OIDC login for trip2g — implementation plan

Email verification resolution

The callback resolves identity in this order, before UserByEmail or provisioning:

1. Verify the ID-token signature, require iss, aud, and exp, validate iat when present, and check nonce.
2. Fetch UserInfo and require exact non-empty id_token.sub == userinfo.sub.
3. Require a non-empty UserInfo email.
4. Resolve email_verified with UserInfo precedence:

The fallback comparison is byte-for-byte, without trimming or case folding. Rejection logs include a stable internal reason such as userinfo_claim_false, id_token_claim_missing, or id_token_userinfo_email_mismatch; successful login logs include email_verification_source=userinfo|id_token.

This sub check binds the two provider responses during one callback only. The database still selects the local account by email and does not persist (issuer, sub).

1. How trip2g login works today (the pattern to mirror)

trip2g already has a clean, repeatable OAuth shape. OIDC is a third instance of it. Two reference providers: Google (internal/case/handlegooglestart + handlegooglecallback) and GitHub (same pair).

Credentials live in the DB, admin-configured, secret encrypted — NOT in env (this differs from simplepanel, which uses env flags):

• Table google_oauth_credentials (db/schema.sql:540): id, name, client_id, client_secret_encrypted blob, active, created_at, created_by. Model db.GoogleOauthCredential (internal/db/models.go:322).
• Loaded per request via GetActiveGoogleOAuthCredentials (internal/db/queries.read.sql.go:1527).
• Secret decrypted via the encryption manager DecryptData (internal/dataencryption/encryption.go:64).
• Written via InsertGoogleOAuthCredentials (internal/db/queries.write.sql.go:1414) + an activate query (set active = (id = ?)).

State / CSRF is a reusable package — no changes needed:

• oauthstate.Generate(ctx, redirect, insecure) sets a 5-min oauth_state nonce cookie and returns the encoded state; oauthstate.Validate(ctx, stateParam, insecure) checks the nonce and returns the safe redirect (internal/oauthstate/state.go). It also sanitizes the post-login redirect (safeRedirect).

Provider client is a small hand-rolled fasthttp client (no golang.org/x/oauth2):

• internal/googleauth/: Config{ClientID, ClientSecret} + BuildAuthURL(clientID, redirectURI, state) + ExchangeCode(...) + GetUserInfo(accessToken). Endpoint URLs are hardcoded constants (internal/googleauth/client.go:12-16). Scope hardcoded "email profile".

The start handler (handlegooglestart/endpoint.go): loads active creds, generates state, builds callbackURL = env.PublicURL() + "/_system/auth/google/callback", redirects to the provider authorize URL. Path() = /_system/auth/google.

The callback handler (handlegooglecallback/endpoint.go): loads creds → DecryptData the secret → check error param → oauthstate.Validate → ExchangeCode → GetUserInfo → env.UserByEmail(email) → env.SetupUserToken(userID) (sets the session JWT cookie) → redirect. On unknown email it redirects with ?berror=user_not_found — it does NOT auto-create users (db.IsNoFound(err) branch). Path() = /_system/auth/google/callback.

Session is an HS256 JWT cookie set by SetupUserToken (internal/usertoken/).

Routing is generated, not hand-edited:

• Each case package exposes an Endpoint struct with Handle/Path/Method and its own Env interface.
• go run ./internal/router/gencmd scans internal/case/{"", admin, system} for any <name>/endpoint.go and regenerates internal/router/endpoints_gen.go (the file is DO NOT EDIT; //go:generate go run ./gencmd lives in internal/router/router.go:12). So a new endpoint is picked up automatically once the package exists and you re-run gencmd.
• The router's aggregate Env must satisfy every endpoint's Env interface (where GetActiveGoogleOAuthCredentials, PublicURL, Insecure, DecryptData, UserByEmail, SetupUserToken are implemented).

Admin config of Google/GitHub creds is a GraphQL admin mutation — createGoogleOAuthCredentials / setActiveGoogleOAuthCredentials / deleteGoogleOAuthCredentials (internal/graph/schema.graphqls:3110-3112), backed by case handlers under internal/case/admin/creategoogleoauthcredentials/ etc. The mutation validates + encrypts the secret and writes the row. OIDC follows the same path (detailed in Step 7).

2. What OIDC adds beyond the Google pattern

1. Discovery instead of hardcoded endpoints. Google hardcodes authorize/token/userinfo URLs. OIDC derives them from a single issuer via GET {issuer}/.well-known/openid-configuration → authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri. So the credential needs one extra field: issuer.
2. openid scope + groups. Use scope openid email profile (+ a groups scope if the IdP maps it) to get the user's email and group memberships.
3. id_token. The token response carries an id_token (signed JWT). Proper OIDC verifies its signature against jwks_uri and reads claims from it. Minimal path: ignore the id_token and call userinfo exactly like Google does (simpler, matches existing code). Recommended path: verify the id_token signature (defense in depth) and read email/groups from it. See §7 open questions.
4. Issuer string must match exactly (Authentik per-provider issuer ends with a trailing slash — see §5).

3. Implementation steps

-- migrate:up
create table oidc_credentials (
    id integer primary key,
    name text not null,
    issuer text not null,
    client_id text not null,
    client_secret_encrypted blob not null,
    scopes text not null default 'openid email profile',
    active boolean not null default false,
    created_at datetime not null default (datetime('now')),
    created_by integer not null references users(id)
);

-- migrate:down
drop table oidc_credentials;

go run ./internal/router/gencmd   # auto-discovers handleoidcstart / handleoidccallback

mutation {
  createOIDCCredentials(input: {
    name: "Authentik",
    issuer: "https://authentik.company/application/o/trip2g/",
    clientId: "...", clientSecret: "...",
    scopes: "openid email profile"
  }) { ... on CreateOIDCCredentialsPayload { credentials { id name active } } ... on ErrorPayload { message } }
}

4. URL configuration — issuer vs redirect_uri

Two URLs in opposite directions; do not confuse them.

• You only store the issuer; discovery derives authorize/token/userinfo/jwks.
• ⚠️ Trailing slash matters — Authentik per-provider iss is exactly …/o/<app-slug>/. If the stored issuer omits the slash, id_token iss verification fails.
• The redirect_uri must be added to the Authentik Application's allowed redirect URIs (exact match), or Authentik returns redirect_uri mismatch.

5. Authentik side (done once by the client's admin)

Mirrors docs/sso_box_design.md §4.1 in the simplepanel repo:

1. Applications → Applications → New Provider → OAuth2/OpenID Provider; create the linked Application (its slug becomes the issuer path).
2. Set the Redirect URI to {PublicURL}/_system/auth/oidc/callback.
3. Copy client_id / client_secret into trip2g's oidc_credentials (issuer = https://authentik.company/application/o/<slug>/).
4. To get groups in the token: Customization → Property Mappings → new OAuth2 Scope Mapping returning [g.name for g in request.user.ak_groups.all()], attach it to the provider; add its scope to oidc_credentials.scopes.

6. Groups → authorization (separate concern, defer)

Authentication (who the user is) is what this plan delivers. Authorization (what subgraphs/instances the user may see) is trip2g's existing access model (subgraph access, e.g. UserSubgraphAccess). Mapping OIDC groups → subgraph access is a follow-up: read groups from the verified token in the callback and grant/deny accordingly. Not required for basic SSO login; design it after Step 8.

7. Open questions / risks

1. Persistent provider identity. ID token and UserInfo are cryptographically/semantically bound during each callback, but the local account is still selected by email. Persist (issuer, sub) before relying on stable provider identity across email changes or reassignment.
2. Discovery caching. Cache .well-known per issuer with a TTL; do not fetch on every login. Handle issuer/IdP downtime gracefully (fall back to a clear ?berror=).
3. Auto-provisioning (Step 8). Policy + security decision (who gets an account). Confirm before enabling B.
4. Authentik reachability. trip2g must reach the issuer's token/userinfo/jwks over HTTPS at login time, and the user's browser must reach authorize. If the client's Authentik is network-isolated, plan connectivity (see sso_box_design.md §6 risk 8).
5. No golang.org/x/oauth2 in trip2g. Keep the hand-rolled fasthttp style for consistency; that means implementing discovery + (optional) JWKS verification by hand, or pulling a minimal JOSE dependency for verification only.
6. Single active credential. Reuse the Google single-active invariant (set active = (id = ?)); decide whether multiple IdPs can be active at once (Google/GitHub/OIDC are independent rows in separate tables, so OIDC active is orthogonal).

8. Effort & file checklist

Size: M (no provider abstraction to reuse; a new package + two endpoints + migration + sqlc + GraphQL + gencmd).

• db/migrations/20260621150755_create_oidc_credentials.sql (+ auto_provision, allowed_email_domain, required_group)
• queries.read.sql / queries.write.sql + make sqlc
• internal/oidcauth/{config.go, client.go, discovery.go, models.go}
• internal/case/handleoidcstart/endpoint.go
• internal/case/handleoidccallback/endpoint.go (+ policy.go account gates)
• Env: GetActiveOIDCCredentials (promotes via *db.Queries; no manual Env method needed)
• go generate ./internal/router/... → endpoints_gen.go committed
• GraphQL admin mutation/query for OIDC creds + UI login button (oidcAuthUrl)
• account policy decision (Step 8) — per-provider auto_provision + domain/group gates
• go test ./... green; e2e e2e/oidc.spec.js (7 cases) green against a mock IdP. Manual smoke against a real Authentik still TODO.