Documentation
¶
Overview ¶
Package oidc signs a user in with an OpenID Connect provider, on coreos/go-oidc. Provider.Begin seals the flow's state, nonce, PKCE verifier and intent into a browser-bound cookie and returns the authorization URL; Provider.Finish opens that cookie on the callback, exchanges the code and verifies the ID token. Nothing is stored server-side. The flow cookie always takes the secure name and the Secure flag, because every OIDC route needs a secure request: over plain HTTP the browser drops it, so the flow fails closed. It imports the root access package and never the reverse.
Index ¶
- Constants
- Variables
- func UsernameCandidate(c Claims) (string, error)
- type BeginRequest
- type Callback
- type Claims
- type Config
- type Flow
- type Intent
- type Provider
- func (p *Provider) Begin(w http.ResponseWriter, r *http.Request, session access.CookieConfig, ...) (authURL string, err error)
- func (p *Provider) Finish(w http.ResponseWriter, r *http.Request, session access.CookieConfig, ...) (Flow, Claims, error)
- func (p *Provider) Issuer() string
- func (p *Provider) LogValue() slog.Value
- type ProviderError
- type Provisioning
- type UsernameError
Constants ¶
const MaxRedirectBytes = 512
MaxRedirectBytes is the longest BeginRequest.Redirect Begin accepts.
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 verified email claim") // ErrFlowInvalid reports a flow cookie that is missing, forged, expired, // sealed by another provider or answered with another state, and a // malformed BeginRequest or a cross-site begin that Begin refuses. ErrFlowInvalid = errors.New("oidc: sign-in flow invalid") // ErrStaleAuthentication reports a link or step-up whose ID token does // not prove a sign-in at the provider after the flow began. ErrStaleAuthentication = errors.New("oidc: the provider did not authenticate the user again") ErrRedirectTooLong = errors.New("oidc: redirect longer than MaxRedirectBytes") // ErrProvisioningDisabled and ErrNotAdmitted are Provisioning.Admit's // refusals. ErrProvisioningDisabled = errors.New("oidc: provisioning is disabled") ErrNotAdmitted = errors.New("oidc: identity not admitted for provisioning") )
Sentinel errors for OIDC operations.
Functions ¶
func UsernameCandidate ¶
UsernameCandidate is preferred_username when present, else email when email_verified, normalised by access.NormalizeUsername. It returns ErrNoUsername when neither applies, and a *UsernameError naming the claim when the chosen one does not normalise; it never falls back from a refused preferred_username to the email.
Types ¶
type BeginRequest ¶
type BeginRequest struct {
Intent Intent
SessionID string
// Redirect is the app's relative return path, at most MaxRedirectBytes,
// passed through access.ValidateRedirectURI, so an unsafe one becomes "/".
Redirect string
UserID int64
}
BeginRequest names what the flow is for. SessionID, at most 64 bytes, and a positive UserID are required for IntentLink and IntentStepUp and must be empty for IntentSignIn.
type Callback ¶
Callback is what the provider sent on its redirect to the callback (RFC 6749 sections 4.1.2 and 4.1.2.1), decoded once by the caller.
type Claims ¶
type Claims struct {
// AuthTime is the auth_time claim, zero when the token has none.
AuthTime time.Time
// Raw holds every verified claim, by name.
Raw map[string]json.RawMessage
Identity access.OIDCIdentity
Email string
PreferredUsername string
Name string
// EmailVerified is decoded from a JSON boolean or the strings "true"
// and "false", which some providers send.
EmailVerified bool
}
Claims are the claims of an ID token Finish verified.
type Config ¶
type Config struct {
// HTTPClient is the client for discovery, JWKS and token calls; nil
// means a default client. The provider uses a copy: a zero Timeout
// becomes 10s, and the transport is wrapped so a response body past 1
// MiB is refused, whatever length it declares. A negative Timeout is
// refused. CheckRedirect, Jar and the transport's dialer and TLS
// settings are kept as given.
HTTPClient *http.Client
// FlowSealer seals the flow cookie; nil means a new ephemeral sealer
// per Provider, so a flow begun under one Provider value cannot finish
// under a rebuilt one; an app that rebuilds providers passes one sealer
// that outlives them.
FlowSealer *access.Sealer
// Now is the clock for the flow cookie and the ID token's expiry; nil
// means time.Now.
Now func() time.Time
ClientSecret access.Secret
IssuerURL string
ClientID string
RedirectURL string
// Scopes is the requested scope list, which must include "openid"; nil
// means openid, profile and email.
Scopes []string
}
Config is a Provider's settings. Every optional field's zero value is its default.
func (Config) Validate ¶
Validate requires an https issuer and redirect URL, except http on a loopback host, each absolute with a host and no userinfo or fragment, and the issuer with no query (OpenID Connect Discovery 1.0 section 3); a client ID; a Scopes list that includes "openid" when one is given; and a non-negative HTTPClient.Timeout. Every refusal matches ErrConfigInvalid.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is an OpenID Connect provider discovered by NewProvider. It is immutable; an app swaps its pointer when settings change.
func NewProvider ¶
NewProvider validates cfg, refuses with ErrConfigInvalid one whose largest flow would not seal or fit its cookie, runs discovery through cfg's client and refuses, with ErrDiscovery naming the field, a document whose authorization_endpoint, token_endpoint or jwks_uri is not an absolute https URL with a host and without userinfo; http is accepted only on a loopback host while the issuer itself is a loopback http URL.
func (*Provider) Begin ¶
func (p *Provider) Begin(w http.ResponseWriter, r *http.Request, session access.CookieConfig, req BeginRequest) (authURL string, err error)
Begin seals the flow into the flow cookie, session.Derive("oidc", Lax) under its secure name, and returns the authorization URL, with max_age=0 and prompt=login for IntentLink and IntentStepUp. Before any Set-Cookie it refuses a Redirect over MaxRedirectBytes with ErrRedirectTooLong, first; with ErrConfigInvalid, a session config that fails Validate; with ErrFlowInvalid, an unknown intent or IDs that do not fit it, and a link or step-up whose Sec-Fetch-Site is present and not same-origin. NewProvider owns the flow cookie's size.
func (*Provider) Finish ¶
func (p *Provider) Finish(w http.ResponseWriter, r *http.Request, session access.CookieConfig, cb Callback) (Flow, Claims, error)
Finish reads and clears the flow cookie derived from session, under its secure name, on every outcome past session.Validate, checks cb.State, exchanges cb.Code and verifies the ID token. It reads the request only for the cookie and its context, never its URL. A session config that fails Validate is ErrConfigInvalid with no Set-Cookie. An error after the cookie opened, for this provider, comes with the opened Flow, so the caller can return the browser to the page the flow began on; before that, Flow is zero.
type ProviderError ¶
type ProviderError struct {
// Code is one of the codes of RFC 6749 section 4.1.2.1, or "other" for
// any other value. The provider's error_description is never read.
Code string
}
ProviderError is the provider's error answer to the authorization request, read only after the callback's state matched the flow's.
func (*ProviderError) Error ¶
func (e *ProviderError) Error() string
type Provisioning ¶
type Provisioning struct {
// Claim names the claim to check, e.g. "groups"; empty admits any
// authenticated identity.
Claim string
// Role is the created account's role; empty means access.RoleUser.
Role access.Role
// AllowedValues must share at least one value with Claim.
AllowedValues []string
Enabled bool
}
Provisioning gates just-in-time account creation from an OIDC sign-in. The zero value is off. An app supplies it as data through account.Rules.Provisioning.
func (Provisioning) Admit ¶
func (p Provisioning) Admit(c Claims) error
Admit reports whether c may provision an account: ErrProvisioningDisabled when p is off, Validate's error for an invalid p, and ErrNotAdmitted when Claim is set and c's claim, a string or an array of strings, holds none of AllowedValues.
func (Provisioning) Validate ¶
func (p Provisioning) Validate() error
Validate refuses a Claim without AllowedValues, AllowedValues without a Claim, and a Role other than "", RoleUser or RoleAdmin, each matching ErrConfigInvalid.
type UsernameError ¶
type UsernameError struct {
// Err is NormalizeUsername's error, matching access.ErrUsernameEmpty or
// access.ErrUsernameInvalid.
Err error
// Claim is "preferred_username" or "email".
Claim string
}
UsernameError reports that the claim UsernameCandidate chose is not a username access.NormalizeUsername accepts.
func (*UsernameError) Error ¶
func (e *UsernameError) Error() string
func (*UsernameError) Unwrap ¶
func (e *UsernameError) Unwrap() error