path: root/authelia/setup.md

# 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).