Files
StarPunk/docs/decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md
PhilandClaude Opus 5.5 b84cf23e1a feat!: OIDC admin login and built-in IndieAuth server (v2.0.0)
Admin login now uses OpenID Connect (PKCE, nonce, ID token verified
against the provider JWKS) and only OIDC_ADMIN_SUB may log in. Micropub
tokens are issued and verified by StarPunk itself, with a consent screen
behind the OIDC session and a Connected Apps page to revoke them, so an
external IndieAuth server (Gondulf) is no longer needed.

Existing notes, media, tags, webmentions, author profile and sessions
are unchanged. Migration 011 adds new tables only.

BREAKING CHANGE: production requires OIDC_ISSUER, OIDC_CLIENT_ID,
OIDC_CLIENT_SECRET and OIDC_ADMIN_SUB. The ADMIN_ME page must point
Micropub apps at StarPunk's IndieAuth endpoints. See ADR-064.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 11:38:27 -06:00

3.3 KiB

ADR-064: OIDC Admin Login and Built-in IndieAuth Server

Status

Accepted (v2.0.0, 2026-10-31)

Supersedes the login parts of ADR-021, ADR-025, ADR-027 and ADR-043, and the external token verification of ADR-030 and ADR-036.

Context

Up to v1.6.0 StarPunk was an IndieAuth client. Admin login discovered an authorization endpoint from ADMIN_ME and used the authentication-only flow; Micropub verified bearer tokens by calling the token endpoint discovered from ADMIN_ME. In practice both pointed at Gondulf, a separate self-hosted IndieAuth server.

The operator now runs Pocket ID (OIDC, passkeys) for every other self-hosted service and wants StarPunk to use it too. Pocket ID cannot act as an IndieAuth server: IndieAuth clients identify themselves by URL (client_id = their homepage) and are not pre-registered, while OIDC clients must be registered with the provider.

Micropub apps such as Quill and Indigenous only speak IndieAuth, so moving login to OIDC alone would end Micropub posting.

Decision

  1. Admin login uses OIDC (authorization code flow, PKCE S256, nonce). StarPunk is a confidential client. The ID token's signature (provider JWKS), iss, aud, exp and nonce are verified, and only the configured OIDC_ADMIN_SUB may log in. A successful login creates the same local session as before, for ADMIN_ME.
  2. StarPunk becomes its own IndieAuth server for Micropub clients: /.well-known/oauth-authorization-server, /auth/authorize (consent screen, admin session required, so approval is protected by OIDC), /auth/token and /auth/revoke. Only response_type=code with PKCE S256 is supported. Tokens are stored as SHA-256 hashes and verified locally by /micropub and /media.
  3. ADMIN_ME stays as the site owner's identity URL: it is the author h-card source and the me in issued tokens. That page must advertise StarPunk's IndieAuth metadata (or authorization_endpoint / token_endpoint links) so Micropub apps discover StarPunk.
  4. New tables (oidc_login_state, indieauth_codes, indieauth_tokens, migration 011). The legacy auth_state, tokens and authorization_codes tables are not reused because migration 004 drops the last two after INITIAL_SCHEMA_SQL creates them.
  5. Client redirect_uri must share the client_id origin, or be published by the client (JSON redirect_uris or rel="redirect_uri"). The fetch reuses the webmention SSRF guard.

Consequences

  • Gondulf is no longer needed and can be retired.
  • Existing admin sessions stay valid (sessions are keyed by ADMIN_ME, which does not change). Notes, media, tags and webmentions are untouched.
  • Micropub apps must be re-authorized once, since their old tokens were issued by Gondulf. Tokens are visible and revocable at /admin/tokens.
  • Production requires OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ADMIN_SUB. INDIELOGIN_URL and TOKEN_ENDPOINT are ignored.
  • New dependency: PyJWT[crypto].
  • Major version bump (2.0.0): configuration and endpoint discovery change incompatibly.

Alternatives Considered

  • Keep Gondulf for Micropub only: two auth systems to run and patch.
  • Drop Micropub: simplest, but loses posting from apps.
  • Manually created API tokens: Quill and most apps require IndieAuth.