oidc

package
v0.231.0 Latest Latest
Warning

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

Go to latest
Published: Jul 15, 2026 License: MIT Imports: 12 Imported by: 0

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.

func Discover added in v0.37.0

func Discover(ctx context.Context, client *http.Client, issuer string) (Discovery, error)

Discover fetches {issuer}/.well-known/openid-configuration. A nil client uses http.DefaultClient.

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.

type Verifier

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier implements auth.TokenVerifier for one external issuer.

func New

func New(ctx context.Context, cfg Config) (*Verifier, error)

New wires JWKS fetching for the issuer, resolving the JWKS URL via OIDC discovery when not configured.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, raw string) (auth.Identity, error)

Verify checks the token's signature against the issuer's JWKS and its issuer/audience/extra claims, then maps its role claim onto auth roles.

Jump to

Keyboard shortcuts

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