Documentation
¶
Overview ¶
Package oidc verifies bearer tokens from an external OIDC issuer -- the pluggable-SSO half of the backend's auth (auth/local is the built-in half). Signature keys come from the issuer's JWKS (cached and auto-refreshed); role assignment is configurable (which claim, and how the issuer's role names map onto auth.Role), so any IdP that can mint a role-bearing access token plugs in without code.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExchangeHandler ¶
func ExchangeHandler(cfg ExchangeConfig) http.Handler
ExchangeHandler returns the POST /v1/auth/exchange handler. It accepts form-encoded token requests, injects the confidential credentials, forwards to the issuer's token endpoint, and relays the JSON response verbatim.
Types ¶
type Config ¶
type Config struct {
// Issuer is the issuer URL; tokens' iss must match exactly.
Issuer string
// JWKSURL overrides key discovery. Empty = try OIDC discovery
// ({issuer}/.well-known/openid-configuration), falling back to
// {issuer}/jwks.json (a common fallback convention).
JWKSURL string
// Audience, when set, must appear in the token's aud.
Audience string
// RoleClaim is the claim carrying the caller's role(s); string or list.
// Default "role".
RoleClaim string
// RoleMap translates issuer role names to auth roles (e.g.
// {"subject_moderator": auth.RoleModerator}). Issuer values that already
// equal an auth.Role name map implicitly; anything else is ignored.
RoleMap map[string]auth.Role
// ClaimEquals lists extra exact-match claim requirements (e.g.
// {"token_use": "access"} to reject id tokens).
ClaimEquals map[string]string
// EmailClaim is the claim carrying the caller's email. Default "email".
EmailClaim string
// HTTPClient overrides the client used for discovery and JWKS (tests).
HTTPClient *http.Client
}
Config describes one external issuer.
type Discovery ¶ added in v0.37.0
type Discovery struct {
AuthorizationEndpoint string `json:"authorization_endpoint"`
TokenEndpoint string `json:"token_endpoint"`
JWKSURI string `json:"jwks_uri"`
}
Discovery is the subset of the issuer's OIDC discovery document the backend consumes; auth/sitegate additionally needs the interactive endpoints.
type ExchangeConfig ¶
type ExchangeConfig struct {
// TokenEndpoint is the issuer's token URL. Empty = resolve via OIDC
// discovery at first use.
TokenEndpoint string
// Issuer is used for discovery when TokenEndpoint is empty.
Issuer string
// ClientID and ClientSecret are the confidential client credentials
// added to every proxied request. An empty secret disables the proxy
// (503) until deployment configuration provides one.
ClientID string
ClientSecret string
// HTTPClient overrides the upstream client (tests).
HTTPClient *http.Client
}
ExchangeConfig wires the PKCE token-exchange proxy: the SPA is a public OIDC client, so the confidential client secret lives only server-side and the SPA exchanges its authorization code (and rotates refresh tokens) through this endpoint instead of calling the issuer directly, which also sidesteps issuer CORS.