Help us shape the future of Go! Take the 2026 Go Developer Survey

oidc

package
v0.41.0 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: Apache-2.0, Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package oidc owns OIDC login, token verification, and Epithet identity mapping. Authenticate obtains credentials through browser or device login and refresh; callers own token state, session coordination, and progress output. Verifier checks tokens independently of directory mapping. Validator adds the configured mapping from verified claims to a directory user ID for CA and control. Directory lookup and authorization remain the responsibility of those services.

Index

Constants

This section is empty.

Variables

View Source
var ErrDeviceAuthorizationUnsupported = errors.New("OIDC issuer does not advertise device authorization")

ErrDeviceAuthorizationUnsupported means the issuer did not advertise the RFC 8628 endpoint required for device login.

View Source
var Scopes = []string{"openid", "profile", "email"}

Scopes is the fixed set requested during browser authentication. CA and control map verified tokens to directory users using their configured identity mode.

Functions

func Authenticate

func Authenticate(ctx context.Context, cfg LoginConfig, prev *oauth2.Token, out io.Writer) (idToken string, next *oauth2.Token, err error)

Authenticate obtains an ID token, reusing a valid token when available. prev carries refresh state from the previous call (nil on first use); the returned token is the next state. User-facing progress ("visit this URL…") is written to out.

func ResolveUserIDClaim

func ResolveUserIDClaim(issuer, override string) string

ResolveUserIDClaim uses only the configured issuer, never unverified token contents. Entra defaults apply to tenant-specific v1 and v2 issuer URLs. Other providers, including Google and Okta, default to the standard sub.

Types

type Claims

type Claims struct {
	// Issuer is the configured issuer against which the token was verified.
	Issuer string
	// Subject is the stable, case-sensitive identifier within this issuer.
	Subject string
	// UserID is the verified claim value used to look up the directory user.
	UserID string

	// ExpiresAt is when the token expires.
	ExpiresAt time.Time
}

Claims represents the claims extracted from an OIDC token.

type IdentityMode

type IdentityMode string

IdentityMode defines how a verified ID token maps to a directory user.

const (
	StableID      IdentityMode = "stable-id"
	VerifiedEmail IdentityMode = "verified-email"
)

func ResolveIdentity

func ResolveIdentity(issuer string, mode IdentityMode, override string) (IdentityMode, string, error)

ResolveIdentity validates identity settings without network access. Empty mode defaults to stable-id. Claim overrides, including email, are administrator choices and receive no special email-verification checks in stable-id mode.

type LoginConfig

type LoginConfig struct {
	IssuerURL    string
	ClientID     string
	ClientSecret string // Optional for PKCE.
	TLSConfig    tlsconfig.Config
	LoginMethod  LoginMethod
}

LoginConfig holds OIDC authentication configuration.

type LoginMethod

type LoginMethod uint8

LoginMethod selects the interactive operation used when neither a valid token nor a working refresh token is available. Its zero value preserves the browser-based behavior used before device authorization was added.

const (
	LoginBrowser LoginMethod = iota
	LoginDevice
)

type Validator

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

Validator verifies ID tokens and maps their claims to directory user IDs.

func NewValidator

func NewValidator(ctx context.Context, config ValidatorConfig) (*Validator, error)

NewValidator creates a new OIDC token validator. It performs OIDC discovery to fetch the provider's JWKS (public keys).

func (*Validator) Validate

func (v *Validator) Validate(ctx context.Context, tokenString string) (*Claims, error)

Validate validates an OIDC JWT token and extracts claims. Returns Claims if the token is valid, error otherwise.

type ValidatorConfig

type ValidatorConfig struct {
	// Issuer is the OIDC provider issuer URL (e.g., "https://accounts.google.com").
	Issuer string

	// ClientID is the expected audience claim. Required: without it, any
	// token issued by the provider for any client would be accepted.
	ClientID string

	// IdentityMode selects how verified claims resolve to a directory ID.
	IdentityMode IdentityMode

	// UserIDClaim selects a top-level string claim to map to directory ID.
	// Empty selects the provider default (oid for Entra, sub otherwise).
	UserIDClaim string

	// TLSConfig configures TLS for OIDC provider connections.
	TLSConfig tlsconfig.Config
}

ValidatorConfig configures the OIDC validator.

type Verifier

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

Verifier checks ID tokens independently of directory identity mapping. It can be shared by concurrent callers and caches the provider's signing keys.

func NewVerifier

func NewVerifier(ctx context.Context, config VerifierConfig) (*Verifier, error)

NewVerifier discovers the configured issuer and prepares token verification.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, token string) (*coreoidc.IDToken, error)

Verify checks signature, issuer, audience, expiry, and a nonempty subject. Callers may inspect claims only after this succeeds.

type VerifierConfig

type VerifierConfig struct {
	IssuerURL string
	ClientID  string
	TLSConfig tlsconfig.Config
}

VerifierConfig identifies the issuer and audience trusted for ID tokens. Login credentials and directory identity mapping are independent of verification.

Jump to

Keyboard shortcuts

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