anchorage/docs/authentik-setup.md

Setting up Authentik OIDC for anchorage

anchorage delegates human authentication to Authentik (or any OIDC provider). The web UI runs an Authorization Code + PKCE flow against Authentik; anchorage validates the returned ID token against Authentik's JWKS and upserts the user on first login. API clients (ipfs pin remote, CI) use per-device JWTs minted by anchorage itself — see auth-flow.md for that side of the story.

This document walks through the Authentik side, end-to-end, and the matching anchorage config.

Tested against Authentik 2024.12+; paths should be the same on any recent 2024.x / 2025.x release.

---

Prerequisites

• A running Authentik instance with admin access.
• A public hostname for anchorage (e.g. https://anchor.example.com) with valid TLS — OIDC requires HTTPS for non-localhost redirect URIs.
• anchorage installed and reachable on that hostname (see ../deploy/README.md).

---

1. Create the OIDC provider

Applications → Providers → Create → OAuth2/OpenID Provider.

Under Protocol settings:

Field	Value	Notes
Name	anchorage-oidc	internal label
Authentication flow	default-authentication-flow	or your org's SSO flow
Authorization flow	default-provider-authorization-implicit-consent	explicit consent also works
Client type	Public	anchorage's web UI is a browser app; no client secret
Client ID	anchorage-web	must match auth.authentik.clientID in anchorage.yaml
Client Secret	(leave empty)	public client + PKCE
Redirect URIs / Origins	https://anchor.example.com/ (one per line; add http://localhost:5173/ etc. for dev)	exact match — including trailing /
Signing Key	authentik Self-signed Certificate (default) or your managed cert	RS256
Subject mode	Based on the User's hashed ID	stable across email changes
Include claims in id_token	✅ enabled	needed so anchorage can read email/groups without a separate /userinfo call
Issuer mode	Each provider has a different issuer	produces https://auth/…/o/<slug>/ — what anchorage expects

Under Scopes, grant:

• openid (mandatory)
• email
• profile
• groups — only if you add the property mapping in §4 below

Save. On the provider's detail page note the OpenID Configuration Issuer URL — it will look like:

https://auth.example.com/application/o/anchorage/

That exact URL (including the trailing slash) goes into auth.authentik.issuer in anchorage.yaml.

---

2. Create the Application

Applications → Applications → Create:

Field	Value
Name	anchorage
Slug	anchorage — must match the /o/<slug>/ in the issuer URL above
Provider	anchorage-oidc (the one from §1)
Launch URL	https://anchor.example.com/
Icon / Group	optional, cosmetic

The slug is load-bearing: changing it later changes the issuer URL and invalidates every outstanding anchorage session.

---

3. Create groups and bind them to the application

anchorage uses two roles that are checked against Authentik group membership (if you wire up §4) or against the bootstrap list in config.

Directory → Groups → Create:

• anchorage-users — ordinary members; can CRUD pins within their org
• anchorage-sysadmins — platform-wide admin rights (drain, maintenance, cross-org audit)

Add users to the appropriate groups. Then bind the groups to the application:

Applications → Applications → anchorage → Policy / Group / User Bindings → Create Binding:

• Bind anchorage-users with Enabled = true, Negate = false
• Bind anchorage-sysadmins with Enabled = true, Negate = false

Unbound Authentik users are now rejected at the Authentik layer before the ID token is ever minted — a defense-in-depth layer for anchorage's own authz.

---

4. (Optional) Property mapping for group-based roles

If you want anchorage to decide sysadmin-ness from Authentik groups rather than the static bootstrap.sysadmins list, add a scope mapping that surfaces groups in the ID token.

Customisation → Property Mappings → Create → Scope Mapping:

Field	Value
Name	anchorage-groups
Scope name	groups
Description	Groups claim for anchorage
Expression	(see below)

return {
    "groups": [g.name for g in request.user.ak_groups.all()],
}

Attach this scope mapping to the provider under Scopes. Verify it works by decoding an issued ID token at https://jwt.io and confirming the groups claim contains anchorage-sysadmins for your admin user.

---

5. Configure anchorage

Open /etc/anchorage/anchorage.yaml and set the auth and bootstrap sections:

auth:
  authentik:
    # Exactly as shown on the Provider's detail page, trailing slash included.
    issuer: https://auth.example.com/application/o/anchorage/
    # Must equal the Client ID configured in Authentik.
    clientID: anchorage-web
    # Authentik puts the client ID in the `aud` claim by default.
    # If you override audience via a property mapping, match it here.
    audience: anchorage-web
  apiToken:
    signingKeys:
      - id: "2026-04"
        path: /etc/anchorage/jwt.key
        primary: true
    defaultTTL: 24h           # web-UI sessions
    maxTTL: 9480h             # 1y + 30-day grace for IPFS client tokens

bootstrap:
  # First Authentik login for one of these emails → user is promoted
  # to sysadmin. Consulted ONLY on first login; later changes need
  # `anchorage admin grant-sysadmin`.
  sysadmins:
    - admin@example.com

Restart anchorage:

systemctl restart anchorage        # package install
# or:
docker service update --force anchorage_anchorage-1   # Swarm

---

6. Verify the flow end-to-end

6a. Reachability — Authentik side

# Discovery document resolves and the issuer matches.
curl -fsS https://auth.example.com/application/o/anchorage/.well-known/openid-configuration \
  | jq '{issuer, jwks_uri, authorization_endpoint, token_endpoint}'

# JWKS is reachable and non-empty.
curl -fsS https://auth.example.com/application/o/anchorage/jwks/ | jq '.keys | length'
# → 1 (or more)

If either call fails, anchorage can't verify ID tokens regardless of the rest. Fix network reachability / TLS / DNS first.

6b. Browser flow — anchorage side

1. Open https://anchor.example.com/ in a browser.
2. Click Sign in → should redirect to https://auth.example.com/application/o/authorize/?client_id=anchorage-web&….
3. Log in at Authentik.
4. You are redirected back to https://anchor.example.com/?code=…&state=….
5. The web UI POSTs the code to /v1/auth/session; anchorage exchanges it with Authentik, validates the ID token, upserts the user, and returns a session cookie.

Check the Postgres row:

psql -c "SELECT id, email, authentik_sub, is_sysadmin, created_at FROM users ORDER BY created_at DESC LIMIT 5;"

You should see your user with authentik_sub = Authentik's hashed user ID and is_sysadmin=true if your email was in bootstrap.sysadmins.

6c. Mint an API token through the UI

Once signed in, exercise the full token lifecycle:

POST /v1/tokens   (with the session cookie)
  body: { "label": "laptop-cli", "scopes": ["pin:write"], "ttl_hours": 720 }

The returned JWT is what goes into ipfs pin remote service add.

---

Troubleshooting

"Invalid redirect URI"

Authentik rejects the authorize request because the redirect_uri query parameter doesn't match any URL in the provider's list.

• Compare byte-for-byte, including trailing /.
• Check protocol (https vs http).
• For local dev, add http://localhost:<port>/ to the provider's list.

"Signature validation failed"

anchorage fetched the JWKS but couldn't verify the ID token.

• Kubernetes NetworkPolicy or egress firewall blocking Authentik? Curl the JWKS endpoint from inside the anchorage pod/container.
• Was the signing key rotated in Authentik? anchorage caches JWKS for 1 hour; restart anchorage or wait for the cache to refresh.

"iss claim invalid"

anchorage's configured issuer doesn't match the iss in the ID token.

• Confirm the provider's Issuer mode is "Each provider has a different issuer" (not the default "global issuer"). The former produces per-application issuers like …/o/anchorage/; the latter produces a bare …/ which won't match.

"aud claim not accepted"

• Authentik's default aud is the Client ID. Set auth.authentik.audience in anchorage.yaml to the same value (typically anchorage-web).
• If you configured a custom audience via a property mapping, set anchorage to match.

Clock skew

JWT validation rejects tokens whose iat is in the future or whose exp has passed. Authentik and anchorage must agree on wall-clock time within ~60s.

• Run NTP / chronyd on both hosts.

First login not promoted to sysadmin

bootstrap.sysadmins matches on the email claim, exact + case- sensitive.

• Check the email Authentik is actually sending: decode the ID token payload and look at the email field.
• bootstrap.sysadmins is only read on the first login for a given authentik_sub. For an existing user, use anchorage admin grant-sysadmin <email> instead.

Users can reach Authentik's login page but get "unauthorized" afterwards

The user isn't a member of a group bound to the anchorage application. Add them to anchorage-users (or the equivalent) and retry.

---

Rotating the Authentik signing certificate

When Authentik rotates its signing cert, outstanding ID tokens keep working until they expire (anchorage trusts JWKS, which lists both old and new keys during overlap). Then:

1. Confirm the new kid is in the JWKS document.
2. anchorage's in-process JWKS cache refreshes every hour; to force a refresh immediately restart the process.

API tokens minted by anchorage are signed with anchorage's own keys (auth.apiToken.signingKeys) and are unaffected by Authentik cert rotation — they only care about the Authentik issuer/audience validity at mint time.