pangolin/AUTHENTIK-SETUP-GUIDE.md

# Authentik Initial Setup Guide

**Status:** ⚠️ **ACTION REQUIRED**
**Created:** 2026-01-20 20:59:00+00:00

---

## Step 1: Access Authentik Initial Setup

**URL:** https://sso.obr.sh/if/flow/initial-setup/

Navigate to this URL in your web browser. You should see the Authentik initial setup wizard.

---

## Step 2: Create Admin Account

**Recommended Settings:**
- **Username:** `admin` (or your preferred admin username)
- **Email:** `admin@obr.digital`
- **Password:** *Choose a strong password (20+ characters recommended)*

**Important:**
- This is the **superuser account** for all Authentik administration
- Will be used to create OIDC providers for Pangolin, Guacamole, Jellyfin, etc.
- Cannot be recovered without recovery codes

---

## Step 3: Save Recovery Codes

After creating the admin account, Authentik will display **recovery codes**.

**CRITICAL:** Save these codes in a secure location (password manager, encrypted file)

These codes allow account recovery if you lose access to MFA devices.

---

## Step 4: Enable MFA (Recommended)

After initial setup, configure TOTP (Time-based One-Time Password):

1. Log in to Authentik admin: https://sso.obr.sh/if/admin
2. Navigate to your user profile (top right corner)
3. Click "Authenticators" or "MFA"
4. Add TOTP authenticator (scan QR code with authenticator app)
5. **Save backup codes**

---

## Step 5: Verify Admin Access

Confirm you can:
1. Access Admin Interface: https://sso.obr.sh/if/admin
2. See the Authentik dashboard
3. Navigate to "Applications" section
4. Navigate to "Providers" section

---

## Next Steps (After Admin Setup Complete)

Once admin account is created, the following OIDC providers need to be configured:

### 1. Pangolin OIDC Provider

**Purpose:** Centralized identity-aware access control for tunneled services

**Configuration:**
- Navigate to: **Admin > Applications > Providers**
- Click "Create"
- **Type:** OAuth2/OIDC Provider
- **Name:** `Pangolin SSO Provider`
- **Client Type:** Confidential
- **Client ID:** `pangolin` (will be auto-generated, copy this)
- **Redirect URIs:** `https://tunnel.obr.sh/api/v1/auth/callback`
- **Scopes:** openid, profile, email, groups

**Required Scopes:**
- `openid` - Core identity
- `profile` - User profile information
- `email` - Email address
- `groups` - Group memberships for access control

**Advanced Settings:**
- **Token validity:** 720 minutes (12 hours)
- **Signing Key:** `authentik Self-signed Certificate`

**Save these values:**
- Client ID: _________________
- Client Secret: _________________

### 2. Guacamole OIDC Provider

**Purpose:** SSO for RDP gateway access

**Configuration:**
- **Name:** `Guacamole RDP Gateway`
- **Client Type:** Confidential
- **Redirect URIs:** `https://remote.obr.sh/guacamole/`
- **Scopes:** openid, profile, email
- **Token validity:** 300 minutes (5 hours, Guacamole maximum)

**MFA Policy:**
Create and bind MFA policy to require TOTP for Guacamole application:
- Navigate to: **Admin > Policies**
- Create Expression Policy: "Require TOTP for Guacamole"
- Expression: `return ak_is_group_member(request.user, name="guacamole-admins")`
- Bind to Guacamole application

### 3. Jellyfin OIDC Provider

**Purpose:** SSO for media server (web access only, mobile uses Quick Connect)

**Configuration:**
- **Name:** `Jellyfin Media Server`
- **Client Type:** Confidential
- **Client Authentication Method:** `client_secret_post` (CRITICAL for Jellyfin plugin)
- **Redirect URIs:** `https://video.obnh.io/sso/OID/redirect/Authentik`
- **Scopes:** openid, profile, email, groups

**Create Groups:**
- `jellyfin-admins` - Full admin access
- `jellyfin-users` - Regular user access

### 4. OpenWebUI OIDC Provider

**Purpose:** SSO for AI chat interface

**Configuration:**
- **Name:** `OpenWebUI`
- **Client Type:** Confidential
- **Redirect URIs:** `https://ll.obr.sh/oauth/oidc/callback`
- **Scopes:** openid, profile, email, groups

**Create Groups:**
- `openwebui-admins` - Admin role
- `openwebui-users` - Regular users

**Claims Mapping:**
Configure role claim for admin designation:
- Claim: `groups`
- Mapped to user group memberships

### 5. Gitea OIDC Providers (2 instances)

**Purpose:** SSO for self-hosted Git repositories

**Configuration for gitea-fry:**
- **Name:** `Gitea (fry.obr.sh)`
- **Redirect URIs:** `https://git.obnh.io/user/oauth2/authentik/callback`
- **Scopes:** openid, profile, email

**Configuration for gitea-proton:**
- **Name:** `Gitea (proton.obr.sh)`
- **Redirect URIs:** `https://git.proton.obr.sh/user/oauth2/authentik/callback`
- **Scopes:** openid, profile, email

---

## Verification Checklist

After completing setup:

- [ ] Admin account created and can login
- [ ] Recovery codes saved securely
- [ ] MFA (TOTP) configured (optional but recommended)
- [ ] Can access Admin Interface
- [ ] Ready to create OIDC providers

---

## Troubleshooting

**Cannot access setup page:**
- Verify Authentik containers are healthy: `cd /srv/docker/authentik && sudo docker compose ps`
- Check Traefik routing: `curl -I https://sso.obr.sh`
- Review logs: `sudo docker compose logs server | tail -50`

**Setup page keeps loading:**
- Wait 1-2 minutes for migrations to complete (already done if from Iteration 1)
- Refresh browser
- Clear browser cache

**Lost recovery codes:**
- If you still have access, generate new codes in admin interface
- If locked out, manual database recovery required (contact for assistance)

---

## Security Recommendations

1. **Use a password manager** - Generate and store strong password
2. **Enable MFA immediately** - Don't delay TOTP setup
3. **Save recovery codes offline** - Print or store in encrypted file
4. **Limit admin access** - Only use admin account for configuration
5. **Regular backups** - PostgreSQL database contains all configuration

---

**Once setup complete, notify the system to proceed with Pangolin OIDC provider creation.**

**File Location:** `/home/olaf/pangolin/AUTHENTIK-SETUP-GUIDE.md`