oidc

package
v0.80.0 Latest Latest
Warning

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

Go to latest
Published: Jul 9, 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 (the qllauthpoc 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 -- the qllpoc pattern, 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