oidc

package
v1.0.0-dev.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

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. It imports the root access package and never the reverse.

Index

Constants

View Source
const MaxRedirectBytes = 512

MaxRedirectBytes is the longest BeginRequest.Redirect Begin accepts.

Variables

View Source
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

func UsernameCandidate(c Claims) (string, error)

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

type Callback struct {
	State string
	Code  string
	Error string
}

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.

func (Claims) Strings

func (c Claims) Strings(name string) ([]string, bool)

Strings reads a claim that is a string or an array of strings, the two shapes providers use for groups. It reports false for an absent claim and for any other shape.

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

func (c Config) Validate() error

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 Flow

type Flow struct {
	BeganAt   time.Time
	Intent    Intent
	SessionID string
	Redirect  string
	UserID    int64
}

Flow is what Finish recovers from the flow cookie.

type Intent

type Intent string

Intent is what a flow is for.

const (
	IntentSignIn Intent = "signin"
	IntentLink   Intent = "link"   // started from a session; links on return
	IntentStepUp Intent = "stepup" // started from a session; re-proves on return
)

The three intents. Link and step-up start from a session and make the provider authenticate the user again.

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

func NewProvider(ctx context.Context, cfg Config) (*Provider, error)

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), 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 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.

func (*Provider) Issuer

func (p *Provider) Issuer() string

Issuer returns cfg.IssuerURL, the issuer every ID token this provider verifies carries.

func (*Provider) LogValue

func (p *Provider) LogValue() slog.Value

LogValue prints the issuer and client ID. Provider has no Format: its config holds ClientSecret as an access.Secret, and no field stores an oauth2.Config, which would hold the secret in clear.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL