root/ubuntu-post-install
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Remove Keycloak; standardize on Authelia for SSO

Browse Source 
Keycloak never reliably ran (fiddly reverse-proxy/hostname config) and the
repo has standardized on Authelia for SSO + 2FA. This rips Keycloak out
entirely:

- Delete the install block, whiptail menu entry, uninstall plumbing, and
  EXISTING_SERVICES detection from both 24.04 and 26.04 scripts
- Delete docker-compose-keycloak.yml, fix-keycloak-proxy.sh, and
  KEYCLOAK-SETUP-GUIDE.md
- Remove the Keycloak block from caddy-setup-helper.sh
- Update docs (CADDY-FAIL2BAN-SETUP.md, SECURITY-IMPROVEMENTS.md,
  NEW-SCRIPT-STRUCTURE.md, SCRIPT-FLOW-INTRO.txt) to reference Authelia

Also documents the fail2ban/Authelia overlap: Authelia handles failed-login
regulation (per-account lockout); the Caddy fail2ban jail is complementary
firewall-level IP banning. Neither does geo-blocking — noted CrowdSec / Caddy
GeoIP as the path for that.

https://claude.ai/code/session_017eA2qqq9jfF2tNtpUYL8vK
This commit is contained in:
Claude
2026-06-03 03:44:26 +00:00
parent c54cd9ecc6
commit f564b4b6d8
10 changed files with 45 additions and 2473 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SECURITY-IMPROVEMENTS.md
+23 -140
View File
@@ -11,7 +11,7 @@ This document describes the comprehensive security and infrastructure improvemen
**Solution:**
- Added `ensure_docker_dir_ownership()` helper function
- Applied to ALL 25+ services (Immich, Keycloak, ActualBudget, Jellyfin, etc.)
- Applied to ALL 25+ services (Immich, ActualBudget, Jellyfin, etc.)
- Fixed disaster recovery path (line 309)
- All Docker directories now properly owned by sudo user
@@ -19,8 +19,8 @@ This document describes the comprehensive security and infrastructure improvemen
---
### 2. Keycloak Security Overhaul
**Problem:** Weak default passwords, special characters causing issues, development mode in production.
### 2. Password & Credential Management
**Problem:** Weak default passwords and credentials hardcoded in compose files.
**Solutions Implemented:**
@@ -30,35 +30,20 @@ This document describes the comprehensive security and infrastructure improvemen
- **Auto-generation:** Press ENTER to generate secure passwords automatically
- **Validation:** Real-time password validation with retry loop
#### Production vs Development Mode
- **Production mode:** Uses `start` command, requires hostname configuration
- **Development mode:** Uses `start-dev` command, relaxed security for testing
- **Hostname support:** Proper `KC_HOSTNAME` configuration for public deployment
#### Generated Secrets
- Services that need cryptographic secrets generate them automatically (e.g. Authelia's JWT, session, and storage secrets via `openssl rand`).
#### Environment Variables
- All credentials moved to `.env` file
- Admin password and database password securely stored
- Passwords and secrets securely stored
- No more hardcoded passwords in docker-compose.yml
**Example Keycloak .env file structure:**
```env
# Keycloak Environment Variables
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=<secure-20-char-password>
POSTGRES_DB=keycloak
POSTGRES_USER=keycloak
POSTGRES_PASSWORD=<secure-32-char-password>
KC_PROXY=edge
KC_HTTP_ENABLED=true
KC_HOSTNAME=auth.yourdomain.com # (if production mode)
```
---
### 3. Environment Variable Management (.env Files)
**Services Now Using .env Files:**
- ✅ Keycloak (admin + database passwords)
- ✅ Authelia (JWT/session/storage secrets + SMTP password)
- ✅ ActualBudget (timezone and config)
- ✅ Immich (already had .env)
- ✅ FindMyDevice (already had .env)
@@ -120,7 +105,7 @@ labels:
**Services with fail2ban monitoring:**
- ActualBudget
- Keycloak
- Authelia
- All other internet-facing services
**fail2ban Configuration:**
@@ -130,7 +115,10 @@ labels:
- Ban duration: 3600 seconds (1 hour)
- Detection window: 600 seconds
**Detailed Setup:** See `CADDY-FAIL2BAN-SETUP.md` for complete configuration.
**Note:** When Authelia is in use, it provides its own failed-login regulation
(account lockout after repeated failures). The Caddy fail2ban jail is
complementary defense-in-depth at the HTTP layer. See
`CADDY-FAIL2BAN-SETUP.md` for complete configuration.
---
@@ -154,7 +142,7 @@ PASSWORD=$(generate_password 20) # 20-character password
```
### `validate_password(password [min_length])`
Validates passwords for Keycloak compatibility.
Validates passwords for compatibility (alphanumeric only).
**Validation Rules:**
- Minimum length (default: 12 characters)
@@ -170,67 +158,9 @@ fi
---
## Keycloak Setup Guide
### For ActualBudget on Pikapods
1. **Install Keycloak with production mode:**
```bash
sudo bash ubuntu-post-install.sh
# Select Keycloak from menu
# Choose production mode (y)
# Enter hostname: auth.yourdomain.com
# Press ENTER to auto-generate secure passwords
```
2. **Configure Caddy2:**
- Script automatically prompts for Caddy configuration
- Enter your domain (e.g., auth.yourdomain.com)
- Ensure DNS A record points to your server
3. **Configure DNS:**
```
auth.yourdomain.com → Your Server IP
```
4. **Access Keycloak:**
```
https://auth.yourdomain.com
```
5. **Set up ActualBudget OAuth:**
- The script automatically creates an OAuth client for ActualBudget
- Client details saved to: `~/docker/keycloak/actualbudget-oauth.txt`
- Use these credentials in your Pikapod ActualBudget instance
6. **Configure ActualBudget on Pikapods:**
- Go to your ActualBudget settings
- Enable OpenID Connect
- Enter your Keycloak details:
- Issuer: `https://auth.yourdomain.com/realms/homelab`
- Client ID: (from actualbudget-oauth.txt)
- Client Secret: (from actualbudget-oauth.txt)
### For Other Self-Hosted Services
The script can create generic OAuth clients for other services. After Keycloak installation, you can:
1. Access Keycloak admin console
2. Create new OAuth2/OIDC clients
3. Configure redirect URIs for your services
4. Use the client credentials in your service configuration
**Generic Client Template:**
- Client ID: your-service-name
- Client Type: Confidential
- Standard Flow Enabled: Yes
- Valid Redirect URIs: https://your-service.com/*
---
## Password Requirements Reference
### Keycloak Passwords
### Password Rules
- **Minimum:** 12 characters
- **Recommended:** 16+ characters
- **Format:** Alphanumeric only (a-zA-Z0-9)
@@ -238,7 +168,9 @@ The script can create generic OAuth clients for other services. After Keycloak i
- **Generation:** Press ENTER for auto-generated secure passwords
### Why No Special Characters?
Keycloak has issues with special characters in certain authentication flows and database connection strings. Restricting to alphanumeric ensures compatibility.
Some services and database connection strings mishandle special characters in
certain authentication flows. Restricting to alphanumeric ensures broad
compatibility while remaining cryptographically strong.
### Password Strength with Alphanumeric Only
- 12 characters: ~62^12 = 3.2 × 10^21 combinations
@@ -264,21 +196,6 @@ docker ps
# Should work without permission errors
```
### Keycloak
```bash
# Check .env file exists
cat ~/docker/keycloak/.env
# Should contain KEYCLOAK_ADMIN_PASSWORD and POSTGRES_PASSWORD
# Check production mode
cat ~/docker/keycloak/docker-compose.yml | grep command
# Should show "start" for production or "start-dev" for development
# Test access
curl http://localhost:8180/health
# Should return health status
```
### Caddy2
```bash
# Check Caddy is running
@@ -316,20 +233,6 @@ If you have existing services:
4. Verify ownership: `ls -la ~/docker/actualbudget`
5. Restart container: `cd ~/docker/actualbudget && docker compose restart`
### Existing Keycloak
1. **IMPORTANT:** Backup your data first!
```bash
cp -r ~/docker/keycloak ~/docker/keycloak.backup
```
2. Stop existing container:
```bash
cd ~/docker/keycloak && docker compose down
```
3. Run updated script and select Keycloak
4. Choose whether to keep existing data or start fresh
5. If keeping data, manually update .env with your existing passwords
6. Restart: `docker compose up -d`
---
## Troubleshooting
@@ -340,19 +243,6 @@ If you have existing services:
sudo chown -R $USER:$USER ~/docker
```
### Keycloak Won't Start
```bash
# Check logs
docker logs keycloak
# Common issues:
# 1. Missing KC_HOSTNAME in production mode
# 2. Database connection failed (check postgres container)
# 3. Port 8180 already in use
# Fix: Edit .env and docker-compose.yml as needed
```
### Caddy Certificate Errors
```bash
# Check Caddy logs
@@ -375,19 +265,17 @@ sudo ufw status
## Security Best Practices
1. **Change default passwords:** Even with auto-generation, review and update if needed
2. **Use production mode for Keycloak:** Never use development mode for internet-facing deployments
3. **Enable fail2ban:** Monitor and ban malicious IPs
4. **Regular updates:** Keep containers updated (use Watchtower in notify mode)
5. **Backup .env files:** Store securely, separate from compose files
6. **Use HTTPS everywhere:** Configure Caddy2 for all public services
7. **Limit exposed ports:** Only expose necessary ports to the internet
8. **Monitor logs:** Regular review of Caddy and fail2ban logs
2. **Enable fail2ban:** Monitor and ban malicious IPs
3. **Regular updates:** Keep containers updated (use Watchtower in notify mode)
4. **Backup .env files:** Store securely, separate from compose files
5. **Use HTTPS everywhere:** Configure Caddy2 for all public services
6. **Limit exposed ports:** Only expose necessary ports to the internet
7. **Monitor logs:** Regular review of Caddy and fail2ban logs
---
## Additional Resources
- **Keycloak Setup Guide:** `KEYCLOAK-SETUP-GUIDE.md`
- **Caddy + fail2ban Setup:** `CADDY-FAIL2BAN-SETUP.md`
- **Main Script:** `ubuntu-post-install.sh`
- **Caddy Helper:** `caddy-setup-helper.sh`
@@ -402,8 +290,3 @@ If you encounter issues:
2. Verify ownership: `ls -la ~/docker`
3. Review this document for troubleshooting steps
4. Check existing documentation in repository
---
**Last Updated:** 2026-01-13
**Script Version:** Latest (with security improvements)