cgalo5758
0b28a9dc29
- Replace gorilla/csrf with net/http CrossOriginProtection - Require valkey-password and add TLS options for session store - End session at /logout and revoke refresh tokens - Re-derive identity and roles from provider every five minutes - Process each Stripe webhook event in its own Temporal workflow - Give each outbox entry its own workflow with Temporal retries - Guard against stale Stripe events with provider timestamps - Derive transport security from base-url scheme
164 lines
8.9 KiB
Markdown
164 lines
8.9 KiB
Markdown
# Authentication (internal/auth)
|
|
|
|
This package implements an OAuth 2.0 Authorization Code Grant with PKCE flow, enhanced by OpenID Connect (OIDC) for user identity.
|
|
|
|
> Purpose: Document the implementation details, configuration variables, endpoints, and security considerations for the OIDC authentication flow implemented by the `internal/auth` package.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The `internal/auth` package uses the Authorization Code grant combined with PKCE (Proof Key for Code Exchange) to authenticate users against an OpenID Connect (OIDC) identity provider (IdP). This flow is secure and recommended for both public and confidential clients as it prevents authorization code interception attacks.
|
|
|
|
The codebase integrates with Keycloak (or another OIDC-compatible IdP) and performs the following responsibilities:
|
|
|
|
- Initiate authorization using PKCE and OIDC `nonce` and `state` parameters
|
|
- Exchange authorization code for a token using the code verifier
|
|
- Verify the ID token (signature, nonce, issuer, audience)
|
|
- Provision or update a local user record in the database
|
|
- Manage a session using secure cookies
|
|
- Initiate and verify single sign-out via the IdP
|
|
|
|
---
|
|
|
|
## Grant Type
|
|
|
|
- OAuth 2.0: Authorization Code Grant
|
|
- PKCE extension: RFC 7636 (SHA-256-based `S256` method)
|
|
- OIDC: Identity layer using `openID` scope + ID token verification
|
|
|
|
---
|
|
|
|
## Key Implementation Details
|
|
|
|
### PKCE Flow
|
|
|
|
- A random `code_verifier` is generated for each login attempt: `codeVerifier := generateRandomString(32)`
|
|
- The `code_challenge` is computed by taking the SHA-256 hash of the code verifier and encoding it via base64url without padding:
|
|
|
|
```go
|
|
hashVal := sha256.Sum256([]byte(codeVerifier))
|
|
codeChallenge := base64.RawURLEncoding.EncodeToString(hashVal[:])
|
|
```
|
|
|
|
- The `code_challenge` and `code_challenge_method=S256` are added to the initial authorization URL.
|
|
- When exchanging the authorization code for tokens, the previously generated `code_verifier` is supplied using `oauth2.VerifierOption(codeVerifier)`.
|
|
|
|
### OIDC and Security Parameters
|
|
|
|
- `state`: A CSRF token is generated and validated to prevent CSRF attacks.
|
|
- `nonce`: A token to prevent replay attacks. The nonce is validated against the `nonce` claim in the ID token.
|
|
- ID Token (`id_token`) verification is performed using the OIDC provider's public keys via the `Verifier`.
|
|
- If the ID token is missing or invalid, the flow is rejected.
|
|
|
|
---
|
|
|
|
## Endpoints
|
|
|
|
The `internal/auth` RegisterHandlers method hooks the following HTTP routes on the `*http.ServeMux`:
|
|
|
|
- `GET /login` — `LoginHandler`: Initiate authorization (PKCE + OIDC).
|
|
- `GET /callback` — `CallbackHandler`: Handle authorization code, exchange tokens, verify ID token, provision user and create session.
|
|
- `POST /logout` — `LogoutHandler`: Destroys the session, revokes the refresh token at the IdP, then sends the browser to the IdP's end-session endpoint with a valid `id_token_hint` where one can be had: `HX-Redirect` for the account menu's htmx request, a 303 for any other POST. A GET at `/logout` is a 303 to `/` and ends nothing, so a link on another origin cannot sign a person out.
|
|
- `GET /logout-callback` — `LogoutCallbackHandler`: Where the IdP sends the browser after its own sign-out; redirects to `/login`. Nothing is verified here because nothing is left to protect.
|
|
- `GET /register` — `RegistrationHandler`: Redirects to the IdP registration path (or the auth endpoint with registration params) using `code_challenge` and `nonce` similarly to `/login`.
|
|
|
|
---
|
|
|
|
## Configuration & Environment Variables
|
|
|
|
The auth package depends on the application configuration (via `viper`) to initialize.
|
|
|
|
Required config keys (from `viper`):
|
|
|
|
- `oidc-idp-issuer-url` — Identity Provider issuer URL (e.g., `https://idp.example.com/realms/realm`)
|
|
- `oidc-sp-client-id` — OAuth client ID (service provider client identifier)
|
|
- `oidc-sp-client-secret` — OAuth client secret (if using a confidential client; optional for public clients)
|
|
- `base-url` — Application base redirect URL (e.g., `https://app.example.com`)
|
|
- `valkey-addr` — Valkey/Redis address for the server-side session store (default `localhost:6379`)
|
|
- `env` — `production` or other (controls the cookie `Secure` flag)
|
|
|
|
---
|
|
|
|
## Session & Cookie Management
|
|
|
|
- Session store: `scs` (`alexedwards/scs`) with a Valkey/Redis backend (`redisstore`) — sessions are server-side, so no signing/encryption secret is needed
|
|
- Cookie options:
|
|
- `HttpOnly: true` — prevents JS access to cookie
|
|
- `Secure: true` only when `env` is `production`
|
|
- `SameSite: Lax` — helps prevent CSRF while allowing top-level navigation
|
|
- `MaxAge: 7 days` by default
|
|
- The session stores these keys:
|
|
- `state`, `nonce`, `code_verifier` during the authentication initiation
|
|
- `authenticated`, `id_token`, `refresh_token`, `person_id`, `org_id`, `workspace_id`, `oidc_subject`, `email`, `name`, `username`, `roles`, `identity_refreshed_at` after authentication; `identity_retry_at` while the provider is not answering
|
|
|
|
---
|
|
|
|
## DB Integration
|
|
|
|
- The code uses the `db.Querier` interface (SQLC-generated queries) to get, create, or update users:
|
|
- `GetUserByOIDCSubject(ctx, subject)` — find existing user by `sub` claim
|
|
- `CreateUser(ctx, CreateUserParams)` — create new user when not found
|
|
- `UpdateUser(ctx, UpdateUserParams)` — update user info on subsequent logins
|
|
|
|
- When a new user logs in for the first time, the implementation creates a new database user record with relevant OIDC claims:
|
|
- `OidcSubject` — OIDC `sub` claim
|
|
- `Username` — `preferred_username`
|
|
- `Email` — `email`
|
|
|
|
---
|
|
|
|
## Identity Re-derivation
|
|
|
|
- Every five minutes, on the first authenticated request after the interval, the middleware re-derives the session's identity and roles with a refresh-token grant: the new ID token is verified as at sign-in, its roles replace the session's, and the new ID token and refresh token replace the stored ones.
|
|
- `invalid_grant` (session ended at the IdP, account disabled, token revoked) ends the console session and bounces to `/login`. No answer keeps the session and retries after a minute. A token naming a different subject ends the session.
|
|
- Concurrent requests crossing the interval share one refresh (`singleflight`, keyed by session token).
|
|
|
|
## Logout Flow
|
|
|
|
- Sign-out is a POST, made by the account menu's button; the cross-origin protection covers it and a GET at `/logout` only redirects to `/`. `LogoutHandler` destroys the console session first, then sends the browser to the IdP's `end_session_endpoint`, read from discovery at startup (`HX-Redirect` to the htmx request, since fetch cannot follow a redirect to another origin). A provider that publishes none fails startup; there is no fallback path.
|
|
- The request carries `id_token_hint` whenever a valid ID token can be had: the stored one while it is still valid, otherwise a fresh one minted from the stored refresh token in one bounded call to the token endpoint. A valid hint is what lets the IdP end its session without asking the person to confirm. When no hint can be had the IdP asks; the console session is gone either way.
|
|
- Between the two, every refresh token that was live (the stored one, and a rotated one when the refresh returned it) is revoked at the IdP's `revocation_endpoint` (RFC 7009) when discovery publishes one, so no copy can mint tokens after sign-out. Best effort: a failure is logged and the sign-out proceeds.
|
|
- `LogoutCallbackHandler` destroys the session once more (expiring a cookie the browser may still carry) and redirects to `/login`.
|
|
|
|
---
|
|
|
|
## Quick Start: Configuration Example
|
|
|
|
Example `viper`/env config for a development environment:
|
|
|
|
- `oidc-idp-issuer-url`: `https://idp.example.com/realms/demo`
|
|
- `oidc-sp-client-id`: `member-console`
|
|
- `oidc-sp-client-secret`: `<client-secret>` (optional for public clients)
|
|
- `base-url`: `http://localhost:8080`
|
|
- `valkey-addr`: `localhost:6379`
|
|
- `env`: `development`
|
|
|
|
Once configured, the app can be started and these endpoints will be active on the configured host.
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- OAuth 2.0 Authorization Framework (RFC 6749)
|
|
- Proof Key for Code Exchange (PKCE) (RFC 7636)
|
|
- OpenID Connect Core 1.0
|
|
|
|
---
|
|
|
|
## Notes & Tips
|
|
|
|
- PKCE is mandatory for public clients (e.g., SPA, mobile) and recommended for confidential clients to protect against code interception attacks.
|
|
- The `nonce` is stored in session and validated against the ID token `nonce` claim as an additional replay protection.
|
|
- The logout and revocation endpoints are discovered (`end_session_endpoint`, `revocation_endpoint`). The registration path is still Keycloak's; another IdP may need a different route for registration.
|
|
- When deploying to production, ensure `base-url` reflects your secure domain and `valkey-addr` points at your session store.
|
|
|
|
---
|
|
|
|
## Related code files
|
|
|
|
- `internal/auth/auth.go` — implementation of the handlers and flow
|
|
- `internal/auth/` — this README and other auth related files
|
|
- `internal/db/*` — database schema & SQLC queries (`GetUserByOIDCSubject`, `CreateUser`, `UpdateUser`)
|
|
|