Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
6.8 KiB
OIDC ID-token verification
Implemented: 2026-09-14. This closes the unsigned-ID-token acceptance gap in the authentication backend; it is not a claim that every identity-provider or account-lifecycle feature is complete.
Authentication boundary
/_/auth/oidc and /_/auth/callback/oidc accept GET only. Authorization Code
with PKCE S256 still uses a five-minute, one-use, Domain-scoped DB challenge.
The challenge now also fixes the configured issuer and client ID, and stores
the SHA-256 of a browser-only random secret. A matching HttpOnly, host-only,
SameSite=Lax cookie is mandatory at callback. HTTPS uses the __Host- cookie
prefix, Secure, and / scope; plain HTTP is retained only for existing local
development deployments. Duplicate cookies fail closed. Starting a second
login in the same browser supersedes the first browser challenge.
The callback performs these checks before account binding or session creation:
- Consume and validate state, browser binding, and unchanged provider identity.
- Discover the configured HTTPS issuer and require an exact metadata issuer match. Token, UserInfo, authorization, and JWKS endpoints must be HTTPS.
- Exchange the code and require a Bearer access token and a signed ID token.
- Select a public verification key only from that issuer's discovered JWKS.
Verify RS256 or ES256 using Go's cryptographic standard library. The
algorithm must also be advertised in discovery, match the key type, and
match the JWK
algwhen present.useandkey_opsmust allow verification. RSA modulus sizes are 2048–8192 bits; ES256 requires a valid P-256 point and its 64-byte JOSE signature. Ambiguous matching keys are rejected; omittedkidis allowed only with one suitable key. - Require exact issuer, subject, client audience, nonce, and valid integer
exp/iat; validate optionalnbf,azp, andat_hash. Expired tokens are rejected without grace. Futureiat/nbfpermit at most 60 seconds of clock skew. The access-token hash uses the verified signature algorithm's SHA-256. - Only then fetch UserInfo. Require the same subject and a verified email before resolving the existing external identity or existing local account.
Both lookup routes require active Domain membership. Email fallback must find
exactly one eligible Principal; duplicate matching emails fail closed instead
of choosing an arbitrary UUID. External subject binding uses a conditional
UPSERT: an existing (provider type, provider, issuer, subject) may refresh its
attributes only for the same Principal. A concurrent attempt to bind that
subject to a different Principal is rejected and cannot proceed to session
issuance.
Provider email_verified verifies the provider's claim, not ownership of an
email address previously entered into a local Pages Wiki profile. Local-email
ownership verification and an explicit account-linking approval policy remain
separate requirements; uniqueness checks are not a substitute for them.
These checks follow OpenID Connect Core ID-token validation, with discovery trust rooted in the configured issuer metadata. Algorithm allowlisting and rejection of ambiguous data implement the relevant JWT best-current-practice guidance.
The implementation does not follow token-provided jku, jwk, or x5u to
obtain trust. Unsigned/symmetric tokens, encryption, unencoded JWS payloads,
and critical JOSE extensions are unsupported. Top-level duplicate JSON members
(including case variants used by Go struct decoding) and trailing JSON data
are rejected.
Resource and rotation policy
| Resource | Bound / policy |
|---|---|
| Provider fetch | 5-second total HTTP timeout, including response body |
| Login / callback | Existing 8-second / 10-second request contexts |
| Concurrent external requests | 8 process-wide OIDC slots |
| Production response headers | 64 KiB |
| JSON response | 1 MiB, oversized/truncated input rejected |
| Compact ID token / access token | 64 KiB / 16 KiB |
| Provider cache | LRU-bounded to 64 exact issuers; public data only |
| Signing-key set | At most 128 keys |
| Discovery and JWKS freshness | Locally capped at five minutes |
| Failed discovery / key-fetch retry | No more than once per 30 seconds |
| Signature failure / unknown key | One immediate JWKS refresh, then at most one forced refresh per 30 seconds |
Concurrent requests for one provider share the same retrieval. A newly fetched JWKS replaces the prior set, including removed keys. A failed forced refresh never authenticates the failing token; other tokens may continue using a still-fresh cached key. Expired keys are never used as an outage fallback. With the local five-minute freshness policy, withdrawal of an otherwise valid cached key is not an instantaneous revocation mechanism.
All HTTP redirects are rejected, including token exchange and UserInfo, so a redirect cannot forward a client secret or Bearer token. Provider URLs are administrator-controlled; private HTTPS identity providers remain supported. There is no automatic public-network-only SSRF policy or per-provider CA UI.
Compatibility limits and follow-up
- Only RS256 and ES256 are implemented. PS256, EdDSA, encrypted ID tokens, UserInfo JWTs, and dynamic registration remain separate features.
- The sole trusted audience is the configured client ID. A singleton audience
array is supported; multiple audiences are rejected even when
azpmatches, because no additional-audience trust configuration currently exists. - Exact issuer matching intentionally no longer equates trailing-slash variants. Providers must publish the issuer exactly as configured.
- The discovery document must include
jwks_uriand supported signing algorithms. Token responses must include Bearertoken_type. - Future work: provider-specific registered signing-algorithm selection, additional-audience trust only if a concrete provider requires it, explicit authentication audit/abuse quotas, configurable cache-header handling, and account-linking policy independent of verified-email matching.
- Deployment restarts invalidate the in-memory public-key cache. Login states created before browser/provider binding was added must be restarted.
Verification
go test -race ./internal/server -run '^TestOIDC' -count=1 covers valid RSA and
EC signatures; forged/unsupported/ambiguous signatures; issuer, audience,
nonce, time and access-token-hash failures; key usage/curve constraints; key
rotation and removed keys; refresh coalescing/backoff; cache/response/key-set
bounds; canceled/incomplete response bodies; redirect denial; callback browser
binding and duplicate cookies; provider changes; UserInfo subject mismatches;
successful session issuance; and one-use state replay denial.