halkyon/docs/adr/0023-openid-connect-module.md

ADR 0023: Signing in with OpenID Connect, a module others can use

• Status: decided 23 Oct 2026, by the developer (D1–D4); the design below is built as ADR 0020's step 2, whose D12 and D13 it carries. halkyon_oidc_flutter built with step 4 (23 Oct, night): OidcBrowser opens an OidcStart's page and returns the code (OidcCode), the provider's refusal (OidcDenied) or nothing (closed), the state checked on the device, as the server never compares it; the way back an OidcReturn (the app's scheme, a verified https address, the loopback). halkyon_app's LoopbackWebAuth moved in, relicensed from AGPL v3 to BSD-3-Clause by its author, the developer, and serves GitHub's sign-in from there until it ends.
• Builds on: ADR 0014 (halkyon_base, the first Serverpod module), ADR 0020 (signing in with SimpleLogin only).

Context

ADR 0020 has learn.halkyon.eu sign people in with SimpleLogin, through OpenID Connect's code flow. Asked on 23 Oct whether that could be "a separate module that others may use as well at their convenience with Serverpod", what Serverpod v4.0.4 offers:

• A contract for providers of one's own: an IdentityProvider, built by an IdentityProviderBuilder the host passes to AuthServices beside the stock ones, an endpoint on IdpBaseEndpoint, an account model linking the provider's ID to Serverpod's AuthUser, and a controller on the device ("Custom providers" in Serverpod's documentation, still being written on 23 Oct). OAuth2PkceUtil exchanges a code, PKCE optional, and is exported.
• No OpenID Connect: no provider for it, no discovery, and no exported check of ID tokens (Google's and Firebase's IdTokenVerifier is internal and refuses tokens without typ, ADR 0020's D12).

Decisions (23 Oct 2026, the developer's)

• D1 OpenID Connect, with a SimpleLogin preset (recommended, over SimpleLogin alone): any provider that follows OpenID Connect's code flow (Keycloak, Authentik, Zitadel, Authelia, Pocket ID, …), which Serverpod lacks; SimpleLogin a preset that knows its ways (no PKCE, no typ). Only SimpleLogin is tried live; the rest is tested to the specification. The packages' names stay generic.
• D2 BSD-3-Clause (recommended, over Apache-2.0, MIT, and AGPL v3 as Halkyon's other packages): Serverpod's own licence, so whoever builds on Serverpod can take it, closed apps too.
• D3 In this repository, published later (recommended, over a repository of its own now, or offering it to Serverpod): under packages/ with publish_to: none, so a change to it and to Halkyon is one commit; to pub.dev once it runs on learn.halkyon.eu, asked again before, as publishing is public.
• D4 Now, as ADR 0020's step 2 (recommended, over moving it out after v0.20.0): the boundary drawn first costs less than pulling Halkyon's code apart later, a table moved between modules included; v0.20.0 comes about a day later.

Design

1. Packages: halkyon_oidc_server, a Serverpod module (nickname oidc), with its generated client halkyon_oidc_client; halkyon_oidc_flutter, the device's half, with ADR 0020's step 4. halkyon_base builds on the module; nothing of Halkyon's is in it.
2. Providers: a host names one or more, each under a key of its own that never changes (simplelogin): the issuer, the endpoints (from the provider's discovery document, checked to name the same issuer, or given), the client's ID and secret, the scopes, PKCE or not, the signing algorithms its tokens may use (RS256 unless said), and the callback address the provider has registered. The SimpleLogin preset fills in all but the client and the callback.
3. What it keeps: a person's identity at a provider, the provider's key and the sub (halkyon_oidc_identity): each sub one person's at a provider, one per person and provider. Nothing of what the token says besides; the claims go to the host's code, which decides (Halkyon drops them, ADR 0020's 4).
4. Attempts (ADR 0020's D13): halkyon_oidc_attempt, the ID PostgreSQL's gen_random_uuid() (122 random bits), the secret only the device holds; the state and the nonce, 32 random bytes each, and PKCE's verifier where used; who began it, if signed in; ten minutes, taken once. The host may begin the state with a marker of its own (ADR 0020's forwarding page reads one).
5. Checking a sign-in (ADR 0020's D12): the code exchanged with the client's secret, by the module itself rather than OAuth2PkceUtil, so that a provider out of reach (no answer in time, a 5xx) is told apart from a refused code; the ID token's header without typ asked for, its algorithm one of the provider's, its key the one its kid names in the provider's keys (kept an hour, fetched again for an unknown kid at most once a minute, every fetch with a timeout); the issuer, the audience (and azp with more than one), the expiry and the time issued, a minute of clocks' difference allowed, the nonce the attempt's.
6. Two ways to use it:
   • The stock way, as Serverpod's providers: the host's endpoint on OidcIdpBaseEndpoint, begin and login: a known sub gets a session, an unknown one a new person; linking to the signed-in caller where the attempt was begun so.
   • The parts, for a host with rules of its own (Halkyon: the register, a handle before an account, ADR 0016 and 0020): begin, verify (the identity proven, and its claims, touching no account), link, accountOf, unlink, called from its own endpoints.
7. The forwarding page goes into the module (addOidcCallbackForwarding), with the targets the host fixes: what ADR 0020's 3 has Halkyon need, a provider that takes https callbacks alone, each registered exactly, others need alike.

Consequences

• Halkyon's sign-in rests on a module of its own making, with its own tests and README, kept usable by others: its interface changes with care once published.
• Serverpod hosts get OpenID Connect; a provider other than SimpleLogin may still need a fix the specification's tests didn't foresee.
• The module's tables are part of every host's migrations, as halkyon_base's are.