Files

40 KiB

jwt

import "github.com/effective-security/xpki/jwt"

Package jwt provides JSON Web Token (JWT) signing, verification, and parsing capabilities.

This package implements JWT as defined by RFC 7519, with support for:

  • JWT signing and verification using various algorithms (HMAC, RSA, ECDSA)
  • JWT parsing and validation with configurable verification options
  • JWKS (JSON Web Key Set) for key management and distribution

Subpackages: dpop (RFC 9449 proofs), accesstoken (opaque encrypted tokens), oauth2client (identity-provider client registry).

The package provides both high-level APIs for common use cases and lower-level primitives for advanced JWT operations.

Index

Constants

const (
    // DefaultJWKSRefreshCooldown is the minimum interval between the end of
    // one RemoteKeySet fetch and the start of the next.
    DefaultJWKSRefreshCooldown = 10 * time.Second
    // DefaultJWKSFetchTimeout bounds each RemoteKeySet fetch.
    DefaultJWKSFetchTimeout = 10 * time.Second
    // DefaultJWKSMaxResponseSize is the largest JWKS document, in bytes,
    // that RemoteKeySet accepts.
    DefaultJWKSMaxResponseSize = 1 << 20
)

const (
    // DefaultNotBefore offset for NotBefore
    DefaultNotBefore = -2 * time.Minute
)

Variables

var (
    // TimeNowFn to override in unit tests
    TimeNowFn = time.Now

    // DefaultTimeSkew is an interval for allowed time skew
    DefaultTimeSkew = 5 * time.Minute
)

var (
    // ErrKeyNotFound is returned when a KeySet has no key eligible to verify
    // a token with the requested kid and algorithm.
    ErrKeyNotFound = errors.New("key not found")
    // ErrAmbiguousKey is returned when more than one key is eligible to
    // verify a token with the requested kid and algorithm.
    ErrAmbiguousKey = errors.New("ambiguous key")
)

func CopyUserInfoClaims

func CopyUserInfoClaims(src, dst MapClaims)

CopyUserInfoClaims from source to destination

func DecodeSegment

func DecodeSegment(seg string) ([]byte, error)

DecodeSegment JWT specific base64url encoding with padding stripped

func EncodeSegment

func EncodeSegment(seg []byte) string

EncodeSegment returns JWT specific base64url encoding with padding stripped

func SetClaimsExpiration

func SetClaimsExpiration(claims MapClaims, expiry time.Duration)

SetClaimsExpiration sets expiration claims

func VerifySignature

func VerifySignature(algo, signingString, signature string, key any) error

VerifySignature returns error if JWT signature is invalid

type AlgorithmKeySet

AlgorithmKeySet is a KeySet that can also restrict key selection to keys compatible with the token's signing algorithm. The parser uses it when the configured KeySet implements it.

type AlgorithmKeySet interface {
    KeySet
    // GetKeyForAlgorithm returns the only key eligible to verify a token with
    // the given kid and alg headers. An empty keyID matches every key.
    GetKeyForAlgorithm(ctx context.Context, keyID, alg string) (any, error)
}

type Audience

Audience represents the recipients that the token is intended for.

type Audience []string

func (Audience) Contains

func (s Audience) Contains(expected string) bool

Contains returns true if audience contains expected value

func (*Audience) UnmarshalJSON

func (s *Audience) UnmarshalJSON(b []byte) error

UnmarshalJSON reads an audience from its JSON representation.

type Claims

Claims represents public claim values (as specified in RFC 7519).

type Claims struct {
    Issuer    string       `json:"iss,omitempty"`
    Subject   string       `json:"sub,omitempty"`
    Audience  Audience     `json:"aud,omitempty"`
    Expiry    *NumericDate `json:"exp,omitempty"`
    NotBefore *NumericDate `json:"nbf,omitempty"`
    IssuedAt  *NumericDate `json:"iat,omitempty"`
    ID        string       `json:"jti,omitempty"`

    // DPoP specific claims
    Cnf        *Cnf   `json:"cnf,omitempty"`
    Nonce      string `json:"nonce,omitempty"`
    HTTPMethod string `json:"htm,omitempty"`
    HTTPUri    string `json:"htu,omitempty"`

    // Custom most common claims
    Name          string `json:"name,omitempty"`
    Profile       string `json:"profile,omitempty"`
    Email         string `json:"email,omitempty"`
    EmailVerified bool   `json:"email_verified,omitempty"`
    Phone         string `json:"phone_number,omitempty"`
    PhoneVerified bool   `json:"phone_number_verified,omitempty"`
    // Role in the service
    Role   string `json:"role,omitempty"`
    Tenant string `json:"tenant,omitempty"`
    Org    string `json:"org,omitempty"`
    // map of Org:Role
    Orgs    map[string]string `json:"orgs,omitempty"`
    OrgRole string            `json:"org_role,omitempty"`
    Scope   Audience          `json:"scope,omitempty"`
}

func (*Claims) Marshal

func (c *Claims) Marshal() string

Marshal returns JSON encoded string

func (*Claims) Valid

func (c *Claims) Valid(cfg *VerifyConfig) error

Valid returns error if the standard claims are invalid

func (*Claims) VerifyAudience

func (c *Claims) VerifyAudience(expected []string) error

VerifyAudience compares the aud claim against expected.

func (*Claims) VerifyExpiresAt

func (c *Claims) VerifyExpiresAt(now time.Time, req bool) error

VerifyExpiresAt returns true issued at is valid.

func (*Claims) VerifyIssuedAt

func (c *Claims) VerifyIssuedAt(now time.Time, req bool) error

VerifyIssuedAt verifies the iat claim.

func (*Claims) VerifyIssuer

func (c *Claims) VerifyIssuer(expected string) error

VerifyIssuer compares the iss claim against expected.

func (*Claims) VerifyNotBefore

func (c *Claims) VerifyNotBefore(now time.Time, req bool) error

VerifyNotBefore verifies the nbf claim.

func (*Claims) VerifySubject

func (c *Claims) VerifySubject(expected string) error

VerifySubject compares the sub claim against expected.

type Cnf

Cnf is DPoP specific claim for JWT Key ID

type Cnf struct {
    Jkt string `json:"jkt,omitempty"`
}

type Key

Key for JWT signature

type Key struct {
    // ID of the key
    ID   string `json:"id" yaml:"id"`
    Seed string `json:"seed" yaml:"seed"`
}

type KeySet

KeySet is an interface for verifying JWT signatures.

type KeySet interface {
    // GetKey returns the key to verify a token with the given kid header.
    // An empty keyID selects the only signing-eligible key, if there is
    // exactly one.
    GetKey(ctx context.Context, keyID string) (any, error)
}

type Keyfunc

Keyfunc is a callback function to supply the key for verification. The function receives the parsed, but unverified Token. This allows you to use properties in the Header of the token (such as `kid`) to identify which key to use.

type Keyfunc func(*Token) (any, error)

type MapClaims

MapClaims provides generic claims on map

type MapClaims map[string]any

func CreateClaims

func CreateClaims(jti, subject, issuer string, audience []string, expiry time.Duration, extraClaims MapClaims) MapClaims

CreateClaims returns claims

func (MapClaims) Add

func (c MapClaims) Add(val ...any) error

Add new claims to the map

func (MapClaims) Bool

func (c MapClaims) Bool(k string) bool

Bool will return the named claim as Bool

func (MapClaims) CNF

func (c MapClaims) CNF() *Cnf

CNF returns DPoP cnf claim

func (MapClaims) Int

func (c MapClaims) Int(k string) int

Int will return the named claim as an int. Values that do not fit in an int, or cannot be parsed, return 0.

func (MapClaims) Int64

func (c MapClaims) Int64(k string) int64

Int64 will return the named claim as an int64. Values that do not fit in an int64, or cannot be parsed, return 0.

func (MapClaims) Marshal

func (c MapClaims) Marshal() string

Marshal returns JSON encoded string

func (MapClaims) NormalizeTimeClaims

func (c MapClaims) NormalizeTimeClaims() error

NormalizeTimeClaims replaces the exp, iat and nbf claims present in c by their Unix seconds, so that a time.Time, a *NumericDate or an RFC 3339 string is serialized as the NumericDate that Valid checks (XPKI-109). A value that Time cannot parse, or a zero time, is an error, and c is then unchanged. Signers call it on a copy of the caller's claims.

func (MapClaims) String

func (c MapClaims) String(k string) string

String will return the named claim as a string, if the underlying type is not a string, it will try and coerce it to a string.

func (MapClaims) Strings

func (c MapClaims) Strings(k string) []string

Strings will return the named claim as a []string

func (MapClaims) StringsMap

func (c MapClaims) StringsMap(k string) map[string]string

StringsMap will return the named claim as a map[string]string,

func (MapClaims) Time

func (c MapClaims) Time(k string) *time.Time

Time will return the named claim as Time pointer. It is nil when the claim is absent, and when it is present but not a time (logged at DEBUG); the Verify methods and Valid reject the latter (XPKI-125).

func (MapClaims) TimeVal

func (c MapClaims) TimeVal(k string) time.Time

TimeVal will return the named claim as Time value

func (MapClaims) To

func (c MapClaims) To(val any) error

To converts the claims to the value pointed to by v.

func (MapClaims) UInt64

func (c MapClaims) UInt64(k string) uint64

UInt64 will return the named claim as an uint64. Negative values, values that do not fit in an uint64, or values that cannot be parsed, return 0.

func (MapClaims) Valid

func (c MapClaims) Valid(cfg *VerifyConfig) error

Valid returns error if the standard claims are invalid

func (MapClaims) VerifyAudience

func (c MapClaims) VerifyAudience(expected []string) error

VerifyAudience compares the aud claim against expected.

func (MapClaims) VerifyExpiresAt

func (c MapClaims) VerifyExpiresAt(now time.Time, req bool) error

VerifyExpiresAt verifies the exp claim. A present exp that is not a time is an error (XPKI-125), a missing one only with req.

func (MapClaims) VerifyIssuedAt

func (c MapClaims) VerifyIssuedAt(now time.Time, req bool) error

VerifyIssuedAt verifies the iat claim. A present iat that is not a time is an error (XPKI-125), a missing one only with req.

func (MapClaims) VerifyIssuer

func (c MapClaims) VerifyIssuer(expected string) error

VerifyIssuer compares the iss claim against expected.

func (MapClaims) VerifyNotBefore

func (c MapClaims) VerifyNotBefore(now time.Time, req bool) error

VerifyNotBefore verifies the nbf claim. A present nbf that is not a time is an error (XPKI-125), a missing one only with req.

func (MapClaims) VerifySubject

func (c MapClaims) VerifySubject(expected string) error

VerifySubject compares the sub claim against expected.

type NumericDate

NumericDate represents date and time as the number of seconds since the epoch, ignoring leap seconds. Non-integer values can be represented in the serialized format (RFC 7519 Section 2); they are accepted on input and truncated to whole seconds, and always serialized as integers. See RFC7519 Section 2: https://tools.ietf.org/html/rfc7519#section-2

type NumericDate int64

func NewNumericDate

func NewNumericDate(t time.Time) *NumericDate

NewNumericDate constructs NumericDate from time.Time value.

func (NumericDate) MarshalJSON

func (n NumericDate) MarshalJSON() ([]byte, error)

MarshalJSON serializes the given NumericDate into its JSON representation.

func (*NumericDate) Time

func (n *NumericDate) Time() time.Time

Time returns time.Time representation of NumericDate.

func (*NumericDate) UnmarshalJSON

func (n *NumericDate) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a date from its JSON representation. Integer and fractional values are accepted, quoted or not; a fractional value is truncated toward zero to whole seconds.

type Option

A Option modifies the default behavior of Provider.

type Option interface {
    // contains filtered or unexported methods
}

func WithHeaders

func WithHeaders(headers map[string]any) Option

WithHeaders adds JOSE headers to signed tokens or overrides the defaults, such as typ. The constructor rejects an alg header that differs from the signing algorithm, and a kid header that would stop the provider from verifying its own tokens: with configured HS256 keys it must be the signing key's ID, and for NewProviderWithSymmetricKey it must be a nonempty string.

type Parser

Parser specifies JWT parser interface

type Parser interface {
    // ParseToken verifies the token signature and standard claims and returns MapClaims
    ParseToken(ctx context.Context, token string, cfg *VerifyConfig) (MapClaims, error)

    // GetRevocation returns the revocation checker, or nil if none is set
    GetRevocation() Revocation
    // SetRevocation installs a revocation checker consulted by ParseToken
    SetRevocation(Revocation)
}

func NewParser

func NewParser(cfg *ParserConfig) (Parser, error)

NewParser returns Parser

type ParserConfig

ParserConfig provides JWT parser configuration

type ParserConfig struct {
    // Issuer specifies issuer claim
    Issuer   string              `json:"issuer" yaml:"issuer"`
    JWKSURI  string              `json:"jwks_uri" yaml:"jwks_uri"`
    JWKeySet *jose.JSONWebKeySet `json:"jwks" yaml:"jwks"`
}

func LoadParserConfig

func LoadParserConfig(file string) (*ParserConfig, error)

LoadParserConfig returns parser configuration loaded from a file

type Provider

Provider specifies JWT provider interface

type Provider interface {
    Signer
    Parser
}

func LoadProvider

func LoadProvider(cfgfile string, crypto *cryptoprov.Crypto) (Provider, error)

LoadProvider returns new provider

func MustNewProvider

func MustNewProvider(cfg *ProviderConfig, crypto *cryptoprov.Crypto, ops ...Option) Provider

MustNewProvider returns new provider

func NewProvider

func NewProvider(cfg *ProviderConfig, crypto *cryptoprov.Crypto, ops ...Option) (Provider, error)

NewProvider returns new provider that supports, both Signer and Parser

func NewProviderFromCryptoSigner

func NewProviderFromCryptoSigner(signer crypto.Signer, ops ...Option) (Provider, error)

NewProviderFromCryptoSigner returns new from Signer

func NewProviderWithSymmetricKey

func NewProviderWithSymmetricKey(key []byte, ops ...Option) (Provider, error)

NewProviderWithSymmetricKey returns a provider that signs HS256 tokens with key and verifies its own tokens.

Tokens carry no kid header unless WithHeaders sets one, which must be a nonempty string. ParseToken accepts only HS256 tokens signed with key that have no kid or that kid; any other kid, including an empty or non-string one, is rejected (XPKI-066, XPKI-104).

type ProviderConfig

ProviderConfig provides OAuth2 configuration

type ProviderConfig struct {
    // Issuer specifies issuer claim
    Issuer string `json:"issuer" yaml:"issuer"`
    // KeyID specifies ID of the current key
    KeyID string `json:"kid" yaml:"kid"`
    // Keys specifies list of issuer's keys
    Keys []*Key `json:"keys" yaml:"keys"`

    // PrivateKey is a PEM-encoded key or a pkcs11: URI resolved through cryptoprov;
    // when set, the provider signs with RS*/ES* instead of HS256 keys
    PrivateKey string `json:"private_key" yaml:"private_key"`

    // TokenExpiry specifies token expiration period
    TokenExpiry csr.Duration `json:"token_expiry" yaml:"token_expiry"`
}

func LoadProviderConfig

func LoadProviderConfig(file string) (*ProviderConfig, error)

LoadProviderConfig returns provider configuration loaded from a file

type RemoteKeySet

RemoteKeySet is a KeySet implementation that validates JSON web tokens against a jwks_uri endpoint. Key selection follows the StaticKeySet rules for KeySet entries. Create it with NewRemoteKeySet.

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

func NewRemoteKeySet

func NewRemoteKeySet(ctx context.Context, jwksURL string, opts ...RemoteKeySetOption) *RemoteKeySet

NewRemoteKeySet returns a KeySet that fetches a JWKS document from jwksURL over HTTP. NewParser uses it when ParserConfig.JWKSURL is set. Keys are fetched lazily on the first lookup and re-fetched when no cached key fits the lookup; concurrent refreshes are coalesced, and a refresh starts at most once per refresh cooldown. ctx bounds the lifetime of every fetch; each fetch is also bounded by the fetch timeout and response size limit. Reuse one RemoteKeySet per URL rather than creating new ones.

func (*RemoteKeySet) GetKey

func (r *RemoteKeySet) GetKey(ctx context.Context, keyID string) (any, error)

GetKey returns the public key for the given kid.

func (*RemoteKeySet) GetKeyForAlgorithm

func (r *RemoteKeySet) GetKeyForAlgorithm(ctx context.Context, keyID, alg string) (any, error)

GetKeyForAlgorithm returns the public key for the given kid and alg.

type RemoteKeySetOption

RemoteKeySetOption configures a RemoteKeySet.

type RemoteKeySetOption func(*RemoteKeySet)

func WithFetchTimeout

func WithFetchTimeout(d time.Duration) RemoteKeySetOption

WithFetchTimeout bounds each fetch, including reading the body. Zero or negative keeps DefaultJWKSFetchTimeout.

func WithHTTPClient

func WithHTTPClient(client *http.Client) RemoteKeySetOption

WithHTTPClient sets the client used to fetch the JWKS document. The fetch timeout still applies to each request. A nil client keeps the default.

func WithMaxResponseSize

func WithMaxResponseSize(n int64) RemoteKeySetOption

WithMaxResponseSize sets the largest accepted JWKS document in bytes. Zero or negative keeps DefaultJWKSMaxResponseSize.

func WithRefreshCooldown

func WithRefreshCooldown(d time.Duration) RemoteKeySetOption

WithRefreshCooldown sets the minimum interval between the end of one fetch and the start of the next; lookups for unknown kids inside that window use the cached keys. Zero or negative disables throttling. The default is DefaultJWKSRefreshCooldown.

type Revocation

Revocation is an optional hook consulted by Parser.ParseToken after a token is verified, and used by callers to revoke tokens.

type Revocation interface {
    // Validate validates token claims,
    // it can be used to validate token revocation, etc.
    Validate(ctx context.Context, token string, claims MapClaims) error
    // Revoke revokes token
    Revoke(ctx context.Context, token string, claims MapClaims) error
}

type Signer

Signer specifies JWT signer interface

type Signer interface {
    // Sign returns a signed, compact-serialized JWT for the claims. The exp,
    // iat and nbf claims are written as NumericDate whatever their Go type,
    // time.Time included, see MapClaims.NormalizeTimeClaims; one that
    // MapClaims.Time cannot parse is an error. The claims map is not
    // modified.
    Sign(ctx context.Context, claims MapClaims) (string, error)
    // PublicKey is returned for asymmetric signer
    PublicKey() crypto.PublicKey
    // Issuer returns name of the issuer
    Issuer() string
    // TokenExpiry specifies token expiration period
    TokenExpiry() time.Duration
}

type SignerInfo

SignerInfo represents JWT signer

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

func NewSignerInfo

func NewSignerInfo(signer crypto.Signer) (*SignerInfo, error)

NewSignerInfo returns *SignerInfo

type StaticKeySet

StaticKeySet is a verifier that validates JWT against a static set of public keys.

A key is eligible when its JWK "use" is empty or "sig" and, when the token algorithm is known, its type, curve and JWK "alg" fit that algorithm. A token kid selects KeySet entries with that KeyID; when none has it, PublicKeys entries whose RFC 7638 SHA-256 thumbprint (base64url) equals the kid. An empty kid considers every entry of both lists. Exactly one eligible key must remain, otherwise GetKey returns ErrKeyNotFound or ErrAmbiguousKey.

type StaticKeySet struct {
    // PublicKeys used to verify the JWT. They have no kid, see StaticKeySet.
    // Supported types are *rsa.PublicKey and *ecdsa.PublicKey; any other
    // entry makes GetKey fail.
    PublicKeys []crypto.PublicKey
    KeySet     []jose.JSONWebKey
}

func (*StaticKeySet) GetKey

func (s *StaticKeySet) GetKey(ctx context.Context, keyID string) (any, error)

GetKey returns the public key for the given kid.

func (*StaticKeySet) GetKeyForAlgorithm

func (s *StaticKeySet) GetKeyForAlgorithm(_ context.Context, keyID, alg string) (any, error)

GetKeyForAlgorithm returns the public key for the given kid and alg.

type Token

Token for JWT

type Token struct {
    Raw           string         // The raw token.  Populated when you Parse a token
    SigningMethod string         // The signing method used or to be used
    Header        map[string]any // The first segment of the token
    Claims        ValidClaims    // The second segment of the token
    Signature     string         // The third segment of the token.  Populated when you Parse a token
    Valid         bool           // Is the token valid?  Populated when you Parse/Verify a token
}

type TokenParser

TokenParser config

type TokenParser struct {
    ValidMethods         []string // If populated, only these methods will be considered valid
    UseJSONNumber        bool     // Use JSON Number format in JSON decoder
    SkipClaimsValidation bool     // Skip claims validation during token parsing
}

func (*TokenParser) Parse

func (p *TokenParser) Parse(tokenString string, cfg *VerifyConfig, keyFunc Keyfunc) (*Token, error)

Parse parses and validates JWT, and return a token. keyFunc will receive the parsed token and should return the key for validating. If everything is kosher, err will be nil

func (*TokenParser) ParseUnverified

func (p *TokenParser) ParseUnverified(tokenString string, claims MapClaims) (token *Token, parts []string, err error)

ParseUnverified parses the token but doesn't validate the signature. It's only ever useful in cases where you know the signature is valid (because it has been checked previously in the stack) and you want to extract values from it. WARNING: Don't use this method unless you know what you're doing

func (*TokenParser) ParseWithClaims

func (p *TokenParser) ParseWithClaims(tokenString string, cfg *VerifyConfig, claims MapClaims, keyFunc Keyfunc) (*Token, error)

ParseWithClaims parses token with a specified Claims

type ValidClaims

ValidClaims interface for Claims validation

type ValidClaims interface {
    Valid(cfg *VerifyConfig) error
}

type VerifyConfig

VerifyConfig expresses the possible options for validating a JWT

type VerifyConfig struct {
    // ExpectedIssuer validates the iss claim of a JWT matches this value
    ExpectedIssuer string
    // ExpectedSubject validates the sub claim of a JWT matches this value
    ExpectedSubject string
    // ExpectedAudience validates that the aud claim of a JWT contains this value
    ExpectedAudience []string
}

Generated by gomarkdoc