Files
pages/docs/design/oidc-verification.md
T
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

118 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation),
with discovery trust rooted in the
[configured issuer metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
Algorithm allowlisting and rejection of ambiguous data implement the relevant
[JWT best-current-practice guidance](https://www.rfc-editor.org/rfc/rfc8725.html).
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.