oidc

package
v5.0.3 Latest Latest
Warning

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

Go to latest
Published: Sep 2, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

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

Constants

This section is empty.

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

func ResolveUser(claims *Claims, existingBySub *auth.User) (user *auth.User, isNew bool, err error)

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

func ValidateConfig(cfg Config) error

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

type Nonce = auth.OIDCNonce

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

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

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

type State = auth.OIDCState

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.

Jump to

Keyboard shortcuts

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