homelab-optimized/docs/services/individual/authentik.md

Authentik - SSO / Identity Provider

Host: Calypso (DS723+)
Domain: sso.vish.gg
Ports: 9000 (HTTP), 9443 (HTTPS)
Compose File: Calypso/authentik/docker-compose.yaml

Overview

Authentik provides Single Sign-On (SSO) and identity management for homelab services. It supports:

• OAuth2 / OpenID Connect
• SAML 2.0
• LDAP
• Proxy authentication (forward auth)
• SCIM provisioning

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Cloudflare DNS                            │
│                      (sso.vish.gg → Calypso)                    │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Synology Reverse Proxy                         │
│              (sso.vish.gg → localhost:9000)                     │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Authentik Stack                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ authentik-   │  │ authentik-   │  │ authentik-   │          │
│  │   server     │◄─┤   worker     │  │    redis     │          │
│  │  (9000)      │  │              │  │              │          │
│  └──────┬───────┘  └──────┬───────┘  └──────────────┘          │
│         │                 │                                      │
│         ▼                 ▼                                      │
│  ┌────────────────────────────────┐                             │
│  │        authentik-db            │                             │
│  │       (PostgreSQL 16)          │                             │
│  └────────────────────────────────┘                             │
└─────────────────────────────────────────────────────────────────┘

Initial Setup

1. Deploy the Stack

Deploy via Portainer GitOps - the stack will auto-pull from the repository.

2. Configure DNS

Add DNS record in Cloudflare:

• Type: A or CNAME
• Name: sso
• Target: Your Calypso IP or DDNS hostname
• Proxy: Orange cloud ON (recommended for DDoS protection)

3. Configure Synology Reverse Proxy

In DSM → Control Panel → Login Portal → Advanced → Reverse Proxy:

Setting	Value
Description	Authentik SSO
Source Protocol	HTTPS
Source Hostname	sso.vish.gg
Source Port	443
Enable HSTS	Yes
Destination Protocol	HTTP
Destination Hostname	localhost
Destination Port	9000

Custom Headers (Add these):

Header	Value
X-Forwarded-Proto	$scheme
X-Forwarded-For	$proxy_add_x_forwarded_for
Host	$host

WebSocket (Enable):

• Check "Enable WebSocket"

4. Initial Admin Setup

1. Navigate to https://sso.vish.gg/if/flow/initial-setup/
2. Create your admin account (default username: akadmin)
3. Set a strong password
4. Complete the setup wizard

Integrating Services

Grafana (gf.vish.gg)

1. In Authentik: Create OAuth2/OIDC Provider

   • Name: Grafana
   • Client ID: (copy this)
   • Client Secret: (generate and copy)
   • Redirect URIs: https://gf.vish.gg/login/generic_oauth

2. In Grafana (grafana.ini or environment):

   [auth.generic_oauth]
   enabled = true
   name = Authentik
   allow_sign_up = true
   client_id = YOUR_CLIENT_ID
   client_secret = YOUR_CLIENT_SECRET
   scopes = openid profile email
   auth_url = https://sso.vish.gg/application/o/authorize/
   token_url = https://sso.vish.gg/application/o/token/
   api_url = https://sso.vish.gg/application/o/userinfo/
   role_attribute_path = contains(groups[*], 'Grafana Admins') && 'Admin' || 'Viewer'
   

Gitea (git.vish.gg)

1. In Authentik: Create OAuth2/OIDC Provider

   • Name: Gitea
   • Redirect URIs: https://git.vish.gg/user/oauth2/authentik/callback

2. In Gitea: Settings → Authentication → Add OAuth2

   • Provider: OpenID Connect
   • Client ID: (from Authentik)
   • Client Secret: (from Authentik)
   • OpenID Connect Auto Discovery URL: https://sso.vish.gg/application/o/gitea/.well-known/openid-configuration

Seafile (seafile.vish.gg)

1. In Authentik: Create OAuth2/OIDC Provider

   • Name: Seafile
   • Redirect URIs: https://seafile.vish.gg/oauth/callback/

2. In Seafile (seahub_settings.py):

   ENABLE_OAUTH = True
   OAUTH_ENABLE_INSECURE_TRANSPORT = False
   OAUTH_CLIENT_ID = 'YOUR_CLIENT_ID'
   OAUTH_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
   OAUTH_REDIRECT_URL = 'https://seafile.vish.gg/oauth/callback/'
   OAUTH_PROVIDER_DOMAIN = 'sso.vish.gg'
   OAUTH_AUTHORIZATION_URL = 'https://sso.vish.gg/application/o/authorize/'
   OAUTH_TOKEN_URL = 'https://sso.vish.gg/application/o/token/'
   OAUTH_USER_INFO_URL = 'https://sso.vish.gg/application/o/userinfo/'
   OAUTH_SCOPE = ['openid', 'profile', 'email']
   OAUTH_ATTRIBUTE_MAP = {
       'id': (True, 'email'),
       'email': (True, 'email'),
       'name': (False, 'name'),
   }
   

Forward Auth (Proxy Provider)

For services that don't support OAuth natively, use Authentik's proxy provider:

1. In Authentik: Create Proxy Provider

   • Name: Protected Service
   • External Host: https://service.vish.gg
   • Mode: Forward auth (single application)

2. In Synology Reverse Proxy: Add auth headers

   • Forward requests to Authentik's outpost first

Backup & Recovery

Data Locations

Data	Path	Backup Priority
Database	/volume1/docker/authentik/database	Critical
Media	/volume1/docker/authentik/media	High
Templates	/volume1/docker/authentik/templates	Medium

Backup Command

# On Calypso via SSH
docker exec Authentik-DB pg_dump -U authentik authentik > /volume1/backups/authentik_$(date +%Y%m%d).sql

Restore

docker exec -i Authentik-DB psql -U authentik authentik < backup.sql

Troubleshooting

Check Logs

docker logs Authentik-SERVER
docker logs Authentik-WORKER

Database Connection Issues

docker exec Authentik-DB pg_isready -U authentik

Reset Admin Password

docker exec -it Authentik-SERVER ak create_recovery_key 10 akadmin

This creates a recovery link valid for 10 minutes.

Security Considerations

• Authentik is the gateway to all services - protect it well
• Use a strong admin password
• Enable 2FA for admin accounts
• Regularly rotate the AUTHENTIK_SECRET_KEY (requires re-authentication)
• Keep the PostgreSQL password secure
• Consider IP restrictions in Cloudflare for admin paths

Related Documentation

• Official Docs
• OAuth2 Provider Setup
• Proxy Provider Setup