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