oidc

Documentation

Overview

Package oidc implements a stateless OIDC 1.0 Relying Party running the Authorization Code flow with PKCE. On a successful callback the verified principal is handed to the consumer via a gosso.OnAuthenticated callback; this package never writes session cookies itself. A short lived, signed transit cookie is used purely to carry state, nonce and the PKCE verifier between /login and /callback.

Index

• Variables
• type ClaimMap
• type Handlers
• type LogoutHintProvider
• type Option
  • func WithBootstrapTimeout(d time.Duration) Option
  • func WithClaimMap(m ClaimMap) Option
  • func WithErrorLogger(fn sso.ErrorLogger) Option
  • func WithExtraScopes(scopes ...string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithIssuerValidator(fn func(iss string) error) Option
  • func WithLogoutHintProvider(fn LogoutHintProvider) Option
  • func WithOnLogout(fn sso.OnLogout) Option
  • func WithPostLogoutRedirectURL(u string) Option
  • func WithTransitCookieName(name string) Option
  • func WithTransitDeprecatedKeys(keys ...[]byte) Option
  • func WithTransitTTL(d time.Duration) Option
  • func WithUserInfo(enabled bool) Option
• type Payload
• type RP
  • func New(issuerURL string, clientID string, clientSecret string, redirectURL string, ...) (*RP, error)
  • func (rp *RP) Handlers() Handlers

Variables

var StandardClaimMap = ClaimMap{
	ExternalID: "sub",
	Email:      "email",
	Firstname:  "given_name",
	Lastname:   "family_name",
	Groups:     "groups",
}

StandardClaimMap is the default mapping suitable for most OIDC IdPs (Keycloak, Okta, Auth0, Microsoft Entra ID with the `groups` claim enabled).

Types

type ClaimMap

type ClaimMap struct {
	ExternalID string
	Email      string
	Firstname  string
	Lastname   string
	Groups     string
}

ClaimMap names the OIDC claims that are copied into sso.Subject's common fields. The defaults target the core + profile + email scopes plus the widely-used `groups` claim.

type Handlers

type Handlers struct {
	Login    http.Handler
	Callback http.Handler
	Logout   http.Handler
}

Handlers groups the three HTTP handlers the consumer mounts on its router: Login initiates the flow, Callback completes the code exchange, Logout fires OnLogout and (optionally) redirects to the IdP's end-session endpoint.

type LogoutHintProvider

type LogoutHintProvider func(*http.Request) string

LogoutHintProvider returns the raw ID token (typically extracted from the consumer's session) to be included as id_token_hint in an RP-initiated logout request. Returning an empty string skips the IdP-side SLO.

type Option

type Option = options.OptionE[*RP]

Option configures an RP.

func WithBootstrapTimeout

func WithBootstrapTimeout(d time.Duration) Option

WithBootstrapTimeout bounds the time `New` will spend on OIDC discovery. Defaults to 30s. Values ≤ 0 are rejected.

func WithClaimMap

func WithClaimMap(m ClaimMap) Option

WithClaimMap overrides the default claim names used to populate sso.Subject.

func WithErrorLogger

func WithErrorLogger(fn sso.ErrorLogger) Option

WithErrorLogger routes runtime errors encountered by the OIDC handlers to the supplied logger. HTTP responses stay generic regardless; the logger sees the underlying cause.

func WithExtraScopes

func WithExtraScopes(scopes ...string) Option

WithExtraScopes appends scopes to the default {openid, profile, email} set. Most commonly used to request `offline_access` for refresh tokens.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient overrides the client used for discovery, token and UserInfo calls. The default client has a 15 second Timeout; a client supplied here is used as-is — set your own Timeout if you want one.

func WithIssuerValidator

func WithIssuerValidator(fn func(iss string) error) Option

WithIssuerValidator overrides the default strict issuer check. Use this to accept e.g. Microsoft Entra ID's tenant-GUID issuer pattern. Passing nil restores the default (strict equality with the issuer URL).

WARNING: when a validator is configured, the underlying go-oidc verifier's issuer check is disabled and the validator is the only gate. A buggy validator that returns nil unconditionally silently accepts any issuer — write the validator with care. Example:

oidc.WithIssuerValidator(func(iss string) error {
    if strings.HasPrefix(iss, "https://login.microsoftonline.com/") &&
        strings.HasSuffix(iss, "/v2.0") {
        return nil
    }
    return fmt.Errorf("unexpected issuer: %s", iss)
})

func WithLogoutHintProvider

func WithLogoutHintProvider(fn LogoutHintProvider) Option

WithLogoutHintProvider configures the callback used by the logout handler to populate `id_token_hint` on the end-session URL.

func WithOnLogout

func WithOnLogout(fn sso.OnLogout) Option

WithOnLogout registers a callback invoked before the RP-initiated logout redirect (if any).

func WithPostLogoutRedirectURL

func WithPostLogoutRedirectURL(u string) Option

WithPostLogoutRedirectURL sets the URL the IdP will redirect back to after a successful RP-initiated logout.

func WithTransitCookieName

func WithTransitCookieName(name string) Option

WithTransitCookieName overrides the default transit cookie name.

func WithTransitDeprecatedKeys

func WithTransitDeprecatedKeys(keys ...[]byte) Option

WithTransitDeprecatedKeys adds previously-used signing keys that are still accepted when verifying incoming transit cookies. Supports key rotation. Each key must meet the same minimum length as the primary.

func WithTransitTTL

func WithTransitTTL(d time.Duration) Option

WithTransitTTL overrides the default transit cookie lifetime (5 min).

func WithUserInfo

func WithUserInfo(enabled bool) Option

WithUserInfo enables a call to the UserInfo endpoint after the token exchange. Claims from UserInfo are merged into the result and override claims from the ID token on conflict. The UserInfo `sub` is verified to equal the ID token `sub` per OIDC Core §5.3.2 before merging.

type Payload

type Payload struct {
	// IDToken is the verified ID token. Treat as read-only: further
	// calls to Claims() decode into the caller's destination and are
	// otherwise side-effect free.
	IDToken *gooidc.IDToken
	// RawIDToken is the serialised JWT — useful as an id_token_hint on
	// RP-initiated logout, for forwarding, or for logging.
	RawIDToken string
	// AccessToken is the OAuth2 access token returned by the token
	// endpoint. It may be empty if the IdP only issued an ID token.
	AccessToken string
	// TokenExpiry is the access token's expiry.
	TokenExpiry time.Time
	// RefreshToken is the OAuth2 refresh token, present only when the
	// `offline_access` scope was granted.
	RefreshToken string
	// UserInfo holds the raw claims from the UserInfo endpoint, set only
	// if WithUserInfo(true) was supplied and the call succeeded.
	UserInfo map[string]any
}

Payload is the OIDC-specific data carried in sso.Subject[Payload].Raw.

type RP

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

RP is a constructed OIDC Relying Party. Obtain one from New and mount the values returned by Handlers onto the consumer's router.

func New

func New(
	issuerURL string,
	clientID string,
	clientSecret string,
	redirectURL string,
	transitSigningKey []byte,
	onAuthenticated sso.OnAuthenticated[Payload],
	opts ...Option,
) (*RP, error)

New constructs an OIDC Relying Party. It performs OIDC discovery synchronously; a slow or unreachable IdP surfaces as an error here (bounded by the bootstrap timeout).

The mandatory parameters are:

• issuerURL: OIDC issuer; all endpoints are populated from `<issuer>/.well-known/openid-configuration` unless overridden. Must be HTTPS; loopback hosts are allowed over HTTP for local development.
• clientID, clientSecret: confidential-client credentials.
• redirectURL: callback URL matching the redirect_uri registered at the IdP. HTTPS required (loopback exception applies).
• transitSigningKey: HMAC-SHA256 key used to sign the short-lived transit cookie carrying state, nonce and PKCE verifier. Minimum 32 bytes.
• onAuthenticated: callback invoked after a successful code exchange + ID token verification.

func (*RP) Handlers

func (rp *RP) Handlers() Handlers

Handlers returns the RP's HTTP handlers.