Documentation
¶
Overview ¶
Package oidc wraps coreos/go-oidc to provide OIDC/OAuth2 authentication flows with PKCE. It imports the core auth package for types but never the reverse.
Index ¶
- Variables
- func GeneratePKCE() (CodeVerifier, CodeChallenge)
- func ResolveUser(claims *Claims, existingBySub *auth.User) (user *auth.User, isNew bool, err error)
- func ValidateConfig(cfg Config) error
- type Claims
- type Code
- type CodeChallenge
- type CodeVerifier
- type Config
- type Nonce
- type Provider
- type State
Constants ¶
This section is empty.
Variables ¶
var ( ErrDiscovery = errors.New("oidc: provider discovery failed") ErrExchange = errors.New("oidc: code exchange failed") ErrTokenInvalid = errors.New("oidc: ID token verification failed") ErrNonceMismatch = errors.New("oidc: nonce mismatch") ErrConfigInvalid = errors.New("oidc: invalid configuration") ErrNoUsername = errors.New("oidc: token has no preferred_username or email claim") )
Sentinel errors for OIDC operations.
Functions ¶
func GeneratePKCE ¶
func GeneratePKCE() (CodeVerifier, CodeChallenge)
GeneratePKCE generates a PKCE code verifier and S256 challenge. The two results are distinct types (they are born adjacent and equally opaque), so the whole chain from generation through storage to Provider.Exchange is compiler-checked with no hand-written conversion for a caller to transpose. It cannot fail: since Go 1.24 crypto/rand.Read never returns an error.
func ResolveUser ¶
ResolveUser maps an OIDC identity to a user by (issuer, sub) only. For a new identity (existingBySub == nil) it provisions a user from the token claims; it returns ErrNoUsername if the token has neither preferred_username nor email, rather than provisioning an account with a blank username.
func ValidateConfig ¶
ValidateConfig checks that the required fields of a Config are set.
Types ¶
type Claims ¶
type Claims struct {
Subject string `json:"sub"`
Issuer string `json:"iss"`
Email string `json:"email"`
PreferredUsername string `json:"preferred_username"`
Name string `json:"name"`
EmailVerified bool `json:"email_verified"`
}
Claims holds the verified claims extracted from an OIDC ID token.
type Code ¶
type Code string
Code is the single-use authorization code returned to the redirect URI.
type CodeChallenge ¶
type CodeChallenge string
CodeChallenge is the PKCE S256 challenge sent in the authorization request.
type CodeVerifier ¶
type CodeVerifier = auth.OIDCCodeVerifier
CodeVerifier is the PKCE verifier matching a previously sent CodeChallenge. It is an alias of auth.OIDCCodeVerifier (the canonical definition).
type Config ¶
type Config = auth.OIDCConfig
Config holds OIDC provider settings. It is an alias of auth.OIDCConfig (the canonical definition), so a consumer holding the core type passes it to NewProvider directly with no field-for-field conversion.
type Nonce ¶
Nonce is the ID-token replay-protection nonce bound into an authorization request and verified against the token's nonce claim at Provider.Exchange. It is an alias of auth.OIDCNonce (the canonical definition).
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider wraps the coreos/go-oidc provider with PKCE support. Create with NewProvider; the zero value has no discovered endpoints and no token verifier, so Provider.Exchange fails at the token request — the empty token endpoint URL is unreachable, reported as ErrExchange — and returns before the nil verifier is ever consulted.
func NewProvider ¶
NewProvider creates an OIDC provider from config.
func (*Provider) AuthorizationURL ¶
func (p *Provider) AuthorizationURL(state State, nonce Nonce, codeChallenge CodeChallenge) (string, error)
AuthorizationURL generates the OIDC authorization URL with PKCE and state.
state and codeChallenge MUST be the non-empty, single-use, cryptographically random values minted for this authorization request (GenerateState, GeneratePKCE). An empty state is rejected with a descriptive error (fail closed): a conformant authorization-code flow always supplies a non-empty state, and emitting a request without one would silently drop the CSRF binding of the callback. An empty codeChallenge is rejected the same way: the request would silently carry no PKCE protection. This mirrors Provider.Exchange's empty-nonce posture.
func (*Provider) Exchange ¶
func (p *Provider) Exchange(ctx context.Context, code Code, codeVerifier CodeVerifier, nonce Nonce) (*Claims, time.Time, error)
Exchange exchanges an authorization code for tokens and validates the ID token.
The returned expiry is the OAuth2 token's expiry, or the zero Time when the provider issued none; it is shaped to drop straight into auth.Session.OIDCExpiry.
nonce MUST be the non-empty, single-use, cryptographically random value that was bound into the matching AuthorizationURL call and stored server-side for this authorization request. Exchange requires the ID token's nonce claim to equal it, defending against ID-token replay and injection. Passing nonce == "" is rejected with ErrNonceMismatch (fail closed): a conformant authorization-code flow always supplies a non-empty nonce, so an empty value can never satisfy the check. PKCE and the state parameter remain in force regardless, but the nonce binding is a distinct protection.
type State ¶
State is the CSRF-binding state parameter of an authorization request. It is an alias of auth.OIDCState (the canonical definition), so the value flows from GenerateState through a consumer's auth.OIDCStateStore and back without conversion.
func GenerateState ¶
func GenerateState() State
GenerateState generates a random state value for OIDC flows, typed at the producer so it cannot be transposed with the other opaque randoms on its way to Provider.AuthorizationURL or a consumer's auth.OIDCStateStore. It cannot fail: since Go 1.24 crypto/rand.Read never returns an error.