jwt

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: Apache-2.0 Imports: 15 Imported by: 1

Documentation

Overview

Package jwt provides helpers for validating JSON Web Tokens (JWT) and composing claim predicates.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClaimsMapFromToken added in v0.5.4 

func ClaimsMapFromToken(tokenString string) (map[string]any, error)

ClaimsMapFromToken parses an unverified JWT and returns its payload claims as a map.

func CustomClaimsFromContext 

func CustomClaimsFromContext[T any](ctx context.Context) T

CustomClaimsFromContext extracts provider-specific custom claims from ctx.

The JWT middleware stores a *jwtvalidator.ValidatedClaims wrapper in the context. This function first attempts to unwrap the custom claims from that wrapper (ValidatedClaims.CustomClaims), and falls back to a direct type assertion for callers (e.g. unit tests) that store claims directly.

func CustomClaimsMapFromValidatedClaims added in v0.5.4 

func CustomClaimsMapFromValidatedClaims(vc *jwtvalidator.ValidatedClaims) (map[string]any, error)

CustomClaimsMapFromValidatedClaims converts ValidatedClaims.CustomClaims into a generic map.

func DefaultSignatureAlgorithms added in v0.5.5 

func DefaultSignatureAlgorithms() []jwtvalidator.SignatureAlgorithm

DefaultSignatureAlgorithms returns the repository default JWT signature algorithms in precedence order.

func ParseSignatureAlgorithm added in v0.5.5 

func ParseSignatureAlgorithm(raw string) (jwtvalidator.SignatureAlgorithm, error)

ParseSignatureAlgorithm parses a configured algorithm string into a supported validator.SignatureAlgorithm.

func RegisteredClaimsFromContext 

func RegisteredClaimsFromContext(ctx context.Context) *jwt.RegisteredClaims

RegisteredClaimsFromContext returns the registered JWT claims from ctx.

When the JWT middleware is in use, claims are stored as *jwtvalidator.ValidatedClaims; this function extracts the RegisteredClaims from that wrapper. For unit tests or legacy callers that store *jwt.RegisteredClaims directly, it falls back to a direct assertion.

func ResolveAllowedClockSkew added in v0.8.0 

func ResolveAllowedClockSkew(configuredSeconds int) time.Duration

ResolveAllowedClockSkew converts a configured clock-skew value in seconds to a Duration, defaulting to one minute when unset or non-positive.

func ResolveCustomClaimsMap added in v0.5.4 

func ResolveCustomClaimsMap(vc *jwtvalidator.ValidatedClaims, tokenString string) (map[string]any, error)

ResolveCustomClaimsMap returns a normalized custom-claims map for a validated token. It prefers structured validator custom claims and falls back to the JWT payload map.

func ResolveKeyFunc added in v0.8.0 

func ResolveKeyFunc(issuer string, cacheTTL time.Duration, provider *jwks.CachingProvider) (func(context.Context) (any, error), *jwks.CachingProvider, error)

ResolveKeyFunc returns a key function backed by a JWKS caching provider for issuer, reusing provider when it is already set rather than constructing a new one. cacheTTL non-positive defaults to five minutes. Returns the resolved provider so callers that need to reuse it can do so. Shared by jwt and oidc validator construction so both packages resolve signing keys via the same JWKS-discovery path.

func ResolveSignatureAlgorithms added in v0.5.5 

func ResolveSignatureAlgorithms(
	single string,
	multiple []string,
	defaults []jwtvalidator.SignatureAlgorithm,
) ([]jwtvalidator.SignatureAlgorithm, error)

ResolveSignatureAlgorithms resolves algorithm configuration from either the multi-value field, legacy single field, or provided defaults.

func SignatureAlgorithmsLabel added in v0.8.0 

func SignatureAlgorithmsLabel(algorithms []jwtvalidator.SignatureAlgorithm) string

SignatureAlgorithmsLabel renders algorithms as a comma-separated string for debug-log labels.

func ValidatedClaimsFromContext added in v0.4.0 

func ValidatedClaimsFromContext(ctx context.Context) *jwtvalidator.ValidatedClaims

ValidatedClaimsFromContext returns the *jwtvalidator.ValidatedClaims stored in ctx by the JWT middleware. Returns nil when no validated claims are present.

func WithLabel 

func WithLabel(key, value string) func(*ValidatorDebugger)

WithLabel enriches the logger with a label.

func WithLogger 

func WithLogger(logger zerolog.Logger) func(*ValidatorDebugger)

WithLogger sets the logger on the validator debugger.

Types

type ClaimKey 

type ClaimKey struct {
	Key   string
	Value any
}

ClaimKey is a claim key predicate

func (*ClaimKey) String 

func (c *ClaimKey) String() string

func (*ClaimKey) Validate 

func (c *ClaimKey) Validate(claims jwt.MapClaims) bool

type ClaimPredicate 

type ClaimPredicate interface {
	Validate(input jwt.MapClaims) bool
	String() string
}

ClaimPredicate defines an interface for validating JWT claims.

func And 

func And(children ...ClaimPredicate) ClaimPredicate

And combines the children with an AND

func Or 

func Or(children ...ClaimPredicate) ClaimPredicate

Or combines the children with an OR

func ParseClaimPredicates 

func ParseClaimPredicates(input any) ClaimPredicate

ParseClaimPredicates parses the input into a claim predicate

type MultiValidator 

type MultiValidator struct {
	Validators []TokenValidator
}

MultiValidator attempts to validate tokens using multiple validators in sequence.

func (*MultiValidator) String 

func (v *MultiValidator) String() string

func (*MultiValidator) ValidateToken 

func (v *MultiValidator) ValidateToken(ctx context.Context, tokenString string) (any, error)

type PredicateValidator 

type PredicateValidator struct {
	ParentValidator TokenValidator
	Predicate       ClaimPredicate
}

PredicateValidator wraps a TokenValidator and applies additional claim predicate validation.

func (*PredicateValidator) String 

func (v *PredicateValidator) String() string

func (*PredicateValidator) ValidateToken 

func (v *PredicateValidator) ValidateToken(ctx context.Context, tokenString string) (any, error)

type RegisteredClaims 

type RegisteredClaims = jwt.RegisteredClaims

RegisteredClaims is an alias for the standard JWT registered claims.

type TokenValidator 

type TokenValidator interface {
	ValidateToken(ctx context.Context, tokenString string) (any, error)
	String() string
}

TokenValidator defines the interface for validating tokens.

func NewAuth0Validator added in v0.8.0 

func NewAuth0Validator(v *jwtvalidator.Validator, issuer string) TokenValidator

NewAuth0Validator wraps an already-configured auth0/go-jwt-middleware Validator as a TokenValidator. Exported so packages that build their own jwtvalidator.Option pipeline (e.g. oidc, for HMAC/custom-claims support) can still produce the canonical TokenValidator wrapper instead of duplicating its type.

func NewMultiValidator added in v0.2.0 

func NewMultiValidator(validators ...TokenValidator) TokenValidator

func NewMultiValidatorFromConfig 

func NewMultiValidatorFromConfig(configs []ValidatorConfig, opts ...ValidatorOpt) (TokenValidator, error)

NewMultiValidatorFromConfig creates a MultiValidator from multiple configs.

func NewValidatorFromConfig 

func NewValidatorFromConfig(cfg *ValidatorConfig) (TokenValidator, error)

NewValidatorFromConfig creates a TokenValidator from a ValidatorConfig.

func NewValidatorFromConfigWithOptions 

func NewValidatorFromConfigWithOptions(cfg *ValidatorConfig, opts ...ValidatorOpt) (TokenValidator, error)

NewValidatorFromConfigWithOptions creates a TokenValidator from a ValidatorConfig using custom options.

func NewValidatorsFromConfig 

func NewValidatorsFromConfig(configs []ValidatorConfig, opts ...ValidatorOpt) ([]TokenValidator, error)

NewValidatorsFromConfig creates multiple validators from configs.

func WrapValidator added in v0.8.0 

func WrapValidator(tv TokenValidator, claimPredicate map[string]any, debug bool, debugOpts ...ValidatorDebugOpts) TokenValidator

WrapValidator layers optional claim-predicate and debug-logging wrappers onto tv, in that order, mirroring the config-driven wrapping pipeline used by NewValidatorFromConfigWithOptions. Shared by jwt and oidc validator construction so both packages apply claim_predicates/debug identically.

type ValidatorConfig 

type ValidatorConfig struct {
	Issuer              string         `json:"issuer" mapstructure:"issuer"`
	Audiences           []string       `json:"audiences" mapstructure:"audiences"`
	SignatureAlgorithm  string         `json:"signature_algorithm" mapstructure:"signature_algorithm"`
	SignatureAlgorithms []string       `json:"signature_algorithms" mapstructure:"signature_algorithms"`
	CacheTTL            int            `json:"cache_ttl_seconds" mapstructure:"cache_ttl_seconds"`
	AllowedClockSkew    int            `json:"allowed_clock_skew_seconds" mapstructure:"allowed_clock_skew_seconds"`
	Debug               bool           `json:"debug" mapstructure:"debug"`
	ClaimPredicate      map[string]any `json:"claim_predicates" mapstructure:"claim_predicates"`
}

ValidatorConfig contains configuration for a JWT token validator.

func FromMap 

func FromMap(m map[string]any) ValidatorConfig

FromMap creates a ValidatorConfig from a map.

type ValidatorDebugOpts 

type ValidatorDebugOpts func(*ValidatorDebugger)

ValidatorDebugOpts is a functional option for configuring a ValidatorDebugger.

type ValidatorDebugger 

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

ValidatorDebugger wraps a TokenValidator with debug logging capabilities.

func NewValidatorDebugger 

func NewValidatorDebugger(validator TokenValidator, opts ...ValidatorDebugOpts) *ValidatorDebugger

NewValidatorDebugger wraps a TokenValidator with debug logging.

func (*ValidatorDebugger) String 

func (v *ValidatorDebugger) String() string

func (*ValidatorDebugger) ValidateToken 

func (v *ValidatorDebugger) ValidateToken(ctx context.Context, tokenString string) (any, error)

type ValidatorOpt 

type ValidatorOpt func(*validatorOptions)

ValidatorOpt configures validator creation.

func WithValidatorJWKSProvider 

func WithValidatorJWKSProvider(provider *jwks.CachingProvider) ValidatorOpt

WithValidatorJWKSProvider sets a custom JWKS caching provider.

func WithValidatorKeyFunc 

func WithValidatorKeyFunc(keyFunc func(context.Context) (any, error)) ValidatorOpt

WithValidatorKeyFunc sets a custom key function for validation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.