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>
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
- Admin login uses OIDC (authorization code flow, PKCE S256, nonce).
StarPunk is a confidential client. The ID token's signature (provider
JWKS),
iss,aud,expandnonceare verified, and only the configuredOIDC_ADMIN_SUBmay log in. A successful login creates the same local session as before, forADMIN_ME. - 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/tokenand/auth/revoke. Onlyresponse_type=codewith PKCE S256 is supported. Tokens are stored as SHA-256 hashes and verified locally by/micropuband/media. ADMIN_MEstays as the site owner's identity URL: it is the author h-card source and themein issued tokens. That page must advertise StarPunk's IndieAuth metadata (orauthorization_endpoint/token_endpointlinks) so Micropub apps discover StarPunk.- New tables (
oidc_login_state,indieauth_codes,indieauth_tokens, migration 011). The legacyauth_state,tokensandauthorization_codestables are not reused because migration 004 drops the last two afterINITIAL_SCHEMA_SQLcreates them. - Client
redirect_urimust share theclient_idorigin, or be published by the client (JSONredirect_urisorrel="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_URLandTOKEN_ENDPOINTare 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.