Files
pages/docs/design/oidc-verification.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
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.
2026-09-27 14:44:43 +09:00

6.8 KiB
Raw Permalink Blame History

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:

  1. Consume and validate state, browser binding, and unchanged provider identity.
  2. Discover the configured HTTPS issuer and require an exact metadata issuer match. Token, UserInfo, authorization, and JWKS endpoints must be HTTPS.
  3. Exchange the code and require a Bearer access token and a signed ID token.
  4. 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 alg when present. use and key_ops must 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; omitted kid is allowed only with one suitable key.
  5. Require exact issuer, subject, client audience, nonce, and valid integer exp/iat; validate optional nbf, azp, and at_hash. Expired tokens are rejected without grace. Future iat/nbf permit at most 60 seconds of clock skew. The access-token hash uses the verified signature algorithm's SHA-256.
  6. 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 azp matches, 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_uri and supported signing algorithms. Token responses must include Bearer token_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.