Initial commit: cleaned project structure
- Consolidated documentation from Ralph Loop iterations - Archived 20+ outdated/superseded files to .archive/ - Kept essential docs: OIDC integration, mobile setup, quick start - Added operational scripts for health monitoring and backup - Research artifacts preserved in .tasks/artifacts/ Current state: - 3 VPS sites (fry, proton, photon) ONLINE in Pangolin - brn-home site pending for local services (Jellyfin, etc.) - Mobile access configuration pending Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
204
AUTHENTIK-SETUP-GUIDE.md
Normal file
204
AUTHENTIK-SETUP-GUIDE.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user