Documentation
¶
Overview ¶
Package authn provides pluggable JWT authentication for the Transaction Token Service. Inspired by KEP-3331 (Structured Authentication Configuration), it supports an ordered list of JWT authenticators with OIDC discovery, CEL-based claim validation, and claim mapping.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Authenticator ¶
type Authenticator interface {
// Matches returns true if this authenticator handles tokens from the given issuer.
Matches(issuer string) bool
// Authenticate validates the token and returns the subject info.
Authenticate(ctx context.Context, token string) (*SubjectInfo, error)
}
Authenticator validates a subject token and returns the authenticated subject information.
type AuthenticatorConfig ¶
type AuthenticatorConfig struct {
Issuer IssuerConfig `json:"issuer" yaml:"issuer"`
ClaimValidationRules []ClaimValidationRule `json:"claimValidationRules,omitempty" yaml:"claimValidationRules,omitempty"`
ClaimMappings ClaimMappings `json:"claimMappings" yaml:"claimMappings"`
}
AuthenticatorConfig is the full configuration for a single JWT authenticator.
type ClaimMappings ¶
type ClaimMappings struct {
// Subject determines which claim becomes the TxToken's `sub`.
Subject ClaimOrExpression `json:"subject" yaml:"subject"`
// Extra carries additional identity attributes from the IdP token.
Extra []ExtraMapping `json:"extra,omitempty" yaml:"extra,omitempty"`
}
ClaimMappings defines how JWT claims are mapped to SubjectInfo fields.
type ClaimOrExpression ¶
type ClaimOrExpression struct {
// Claim is a simple JWT claim name (e.g., "email", "sub", "oid").
Claim string `json:"claim,omitempty" yaml:"claim,omitempty"`
// Expression is a CEL expression evaluated against the `claims` map.
Expression string `json:"expression,omitempty" yaml:"expression,omitempty"`
}
ClaimOrExpression specifies either a simple claim name or a CEL expression. Exactly one of Claim or Expression must be set.
type ClaimValidationRule ¶
type ClaimValidationRule struct {
// Expression is a CEL expression that must evaluate to true.
// The variable `claims` is available as a map[string]any.
Expression string `json:"expression" yaml:"expression"`
// Message is the error message when the expression returns false.
Message string `json:"message" yaml:"message"`
}
ClaimValidationRule is a CEL expression evaluated against raw JWT claims. If the expression returns false, the token is rejected.
type ExtraMapping ¶
type ExtraMapping struct {
// Key is the extra attribute key (e.g., "tenant", "name").
Key string `json:"key" yaml:"key"`
// ValueExpression is a CEL expression producing the value.
ValueExpression string `json:"valueExpression" yaml:"valueExpression"`
}
ExtraMapping maps a JWT claim to an extra key-value pair on SubjectInfo.
type IssuerConfig ¶
type IssuerConfig struct {
// URL is the issuer identifier. Must match the `iss` claim in incoming tokens.
URL string `json:"url" yaml:"url"`
// DiscoveryURL overrides where to fetch OIDC discovery metadata.
// If empty, defaults to {URL}/.well-known/openid-configuration.
DiscoveryURL string `json:"discoveryURL,omitempty" yaml:"discoveryURL,omitempty"`
// Audiences is the list of acceptable audience values.
Audiences []string `json:"audiences" yaml:"audiences"`
// AudienceMatchPolicy determines how audiences are matched.
// "MatchAny" means the token's aud must contain at least one configured audience.
AudienceMatchPolicy string `json:"audienceMatchPolicy,omitempty" yaml:"audienceMatchPolicy,omitempty"`
}
IssuerConfig defines the OIDC issuer configuration for a JWT authenticator.
type OIDCAuthenticator ¶
type OIDCAuthenticator struct {
// contains filtered or unexported fields
}
OIDCAuthenticator validates JWT tokens against an OIDC provider. It handles OIDC discovery, JWKS fetching, signature verification, audience validation, CEL claim validation, and claim mapping.
func NewOIDCAuthenticator ¶
func NewOIDCAuthenticator(config AuthenticatorConfig) (*OIDCAuthenticator, error)
NewOIDCAuthenticator creates a new OIDC authenticator from configuration. It compiles CEL expressions and optionally fetches OIDC discovery.
func (*OIDCAuthenticator) Authenticate ¶
func (a *OIDCAuthenticator) Authenticate(ctx context.Context, tokenString string) (*SubjectInfo, error)
Authenticate validates the token and returns subject info.
func (*OIDCAuthenticator) Matches ¶
func (a *OIDCAuthenticator) Matches(issuer string) bool
Matches returns true if this authenticator handles the given issuer.
func (*OIDCAuthenticator) SetJWKSURL ¶
func (a *OIDCAuthenticator) SetJWKSURL(url string)
SetJWKSURL allows directly setting the JWKS URL, bypassing OIDC discovery. Useful for testing and for issuers that don't support OIDC discovery.
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router routes incoming tokens to the correct authenticator based on the issuer claim. Authenticators are tried in order; the first matching one handles the token.
func NewRouter ¶
func NewRouter(authenticators []Authenticator) *Router
NewRouter creates a router from an ordered list of authenticators.
func (*Router) Authenticate ¶
Authenticate decodes the issuer from the token (without verification), routes to the matching authenticator, and performs full validation.
type SubjectInfo ¶
type SubjectInfo struct {
// Subject is the principal identifier (becomes the TxToken `sub` claim).
Subject string
// Extra contains additional identity attributes from claim mappings.
Extra map[string]string
}
SubjectInfo contains the authenticated identity extracted from a subject token.
Source Files