Authentik Part 2: Connecting Apps – Forward Auth & OIDC

Authentik is running – now comes the part that justifies the effort: the services behind it. There are exactly two routes, and the choice depends solely on whether the application understands SSO itself.

What are we building?

We attach two services, each the appropriate way:

• Forward auth for an application without its own login. Traefik asks Authentik before every request whether the visitor is signed in. If not, they land on the Authentik login page; if they are, the application receives their identity as HTTP headers.
• OpenID Connect (OIDC) for applications with SSO support – Grafana, Nextcloud, Forgejo, Immich and many others. There you enter client ID, secret and the endpoints, and the app does the rest.

Everything below was carried out with Authentik 2026.8 behind Traefik v3.7 on Debian 13: at the end the test service shows the forwarded identity headers, and the OIDC discovery document returns real endpoints.

Which route for which service?

The decision is almost always clear-cut:

In short: OIDC where possible, forward auth where necessary. OIDC gives the application a real user account including roles; forward auth only puts a door in front of it and passes a name through in a header.

Prerequisites

• A running Authentik from part 1, reachable at https://YOUR_DOMAIN
• A Traefik v3 with a proxy network (guide) – we work a lot with middlewares here, the basics are in hardening Traefik
• A service to practise on. We use traefik/whoami because it echoes every header it receives – which makes it immediately obvious whether the integration really works

Step by step

1. Access for automation: an API token

Providers and applications can be created entirely through the API – handy, because it makes your work reproducible instead of click-based. For that, Authentik needs a token.

Because you went through the setup wizard in part 1, akadmin already exists. So you create the token in the interface: Directory → Tokens and App passwords → Create token. Use a descriptive identifier (api-setup), set the intent to API and the user to akadmin. After saving, copy the key via the copy icon – it is shown only once.

docker compose run --rm server hash_password

  worker:
    environment:
      AUTHENTIK_BOOTSTRAP_PASSWORD_HASH: ${AK_BOOTSTRAP_PASSWORD_HASH}
      AUTHENTIK_BOOTSTRAP_TOKEN: ${AK_BOOTSTRAP_TOKEN}
      AUTHENTIK_BOOTSTRAP_EMAIL: you@YOUR_DOMAIN

Verify the token – no matter which route produced it:

curl -s -H "Authorization: Bearer YOUR_LONG_RANDOM_TOKEN" \
  https://YOUR_DOMAIN/api/v3/core/users/me/

{"user":{"username":"akadmin", … "is_superuser":true, …}}

2. Route A: forward auth for services without a login

The proxy provider is Authentik’s answer to „this app has no user management at all". It comes in several modes; we use forward_single: one application, one provider.

First the IDs of the two default flows (known from part 1):

API=https://YOUR_DOMAIN/api/v3
TOK="Authorization: Bearer YOUR_LONG_RANDOM_TOKEN"

AUTHZ=$(curl -s -H "$TOK" "$API/flows/instances/?slug=default-provider-authorization-implicit-consent" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['results'][0]['pk'])")
INVAL=$(curl -s -H "$TOK" "$API/flows/instances/?slug=default-provider-invalidation-flow" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['results'][0]['pk'])")

Then the provider:

curl -s -X POST -H "$TOK" -H "content-type: application/json" "$API/providers/proxy/" -d "{
  \"name\": \"whoami-forwardauth\",
  \"authorization_flow\": \"$AUTHZ\",
  \"invalidation_flow\": \"$INVAL\",
  \"mode\": \"forward_single\",
  \"external_host\": \"https://YOUR_DOMAIN\"
}"

And the application that uses it – it also creates the tile in the user library:

curl -s -X POST -H "$TOK" -H "content-type: application/json" "$API/core/applications/" -d '{
  "name": "whoami (protected)", "slug": "whoami", "provider": 1
}'

The 1 is the pk from the provider call’s response. Both then appear in the overview:

3. Arm the outpost – and the most common trap

A proxy provider does not work alone: an outpost serves it. Authentik ships an embedded outpost that runs inside the server container – you only have to assign the provider to it:

OUT=$(curl -s -H "$TOK" "$API/outposts/instances/" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['results'][0]['pk'])")
curl -s -X PATCH -H "$TOK" -H "content-type: application/json" \
  "$API/outposts/instances/$OUT/" -d '{"providers": [1]}'

curl -s -X PATCH -H "$TOK" -H "content-type: application/json" \
  "$API/outposts/instances/$OUT/" \
  -d '{"config": {"authentik_host": "https://YOUR_DOMAIN/"}}'

4. Traefik: the forward auth middleware

Now the connection is missing. Traefik asks the outpost before each request – that is what the forwardauth middleware does. On the protected service:

  whoami:
    image: traefik/whoami:v1.12
    restart: unless-stopped
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`YOUR_DOMAIN`) && PathPrefix(`/whoami`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls.certresolver=le"
      - "traefik.http.routers.whoami.middlewares=ak-auth"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"
      - "traefik.http.middlewares.ak-auth.forwardauth.address=http://server:9000/outpost.goauthentik.io/auth/traefik"
      - "traefik.http.middlewares.ak-auth.forwardauth.trustForwardHeader=true"
      - "traefik.http.middlewares.ak-auth.forwardauth.authResponseHeaders=X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid"

The three decisive lines:

• address points at the outpost – here through the service name server (Authentik reaches it under this alias on the Docker network) on the shared Docker network, so without a detour over the internet. The path /outpost.goauthentik.io/auth/traefik is the Traefik-specific check endpoint.
• trustForwardHeader=true passes the X-Forwarded-* headers along so Authentik knows the originally requested address and can redirect back correctly.
• authResponseHeaders is the actual benefit: Traefik copies these headers from Authentik’s response into the request to your application. Without that line the service is protected but has no idea who is there.

5. Verify that it really protects

First without a login – curl is enough:

curl -s -o /dev/null -w "%{http_code} → %{redirect_url}\n" https://YOUR_DOMAIN/whoami

302 → https://YOUR_DOMAIN/application/o/authorize/?client_id=…&redirect_uri=…%2Foutpost.goauthentik.io%2Fcallback…

A 302 to the Authentik login is the desired result. In the browser the login page appears before the service:

After logging in you are back at /whoami – and the service shows what it receives:

GET /whoami HTTP/1.1
Host: YOUR_DOMAIN
X-Authentik-Email: you@YOUR_DOMAIN
X-Authentik-Groups: authentik Admins
X-Authentik-Name: authentik Default Admin
X-Authentik-Uid: d216e191a6f972c39931a005a7998a68…
X-Authentik-Username: akadmin
X-Forwarded-Proto: https

That is the whole trick: the application has not a single line of login code – and still knows who is sitting in front of it. Services that support header authentication (Grafana with auth.proxy, Paperless, Forgejo with reverse-proxy auth) can turn that straight into a session.

6. Know the limits of forward auth

Before you put everything behind forward auth: the mechanism assumes a browser. An unauthenticated request gets a 302 redirect to a login form – and that is exactly what breaks anything that is not a browser:

• Mobile apps (Nextcloud, Immich, Audiobookshelf) cannot do anything with the redirect. They see HTML instead of JSON and report „server unreachable". For such services OIDC is the only sensible route – or you exempt the app’s paths deliberately.
• API access and scripts (curl, backup jobs, webhooks) run into nothing. Wherever a service is addressed by token, that path has to bypass the middleware – or you move the protection to an IP allowlist.
• WebDAV and sync clients behave like APIs, with the same outcome.

For such exceptions you create a second router without the auth middleware that serves only the necessary path – and protect it differently, for example with the application’s own token. Example for an API path:

      - "traefik.http.routers.app-api.rule=Host(`YOUR_DOMAIN`) && PathPrefix(`/api`)"
      - "traefik.http.routers.app-api.entrypoints=websecure"
      - "traefik.http.routers.app-api.tls.certresolver=le"
      - "traefik.http.routers.app-api.middlewares=rate@file"

For completeness, the third mode of the proxy provider: forward_domain. With it one outpost serves all services of a domain (*.YOUR_DOMAIN), and users sign in once for all of them. That is the more convenient setup from roughly three services onwards, but it requires Authentik and all applications to live under the same parent domain so the session cookie can be shared. What is tested here is forward_single – switching only affects the provider’s mode and the cookie domain.

7. Route B: OpenID Connect for services with their own SSO

If the application has an OIDC login, that is the better route: it then keeps real user accounts including roles instead of just seeing a name in a header.

Create the provider – what matters is the redirect URI, which must match the application’s callback address exactly (Grafana as an example):

curl -s -X POST -H "$TOK" -H "content-type: application/json" "$API/providers/oauth2/" -d "{
  \"name\": \"grafana-oidc\",
  \"authorization_flow\": \"$AUTHZ\",
  \"invalidation_flow\": \"$INVAL\",
  \"client_type\": \"confidential\",
  \"redirect_uris\": [{\"matching_mode\": \"strict\", \"url\": \"https://GRAFANA_DOMAIN/login/generic_oauth\"}]
}"

The response contains client_id and client_secret – you need both in the application. Then create an application pointing at this provider, as above.

Whether everything lines up is revealed by the discovery document. Authentik publishes it per application under its slug:

curl -s https://YOUR_DOMAIN/application/o/grafana/.well-known/openid-configuration \
  | python3 -m json.tool | head -12

"issuer": "https://YOUR_DOMAIN/application/o/grafana/",
"authorization_endpoint": "https://YOUR_DOMAIN/application/o/authorize/",
"token_endpoint": "https://YOUR_DOMAIN/application/o/token/",
"userinfo_endpoint": "https://YOUR_DOMAIN/application/o/userinfo/",

Note: the issuer is application-specific (it contains the slug), while the remaining endpoints are the same for all applications. Exactly these addresses – or the discovery URL itself if the app supports it – go into the application. For Grafana, for instance:

GF_AUTH_GENERIC_OAUTH_ENABLED=true
GF_AUTH_GENERIC_OAUTH_NAME=Authentik
GF_AUTH_GENERIC_OAUTH_CLIENT_ID=YOUR_CLIENT_ID
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET
GF_AUTH_GENERIC_OAUTH_SCOPES=openid profile email
GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://YOUR_DOMAIN/application/o/authorize/
GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://YOUR_DOMAIN/application/o/token/
GF_AUTH_GENERIC_OAUTH_API_URL=https://YOUR_DOMAIN/application/o/userinfo/

8. Who may do what? Restricting access

As long as no policy is attached to an application, every signed-in user may use it. For the normal case you bind a group to the application: Applications → your application → policy / group / user bindings, then pick the group.

Only after that does the tile disappear from the user library for everyone else – and access is blocked. The most honest way to verify is with a second test account that is not in the group: it should neither see nor be able to open the application.

When things go wrong

Your problem is not listed? Search all error messages →

Maintenance & backups

Spot-check after every Authentik update. An update can change flows and providers; the integrations themselves are robust, but the quick test is worth it: curl on the protected path must still return 302, and the discovery document must show your endpoints. Two commands that keep a login from being silently broken for weeks.

Client secrets belong in the password manager. They live in the application (environment variables) and in Authentik. If one is regenerated, the other side has to follow – note down which app uses which secret when you create it, otherwise you will be searching in both systems later.

The database matters even more now. Providers, applications and group bindings all live in PostgreSQL. The pg_dump from part 1 is no longer a nice-to-have: without it you rebuild every integration after an outage. Back it up daily with Restic.

Keep the emergency exit open. Every service behind forward auth is only as reachable as Authentik. Keep a local account in important applications – and put no tools behind SSO that you need for repairs; that applies especially to Dockge and similar management interfaces. Monitoring on /-/health/ready/ notices the outage before your users do.

Tidy up tokens. The bootstrap token from step 1 is an admin access without a second factor. Once the setup is in place, delete it under Directory → Tokens – and create a dedicated token with limited rights for later automation.