"We already run Authentik elsewhere — at a different URL, with our existing user base + identity policies. We want PMA's services to authenticate against THAT Authentik, not the one PMA bundles."
Skip the bundled Authentik. Point PMA's services at your external Authentik. The framework's SSO flows work the same way; only the target URL changes.
PMA's bundled Authentik (in the enterprise profile) is convenient for getting started but creates two identity systems if you already run one. The fix: tell PMA to use the external one and skip the bundled one.
What changes:
AUTHENTIK_URL in .env points at your external Authentik (not the tunnel URL of the bundled one).AUTHENTIK_ADMIN_TOKEN (or equivalent API credential) for the external instance.authentik service is dropped from the active profile.What doesn't change: every other service's manifest. Their sso.type: declarations work identically. The framework calls the same SSO flows — they just register OAuth apps in your external Authentik instead of the bundled one.
From the host that will run PMA:
curl -sI https://auth.your-org.com/-/health/ready/
# HTTP/2 204 No Content ← good
If you get 4xx/5xx or DNS failure, fix that before continuing. The bootstrap will fail dramatically if Authentik isn't reachable.
Authentik admin → Directory → Tokens → Create
- Identifier: pma-bootstrap
- User: akadmin (or any user with API access)
- Intent: API
Copy the token value (only shown once).
.env# .env on the PMA host
AUTHENTIK_URL=https://auth.your-org.com
AUTHENTIK_ADMIN_TOKEN=ak_xxxxxxxxxxxxxxxxxxxx
AUTHENTIK_BOOTSTRAP_SKIP=true # tells bootstrap to NOT install the bundled Authentik
Edit services.yaml:
profiles:
enterprise:
services:
# - authentik # ← comment out
- redmine
- mattermost
- n8n
- erpnext
- wikijs
- superset
- grafana
- prometheus
- loki
- postal
Or use the just recipe:
just profile disable authentik
just compose-generate
just bootstrap-local enterprise
# Bootstrap detects AUTHENTIK_BOOTSTRAP_SKIP=true → skips Authentik install
# All other services bootstrap as normal; their SSO flows register OAuth apps
# in your external Authentik.
Watch the output for "[redmine sso] registered OAuth app in https://auth.your-org.com" — proves the flow is using the external instance.
just sso-check
# Walks every service's manifest. For each with sso.type set, checks
# the OAuth app exists in your-external-authentik (not the bundled one),
# redirect URIs match, client secret in .env matches Authentik's view.
Open any service's URL → "Login" → you're redirected to auth.your-org.com (not a PMA-bundled URL) → log in with your existing Authentik credentials → land back authenticated.
PMA runs without its bundled Authentik. Every PMA service delegates auth to your external instance. User provisioning happens in your existing Authentik admin UI; PMA inherits the user base.
Operationally:
just package install <svc> — the SSO flow registers in the external Authentik).Redirect URIs are PMA-host-specific. Each PMA service's OAuth app has a redirect URI like https://<svc>-<id>.<tunnel>/login/oauth2/callback. Your external Authentik registers these per-service. If the tunnel URL changes (or you move PMA to a different host), re-run just sso-fix-all to update.
PMA's bundled n8n workflows may reference the bundled Authentik. Some shipped workflows (e.g. "create user in all services") talk to Authentik via its admin API. They use AUTHENTIK_URL + AUTHENTIK_ADMIN_TOKEN from .env — which now point at the external instance. Should work transparently, but test before relying on them.
Bundled Authentik's database stays on disk if you ever installed it. If you previously bootstrapped with Authentik bundled and want to switch to external, the authentik-postgres volume is still there. just uninstall authentik --force cleans it up (or leave it for rollback safety).
External Authentik upgrades happen on YOUR timetable. PMA's bundled Authentik gets bumped via PMA releases; the external one is your responsibility. Generally fine — Authentik's OAuth/OIDC contract is stable across versions — but document the upgrade dependency.
/pma/learn/04-sso-everywhere.AUTHENTIK_URL to the provider's issuer URL + adjust the bootstrap flow to use that provider's API for app registration (this needs a custom SSO flow script in scripts/sso/setup-<provider>.py)./pma/internals/architecture (planned) covers how the SSO bootstrap is dispatch-based.