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 ¶
- Variables
- func Authenticate(ctx context.Context, cfg LoginConfig, prev *oauth2.Token, out io.Writer) (idToken string, next *oauth2.Token, err 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.
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 ¶
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).
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.