Implement GenericOAuth2Backend for any OIDC provider #43

New issue

Open

opened 2026-07-28 04:59:54 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-28 04:59:54 +00:00

Context

Auth currently uses Authlib configured for a single provider. The spec calls for a
GenericOAuth2Backend so any standards-compliant OIDC provider works â€” Authentik is the
documented default, but a deployment should not be tied to it.

Scope

A generic, configuration-driven OAuth2/OIDC backend.

Implementation notes

Drive everything from configuration: authorization endpoint, token endpoint, userinfo
endpoint, scopes, and claim mappings. Prefer OIDC discovery where the provider offers it.
Configurable claim mapping for email, name, and identifier. Providers disagree about
claim names, and hardcoding one provider's shape is what created this issue.
Validate ID tokens properly: signature against the provider's JWKS, issuer, audience,
and expiry. This is the security-critical part â€” a backend that accepts unvalidated
tokens is an authentication bypass, so it must be tested directly, including the
rejection cases.
Preserve first-admin bootstrap behaviour across providers.
Handle provider-specific quirks without leaking them into core auth logic.
Document configuration for at least Authentik and one other provider, verified against
a real instance rather than from documentation alone.
Existing sessions must survive the change, or the upgrade path must be documented.

Done when

Any standards-compliant OIDC provider can be configured without code changes
ID token validation covers signature, issuer, audience, and expiry
Token rejection cases are covered by tests
First-admin bootstrap works across providers
Two providers are documented and verified against real instances

References

backend/app/auth/
docs/circa-spec.md Phase 4, section 4 (auth)

Related: #14 (fail fast on insecure configuration).

## Context Auth currently uses Authlib configured for a single provider. The spec calls for a `GenericOAuth2Backend` so any standards-compliant OIDC provider works â€” Authentik is the documented default, but a deployment should not be tied to it. ## Scope A generic, configuration-driven OAuth2/OIDC backend. ## Implementation notes - Drive everything from configuration: authorization endpoint, token endpoint, userinfo endpoint, scopes, and claim mappings. Prefer OIDC discovery where the provider offers it. - Configurable claim mapping for email, name, and identifier. Providers disagree about claim names, and hardcoding one provider's shape is what created this issue. - Validate ID tokens properly: signature against the provider's JWKS, issuer, audience, and expiry. This is the security-critical part â€” a backend that accepts unvalidated tokens is an authentication bypass, so it must be tested directly, including the rejection cases. - Preserve first-admin bootstrap behaviour across providers. - Handle provider-specific quirks without leaking them into core auth logic. - Document configuration for at least Authentik and one other provider, verified against a real instance rather than from documentation alone. - Existing sessions must survive the change, or the upgrade path must be documented. ## Done when - [ ] Any standards-compliant OIDC provider can be configured without code changes - [ ] ID token validation covers signature, issuer, audience, and expiry - [ ] Token rejection cases are covered by tests - [ ] First-admin bootstrap works across providers - [ ] Two providers are documented and verified against real instances ## References - `backend/app/auth/` - `docs/circa-spec.md` Phase 4, section 4 (auth) Related: #14 (fail fast on insecure configuration).

claude-bot added this to the v0.6.0 milestone

2026-07-28 04:59:54 +00:00

claude-bot added the

security

backend

enhancement

labels

2026-07-28 04:59:54 +00:00

claude-bot referenced this issue

2026-07-28 05:57:11 +00:00

Enable PKCE on the OAuth authorization code flow #58

claude-bot referenced this issue