1 files changed, 306 insertions, 0 deletions
diff --git a/authelia/setup.md b/authelia/setup.md
new file mode 100644
index 0000000..9faf7a3
--- /dev/null
+++ b/authelia/setup.md
@@ -0,0 +1,306 @@
+# Authelia Setup Guide
+
+Authelia provides unified authentication (SSO) for all protected services on swave.lol.
+
+**Architecture:**
+- Forward-auth for Netdata, Cockpit (no native auth)
+- Forward-auth + HTTP header injection for Gerrit
+- OIDC provider for Jenkins (full SSO — one login covers Jenkins session)
+- Ghost and cgit remain public (no auth)
+
+---
+
+## 1. DNS record
+
+Add an A record for `auth.swave.lol` pointing to the server IP.
+
+---
+
+## 2. Create host directories
+
+```bash
+mkdir -p /var/authelia/{config,data,redis,secrets}
+```
+
+---
+
+## 3. Generate secrets
+
+Authelia needs 5 secrets. Generate them and write each to a file:
+
+```bash
+# JWT secret (signs short-lived tokens)
+openssl rand -hex 64 > /var/authelia/secrets/jwt_secret
+
+# Session secret (encrypts session cookies)
+openssl rand -hex 64 > /var/authelia/secrets/session_secret
+
+# Storage encryption key (encrypts SQLite DB)
+openssl rand -hex 64 > /var/authelia/secrets/storage_encryption_key
+
+# OIDC HMAC secret (signs OIDC tokens)
+openssl rand -hex 64 > /var/authelia/secrets/oidc_hmac_secret
+
+# OIDC RSA private key (signs OIDC JWTs)
+openssl genrsa -out /var/authelia/secrets/oidc_rsa_key.pem 4096
+
+chmod 600 /var/authelia/secrets/*
+```
+
+---
+
+## 4. Generate Jenkins OIDC client secret
+
+Jenkins needs a plaintext secret (sent in OIDC requests) and the configuration
+needs the argon2id hash of that secret.
+
+```bash
+# Generate a random plaintext secret — save this, you'll enter it in Jenkins UI
+openssl rand -hex 32
+
+# Hash it for authelia config (replace YOUR_PLAINTEXT_SECRET with the value above)
+docker run --rm authelia/authelia:latest \
+  authelia crypto hash generate argon2 --password 'YOUR_PLAINTEXT_SECRET'
+```
+
+Edit `authelia/config/configuration.yml` and replace the placeholder hash under
+`identity_providers.oidc.clients[jenkins].secret` with the argon2id output.
+
+---
+
+## 5. Create users database
+
+```bash
+cp /root/Projects/bastion/authelia/config/users_database.yml.example \
+   /var/authelia/config/users_database.yml
+```
+
+Generate a password hash for each user:
+
+```bash
+docker run --rm authelia/authelia:latest \
+  authelia crypto hash generate argon2 --password 'YOUR_PASSWORD'
+```
+
+Edit `/var/authelia/config/users_database.yml` and fill in the hashes.
+
+---
+
+## 6. Copy Authelia configuration
+
+```bash
+cp /root/Projects/bastion/authelia/config/configuration.yml /var/authelia/config/
+```
+
+---
+
+## 7. Get SSL certificate for auth.swave.lol
+
+Add `-d auth.swave.lol` when running certbot, or if certs already exist, run:
+
+```bash
+cd /root/Projects/bastion/nginx
+bash run_certbot.sh
+```
+
+The `run_certbot.sh` script already includes `auth.swave.lol`. Make sure the DNS
+record from step 1 is propagated before running this.
+
+---
+
+## 8. Start Authelia
+
+```bash
+cd /root/Projects/bastion/authelia
+docker compose up -d
+```
+
+Check logs:
+
+```bash
+docker logs authelia
+```
+
+Authelia is healthy when you see: `Startup complete`
+
+---
+
+## 9. Update nginx config and restart nginx
+
+### 9a. Add Authelia server block
+
+Append the contents of `authelia/nginx-authelia.conf` to `/var/nginx/conf/nginx.conf`.
+
+Also add `auth.swave.lol` to the `server_name` list in the HTTP→HTTPS redirect block:
+
+```nginx
+server_name swave.lol blog.swave.lol ghost.swave.lol jenkins.swave.lol cgit.swave.lol gerrit.swave.lol nexus.swave.lol registry.swave.lol auth.swave.lol;
+```
+
+### 9b. Add auth_request to protected location blocks
+
+For each protected location (Netdata, Cockpit, Gerrit, Jenkins, Nexus, registry),
+add these lines **before** the `proxy_pass` directive:
+
+```nginx
+auth_request /_authelia-auth;
+auth_request_set $authelia_user $upstream_http_remote_user;
+```
+
+For Gerrit locations only, also add the header injection **after** the auth lines:
+
+```nginx
+proxy_set_header X-Forwarded-User $authelia_user;
+```
+
+### 9c. Add the internal auth subrequest location and error handler
+
+In each server block that uses `auth_request`, add these two locations:
+
+```nginx
+location = /_authelia-auth {
+    internal;
+    proxy_pass http://authelia:9091/api/verify;
+    proxy_pass_request_body off;
+    proxy_set_header Content-Length "";
+    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
+    proxy_set_header X-Forwarded-Method $request_method;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $http_host;
+    proxy_set_header X-Forwarded-Uri $request_uri;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+error_page 401 = @authelia_login_redirect;
+location @authelia_login_redirect {
+    return 302 https://auth.swave.lol/?rd=$scheme://$http_host$request_uri;
+}
+```
+
+### 9d. Restart nginx
+
+```bash
+cd /root/Projects/bastion/nginx
+docker compose restart
+```
+
+Or if nginx is already running with the new network:
+
+```bash
+docker exec nginx nginx -s reload
+```
+
+---
+
+## 10. Configure Gerrit HTTP header auth
+
+Edit `/var/gerrit/etc/gerrit.config`. Change the `[auth]` section to:
+
+```ini
+[auth]
+    type = HTTP
+    httpHeader = X-Forwarded-User
+    emailFormat = {0}@swave.lol
+    registerEmailPrivateKey = <output of: openssl rand -hex 20>
+```
+
+Generate the key:
+
+```bash
+openssl rand -hex 20
+```
+
+Restart Gerrit:
+
+```bash
+docker restart gerrit
+```
+
+**Important:** The first user to log in via Authelia becomes Gerrit's administrator.
+Log in immediately after restarting to claim the admin account.
+
+---
+
+## 11. Configure Jenkins OIDC
+
+1. Install the plugin: **Manage Jenkins** > **Plugins** > search `oic-auth`
+   (OpenID Connect Authentication Plugin) > Install
+
+2. Go to **Manage Jenkins** > **Security** > **Security Realm**
+
+3. Select **Login with OpenID Connect**
+
+4. Configure:
+   - **Well-known configuration URL**: `https://auth.swave.lol/.well-known/openid-configuration`
+   - **Client ID**: `jenkins`
+   - **Client Secret**: the plaintext secret from step 4 (not the hash)
+   - **Override scope**: `openid profile email groups`
+
+5. Under **Advanced** > **Username field**: set to `preferred_username`
+
+6. Ensure **Jenkins URL** is set to `https://jenkins.swave.lol/jenkins` in
+   **Manage Jenkins** > **System** > **Jenkins URL**
+
+7. Save and test by logging out and back in.
+
+---
+
+## 12. Enable TOTP two-factor auth (optional, later)
+
+When ready to require 2FA, change `one_factor` to `two_factor` in
+`/var/authelia/config/configuration.yml` for the rules you want to upgrade, then:
+
+```bash
+docker restart authelia
+```
+
+Users will be prompted to enroll their TOTP app on next login.
+
+---
+
+## 13. Set up SMTP notifier (optional, later)
+
+The filesystem notifier writes emails to `/var/authelia/data/notification.txt`.
+To send real emails, replace the `notifier` section in `configuration.yml`:
+
+```yaml
+notifier:
+  smtp:
+    username: your-email@gmail.com
+    password: your-app-password    # or use _FILE env var for secret
+    host: smtp.gmail.com
+    port: 587
+    sender: Authelia <your-email@gmail.com>
+```
+
+Then restart Authelia.
+
+---
+
+## Verification
+
+After completing all steps:
+
+```bash
+# Authelia portal accessible
+curl -I https://auth.swave.lol/
+
+# Netdata redirects to auth portal
+curl -I https://swave.lol/netdata/
+
+# Cockpit redirects to auth portal
+curl -I https://swave.lol/cockpit/
+
+# Gerrit subdomain redirects to auth portal
+curl -I https://gerrit.swave.lol/
+
+# Jenkins subdomain redirects to auth portal
+curl -I https://jenkins.swave.lol/
+
+# Authelia logs show no errors
+docker logs authelia
+```
+
+Log in at `https://auth.swave.lol/` with your credentials from `users_database.yml`.
+After login, Netdata, Cockpit, Gerrit, and Jenkins should be accessible without
+re-entering credentials (single sign-on).