PLAN: Authentik SSO Setup

Executive Summary

╔══════════════════════════════════════════════════════════════════════╗
║                                                                      ║
║    █████╗ ██╗   ██╗████████╗██╗  ██╗███████╗███╗   ██╗████████╗    ║
║   ██╔══██╗██║   ██║╚══██╔══╝██║  ██║██╔════╝████╗  ██║╚══██╔══╝    ║
║   ███████║██║   ██║   ██║   ███████║█████╗  ██╔██╗ ██║   ██║       ║
║   ██╔══██║██║   ██║   ██║   ██╔══██║██╔══╝  ██║╚██╗██║   ██║       ║
║   ██║  ██║╚██████╔╝   ██║   ██║  ██║███████╗██║ ╚████║   ██║       ║
║   ╚═╝  ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝   ╚═╝    ║
║                                                                      ║
║   S S O   I M P L E M E N T A T I E   P L A N                      ║
║                                                                      ║
║   Magic e-VERSE Identity & Access Management                        ║
║   Authentik as Centralized SSO Provider                             ║
║                                                                      ║
║   Status:     SHELVED (Reference only)                               ║
║                                                                      ║
╚══════════════════════════════════════════════════════════════════════╝

Het Magic e-VERSE ecosysteem bevat tientallen services (admin panels, portal, PIM, NextCloud, N8N, monitoring, etc.) die momenteel elk hun eigen authenticatie hebben. Dit plan beschrijft de implementatie van Authentik als gecentraliseerde SSO identity provider, waarmee alle interne services via één login toegankelijk worden.

---

Doelen

• Eén login voor alle Magic e-VERSE interne services
• Centraal gebruikersbeheer (onboarding/offboarding in één plek)
• 2FA/MFA afdwingen voor alle admin-toegang
• Role-Based Access Control (RBAC) per service en per tenant
• Audit logging van alle login-activiteiten
• Forward Auth / Proxy Auth voor services die geen native SSO ondersteunen

---

Architectuur Overzicht

                    ┌──────────────────────────────┐
                    │        Nginx Reverse Proxy     │
                    │        (Port 80/443)           │
                    └──────────────┬─────────────────┘
                                   │
                    ┌──────────────▼─────────────────┐
                    │         Authentik               │
                    │   auth.magiceverse.online       │
                    │                                 │
                    │  ┌───────────┐ ┌────────────┐  │
                    │  │  Server   │ │  Worker    │  │
                    │  │  :9000    │ │  (async)   │  │
                    │  └───────────┘ └────────────┘  │
                    │  ┌───────────┐ ┌────────────┐  │
                    │  │ PostgreSQL│ │   Redis    │  │
                    │  │  :5432    │ │  :6379     │  │
                    │  └───────────┘ └────────────┘  │
                    └──────────────┬─────────────────┘
                                   │
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
   ┌──────▼──────┐         ┌──────▼──────┐         ┌──────▼──────┐
   │  OAuth2/OIDC │         │ Forward Auth │         │  SAML/LDAP  │
   │  (Native)    │         │ (Proxy)      │         │  (Legacy)   │
   │              │         │              │         │              │
   │ - NextCloud  │         │ - Admin      │         │ - Toekomst  │
   │ - N8N        │         │   Panels     │         │              │
   │ - Grafana    │         │ - Glances    │         │              │
   │ - Portal     │         │ - DevDocs    │         │              │
   │              │         │ - Monitoring │         │              │
   └──────────────┘         └──────────────┘         └──────────────┘

---

Fase 1: Authentik Deployment

1.1 Docker Compose Setup

Authentik draait als Docker stack naast de bestaande containers.

Locatie: /mnt/data/magic_omniverse/magic_authentik/

docker-compose.yml

services:
  authentik-postgresql:
    image: docker.io/library/postgres:16-alpine
    container_name: authentik_postgres
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 5s
    volumes:
      - authentik_database:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${PG_PASS:?database password required}
      POSTGRES_USER: ${PG_USER:-authentik}
      POSTGRES_DB: ${PG_DB:-authentik}

  authentik-redis:
    image: docker.io/library/redis:alpine
    container_name: authentik_redis
    command: --save 60 1 --loglevel warning
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 3s
    volumes:
      - authentik_redis:/data

  authentik-server:
    image: ghcr.io/goauthentik/server:2026.2.1
    container_name: authentik_server
    restart: unless-stopped
    command: server
    environment:
      AUTHENTIK_REDIS__HOST: authentik-redis
      AUTHENTIK_POSTGRESQL__HOST: authentik-postgresql
      AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
      AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
    volumes:
      - ./media:/media
      - ./custom-templates:/templates
    ports:
      - "9000:9000"   # HTTP
      - "9443:9443"   # HTTPS
    depends_on:
      authentik-postgresql:
        condition: service_healthy
      authentik-redis:
        condition: service_healthy

  authentik-worker:
    image: ghcr.io/goauthentik/server:2026.2.1
    container_name: authentik_worker
    restart: unless-stopped
    command: worker
    environment:
      AUTHENTIK_REDIS__HOST: authentik-redis
      AUTHENTIK_POSTGRESQL__HOST: authentik-postgresql
      AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
      AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
    user: root
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./media:/media
      - ./certs:/certs
      - ./custom-templates:/templates
    depends_on:
      authentik-postgresql:
        condition: service_healthy
      authentik-redis:
        condition: service_healthy

volumes:
  authentik_database:
    driver: local
  authentik_redis:
    driver: local

1.2 Environment File

.env

PG_PASS=<generate-secure-password>
PG_USER=authentik
PG_DB=authentik
AUTHENTIK_SECRET_KEY=<generate-with: openssl rand 60 | base64>
# AUTHENTIK_ERROR_REPORTING__ENABLED=true  # Optioneel

1.3 Nginx Configuratie

Bestand: /etc/nginx/sites-enabled/auth.magiceverse.online

server {
    listen 443 ssl http2;
    server_name auth.magiceverse.online;

    ssl_certificate /etc/letsencrypt/live/auth.magiceverse.online/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.magiceverse.online/privkey.pem;

    location / {
        proxy_pass http://localhost:9000;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

server {
    listen 80;
    server_name auth.magiceverse.online;
    return 301 https://$host$request_uri;
}

1.4 DNS Record

auth.magiceverse.online  →  A record naar server IP

1.5 SSL Certificaat

sudo certbot certonly --nginx -d auth.magiceverse.online

Tip

Na het starten van Authentik, is de setup wizard beschikbaar op https://auth.magiceverse.online/if/flow/initial-setup/. Hier stel je het admin account in.

---

Fase 2: Authentik Basisconfiguratie

2.1 Gebruikersgroepen Aanmaken

Groep	Beschrijving	Toegang
admins	Systeembeheerders (Wayne, Michiel)	Alle services
developers	Ontwikkelaars	Admin panels, DevDocs, N8N, Portal
tenant-managers	Tenant beheerders	Specifieke tenant admin panels
viewers	Alleen-lezen toegang	Portal, DevDocs

2.2 Gebruikers Aanmaken

Authentik ondersteunt meerdere bronnen:

• Lokale gebruikers (handmatig aangemaakt)
• Invitations (email-gebaseerde uitnodigingen)
• Eventueel later: LDAP/AD koppeling

2.3 MFA/2FA Afdwingen

1. Ga naar Flows & Stages → Stages → maak een Authenticator Validation Stage
2. Configureer TOTP (Google Authenticator/Authy) als primaire methode
3. Optioneel: WebAuthn (hardware keys) als tweede optie
4. Voeg de MFA stage toe aan de default-authentication-flow
5. Stel een enrollment policy in die MFA verplicht voor de admins en developers groepen

---

Fase 3: Service Integraties

3.1 Services met Native OAuth2/OIDC Support

Deze services ondersteunen OAuth2/OIDC out-of-the-box en worden direct gekoppeld aan Authentik.

NextCloud (docs.magiceverse.online)

1. In Authentik: maak een OAuth2/OpenID Provider aan
   • Client ID: nextcloud
   • Redirect URI: https://docs.magiceverse.online/apps/sociallogin/custom_oidc/authentik
   • Scopes: openid profile email
2. In Authentik: maak een Application aan gekoppeld aan deze provider
3. In NextCloud: installeer de Social Login app
4. Configureer een Custom OpenID Connect provider:
   • Discover URL: https://auth.magiceverse.online/application/o/nextcloud/.well-known/openid-configuration
   • Client ID / Secret van Authentik

N8N Workflow (n8n.magiceverse.online, n8n2, n8n3)

1. In Authentik: maak een OAuth2/OpenID Provider per N8N instance (of gedeeld)
   • Redirect URIs: https://n8n.magiceverse.online/rest/oauth2-credential/callback
2. In N8N environment variables toevoegen:

   N8N_AUTH_TYPE=oidc
   N8N_OIDC_CLIENT_ID=n8n
   N8N_OIDC_CLIENT_SECRET=<secret>
   N8N_OIDC_ISSUER=https://auth.magiceverse.online/application/o/n8n/

3. N8N containers herstarten

Magic Portal (portal.magiceverse.online)

1. In Authentik: maak een OAuth2/OpenID Provider aan voor de Portal
2. In de Portal Vite+React app: integreer een OAuth2/OIDC client library
3. Login flow aanpassen:
   • “Login met Magic e-VERSE SSO” knop toevoegen
   • Token validatie via Authentik’s JWKS endpoint
   • Bestaande device-auth kan naast SSO blijven draaien (migratie periode)

3.2 Services via Forward Auth (Proxy)

Services zonder native SSO-support worden beschermd via Authentik’s Forward Auth (nginx auth_request).

Hoe Forward Auth Werkt

Browser → Nginx → auth_request naar Authentik → Authentik controleert sessie
                                                  ├── Sessie geldig → Nginx proxy_pass naar service
                                                  └── Geen sessie → Redirect naar Authentik login

Authentik Proxy Provider Setup

1. In Authentik: maak een Proxy Provider aan (Forward Auth mode)
   • External host: de URL van de te beschermen service
   • Kies Forward auth (single application) mode
2. Maak een Application aan gekoppeld aan deze proxy provider
3. Configureer de Outpost (Embedded Outpost gebruiken voor eenvoud)

Nginx Forward Auth Snippet

Maak een herbruikbaar Nginx snippet:

Bestand: /etc/nginx/snippets/authentik-auth.conf

# Authentik Forward Auth
location /outpost.goauthentik.io {
    internal;
    proxy_pass              http://localhost:9000/outpost.goauthentik.io;
    proxy_pass_request_body off;
    proxy_set_header        Content-Length "";
    proxy_set_header        X-Original-URL $scheme://$http_host$request_uri;
    proxy_set_header        Host $http_host;
    proxy_set_header        X-Forwarded-Proto $scheme;
    proxy_set_header        X-Forwarded-Host $http_host;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
}

# Redirect to login on 401
location @goauthentik_proxy_signin {
    internal;
    add_header Set-Cookie $auth_cookie;
    return 302 /outpost.goauthentik.io/start?rd=$request_uri;
}

Belangrijk: In de location / block gebruik je auth_request /outpost.goauthentik.io/auth/nginx; (met /auth/nginx suffix).

Per Service Nginx Config Aanpassing

Voorbeeld voor Glances (glances.magiceverse.online):

server {
    listen 443 ssl http2;
    server_name glances.magiceverse.online;

    ssl_certificate /etc/letsencrypt/live/glances.magiceverse.online/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/glances.magiceverse.online/privkey.pem;

    include /etc/nginx/snippets/authentik-auth.conf;

    location / {
        auth_request /outpost.goauthentik.io/auth/nginx;
        auth_request_set $auth_cookie $upstream_http_set_cookie;
        error_page 401 = @goauthentik_proxy_signin;

        # Headers met user info van Authentik
        auth_request_set $authentik_username $upstream_http_x_authentik_username;
        auth_request_set $authentik_groups $upstream_http_x_authentik_groups;
        auth_request_set $authentik_email $upstream_http_x_authentik_email;

        proxy_set_header X-authentik-username $authentik_username;
        proxy_set_header X-authentik-groups $authentik_groups;
        proxy_set_header X-authentik-email $authentik_email;

        proxy_pass http://localhost:<service-port>;
    }
}

3.3 Te Beschermen Services per Methode

Forward Auth (Proxy) Services

Service	Domein	Huidige Auth	Prioriteit
Glances	glances.magiceverse.online	Geen/Basic	Hoog
DevDocs	devdocs.magiceverse.online	Geen	Medium
Escalation	escalation.magiceverse.online	Onbekend	Medium
Contacts	contacts.magiceverse.online	Onbekend	Medium
AI Check	aicheck.magiceverse.online	Onbekend	Medium
Crypto Monitor	crypto.magiceverse.online	Onbekend	Laag

OAuth2/OIDC (Native) Services

Service	Domein	Huidige Auth	Prioriteit
NextCloud	docs.magiceverse.online	Eigen login	Hoog
N8N (3x)	n8n*.magiceverse.online	IP whitelist	Hoog
Portal	portal.magiceverse.online	Device auth	Medium

Medusa Admin Panels (Custom Integratie)

Service	Domein	Aanpak
Admin Development	admin-development.magiceverse.online	Forward Auth of Medusa auth plugin
Admin Brinxx	admin-brinxx.magiceverse.online	Forward Auth of Medusa auth plugin
Admin Default	admin-default.magiceverse.online	Forward Auth of Medusa auth plugin
… (8 tenants)	admin-*.magiceverse.online	Zelfde aanpak voor alle tenants

Caution

Medusa 2.0 admin panels hebben hun eigen JWT-gebaseerde auth. Er zijn twee opties:

1. Forward Auth (sneller te implementeren) — Authentik beschermt de Nginx route, Medusa behoudt eigen auth
2. Custom Medusa Auth Plugin — Diepere integratie, Authentik vervangt Medusa’s eigen auth

Aanbevolen: Start met Forward Auth (dubbele auth-laag) en migreer later naar een custom plugin.

---

Fase 4: Tenant-Based Access Control

4.1 Groep-per-Tenant Structuur

admins                        → Alle services
developers                    → Alle admin panels + dev tools
├── tenant-brinxx             → admin-brinxx + brinxx storefront
├── tenant-logohorloge        → admin-logohorloge + logohorloge storefront
├── tenant-bovisales          → admin-bovisales + bovisales storefront
├── tenant-desluis            → admin-desluis + desluis storefront
├── tenant-jodasign           → admin-jodasign + jodasign storefront
├── tenant-demo               → admin-demo + demo storefront
└── tenant-default            → admin-default + default storefront

4.2 Authentik Policies

Per Application in Authentik een Group Membership Policy instellen:

Application: admin-brinxx
  → Policy: Gebruiker moet lid zijn van "admins" OF "developers" OF "tenant-brinxx"

Application: n8n
  → Policy: Gebruiker moet lid zijn van "admins" OF "developers"

Application: glances
  → Policy: Gebruiker moet lid zijn van "admins"

---

Fase 5: Migratie & Uitfasering Bestaande Auth

5.1 Migratiepad

1. Week 1-2: Authentik deployen + basisconfiguratie (Fase 1 & 2)
2. Week 2-3: Forward Auth inrichten voor eenvoudige services (Glances, DevDocs, etc.)
3. Week 3-4: OAuth2/OIDC koppelen voor NextCloud en N8N
4. Week 4-5: Forward Auth voor Medusa admin panels (dubbele auth-laag)
5. Week 5-6: Portal SSO integratie
6. Week 6+: IP whitelists en device-auth geleidelijk uitfaseren waar SSO overneemt

5.2 Bestaande Auth Behouden (Overgangsperiode)

Tijdens de migratie blijven bestaande authenticatiemethoden werken:

Huidige Methode	Service	Status na SSO
Device Auth	Portal	Blijft naast SSO (later uitfaseren)
IP Whitelist	N8N instances	Verwijderen na SSO + MFA
Basic Auth	Glances	Verwijderen na Forward Auth
Medusa JWT	Admin panels	Blijft (Forward Auth als extra laag)
NextCloud login	NextCloud	Optioneel behouden naast OIDC

Danger

Verwijder NOOIT bestaande authenticatie voordat SSO volledig is getest en werkend! Altijd eerst een overgangsperiode met dubbele auth.

---

Fase 6: Monitoring & Backup

6.1 Authentik Backup

# PostgreSQL backup
docker exec authentik_postgres pg_dump -U authentik authentik > /tmp/authentik_backup_$(date +%Y%m%d).sql

# Media & templates backup
tar -czf /tmp/authentik_media_$(date +%Y%m%d).tar.gz /mnt/data/magic_omniverse/magic_authentik/media/

6.2 Monitoring

• Authentik heeft een ingebouwd Admin Dashboard met login statistieken
• Events log toont alle authenticatie-events, policy decisions, en admin acties
• Koppel eventueel aan bestaande monitoring (Glances/Grafana)

6.3 Health Check

# Check of Authentik draait
curl -s https://auth.magiceverse.online/-/health/ready/

---

Commando Referentie

Initiële Setup

# 1. Directory aanmaken
mkdir -p /mnt/data/magic_omniverse/magic_authentik
cd /mnt/data/magic_omniverse/magic_authentik

# 2. Secret key genereren
echo "AUTHENTIK_SECRET_KEY=$(openssl rand 60 | base64)" >> .env
echo "PG_PASS=$(openssl rand 36 | base64)" >> .env
echo "PG_USER=authentik" >> .env
echo "PG_DB=authentik" >> .env

# 3. Docker compose starten
docker compose up -d

# 4. SSL certificaat
sudo certbot certonly --nginx -d auth.magiceverse.online

# 5. Nginx config activeren
sudo ln -s /etc/nginx/sites-available/auth.magiceverse.online /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Dagelijks Beheer

# Logs bekijken
docker logs authentik_server --tail=50 -f

# Herstarten
cd /mnt/data/magic_omniverse/magic_authentik
docker compose restart

# Updaten
docker compose pull
docker compose up -d

---

Checklist

• DNS record auth.magiceverse.online aanmaken
• Directory /mnt/data/magic_omniverse/magic_authentik/ opzetten
• Docker Compose + .env configureren
• Authentik 2026.2.1 starten + initial setup wizard doorlopen
• SSL certificaat via Let’s Encrypt (verloopt 2026-06-08)
• Nginx reverse proxy configureren
• Gebruikersgroepen aanmaken (admins, developers, tenant-managers, viewers + 7 tenant groepen)
• MFA/TOTP in authentication flow
• Forward Auth snippet aanmaken (/etc/nginx/snippets/authentik-auth.conf)
• Forward Auth inrichten voor Glances
• Forward Auth inrichten voor DevDocs
• Forward Auth inrichten voor Escalation
• Forward Auth inrichten voor Contacts
• Forward Auth inrichten voor AI Check
• Forward Auth inrichten voor Crypto Monitor
• 14 Proxy Providers + Applications aangemaakt
• RBAC policies gebonden (admins, developers, tenant-specifiek)
• OAuth2/OIDC koppeling NextCloud
• OAuth2/OIDC koppeling N8N (3 instances)
• Forward Auth voor Medusa admin panels (Nginx config aanpassing nodig)
• Portal SSO integratie
• Bestaande IP whitelists/device-auth evalueren en uitfaseren
• Backup strategie implementeren
• Team documenteren en trainen