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.
Service discovery lifecycle ¶
CA and control use PrepareService to validate local configuration without contacting the issuer. The returned configuration shares discovery state with its lifecycle handle, preserving the ordinary service construction interfaces. Services open their listeners before calling Run, so a temporary discovery outage does not prevent bootstrap or readiness responses. Run retries transient discovery failures until recovery or shutdown; permanent configuration, trust, and discovery metadata errors terminate initialization. Interactive callers use NewValidator or NewVerifier for a single attempt.
Ready reports completed discovery, not current IdP reachability. Pending discovery returns ErrUnavailable without bypassing authentication. After discovery, signing-key fetching and token verification retain go-oidc's existing behavior. Services own the HTTP mapping of startup errors and readiness.
Index ¶
- Variables
- func Authenticate(ctx context.Context, cfg LoginConfig, prev *oauth2.Token, out io.Writer) (idToken string, next *oauth2.Token, err error)
- func PrepareService(config ValidatorConfig) (ValidatorConfig, *Validator, error)
- func ResolveUserIDClaim(issuer, override string) string
- type Claims
- type IdentityMode
- type LoginConfig
- type LoginMethod
- type Validator
- type ValidatorConfig
- type Verifier
- type VerifierConfig
Constants ¶
This section is empty.
Variables ¶
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.
ErrUnavailable distinguishes an unavailable authentication dependency from an invalid token during service startup. Signing-key verification errors retain their existing behavior; this class only represents pending discovery.
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 PrepareService ¶ added in v0.42.0
func PrepareService(config ValidatorConfig) (ValidatorConfig, *Validator, error)
PrepareService validates local configuration without contacting the issuer. Pass the returned configuration unchanged to service construction; validators built from it share the returned handle's discovery state. The service binds its listener, calls Run once on the handle, and uses Ready for startup status. Ordinary NewValidator configurations retain synchronous discovery.
func ResolveUserIDClaim ¶
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. Ordinary configurations perform one discovery attempt; configurations returned by PrepareService share its discovery state. Signing keys are fetched on demand.
func (*Validator) Ready ¶ added in v0.42.0
Ready reports completed discovery, independently of current IdP reachability.
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
// contains filtered or unexported fields
}
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) Ready ¶ added in v0.42.0
Ready reports whether discovery has completed, without probing the issuer.
Source Files