...

Package jwt

import "github.com/lestrrat-go/jwx/jwt"
Overview
Index
Subdirectories

Overview ▾

Package jwt implements JSON Web Tokens as described in https://tools.ietf.org/html/rfc7519

Index ▾

Constants
func Equal(t1, t2 Token) bool
func ErrInvalidIssuedAt() error
func ErrTokenExpired() error
func ErrTokenNotYetValid() error
func IsValidationError(err error) bool
func RegisterCustomField(name string, object interface{})
func SetValidationCtxClock(ctx context.Context, cl Clock) context.Context
func SetValidationCtxSkew(ctx context.Context, dur time.Duration) context.Context
func Settings(options ...GlobalOption)
func Sign(t Token, alg jwa.SignatureAlgorithm, key interface{}, options ...SignOption) ([]byte, error)
func Validate(t Token, options ...ValidateOption) error
func ValidationCtxSkew(ctx context.Context) time.Duration
type Builder
    func NewBuilder() *Builder
    func (b *Builder) Audience(v []string) *Builder
    func (b *Builder) Build() (Token, error)
    func (b *Builder) Claim(name string, value interface{}) *Builder
    func (b *Builder) Expiration(v time.Time) *Builder
    func (b *Builder) IssuedAt(v time.Time) *Builder
    func (b *Builder) Issuer(v string) *Builder
    func (b *Builder) JwtID(v string) *Builder
    func (b *Builder) NotBefore(v time.Time) *Builder
    func (b *Builder) Subject(v string) *Builder
type ClaimPair
type Clock
    func ValidationCtxClock(ctx context.Context) Clock
type ClockFunc
    func (f ClockFunc) Now() time.Time
type DecodeCtx
type DecryptParameters
type EncryptOption
    func WithJweHeaders(hdrs jwe.Headers) EncryptOption
type GlobalOption
    func WithFlattenAudience(v bool) GlobalOption
type Iterator
type KeySetProvider
type KeySetProviderFunc
    func (fn KeySetProviderFunc) KeySetFrom(t Token) (jwk.Set, error)
type Option
type ParseOption
    func InferAlgorithmFromKey(v bool) ParseOption
    func UseDefaultKey(value bool) ParseOption
    func WithDecrypt(alg jwa.KeyEncryptionAlgorithm, key interface{}) ParseOption
    func WithFetchBackoff(b backoff.Policy) ParseOption
    func WithFetchWhitelist(wl jwk.Whitelist) ParseOption
    func WithHTTPClient(httpcl *http.Client) ParseOption
    func WithJWKSetFetcher(f jws.JWKSetFetcher) ParseOption
    func WithKeySet(set jwk.Set) ParseOption
    func WithKeySetProvider(p KeySetProvider) ParseOption
    func WithPedantic(v bool) ParseOption
    func WithToken(t Token) ParseOption
    func WithTypedClaim(name string, object interface{}) ParseOption
    func WithValidate(b bool) ParseOption
    func WithVerify(alg jwa.SignatureAlgorithm, key interface{}) ParseOption
    func WithVerifyAuto(v bool) ParseOption
type ParseRequestOption
    func WithFormKey(v string) ParseRequestOption
    func WithHeaderKey(v string) ParseRequestOption
type ReadFileOption
type SerializeCtx
type SerializeStep
type Serializer
    func NewSerializer() *Serializer
    func (s *Serializer) Encrypt(keyalg jwa.KeyEncryptionAlgorithm, key interface{}, contentalg jwa.ContentEncryptionAlgorithm, compressalg jwa.CompressionAlgorithm, options ...EncryptOption) *Serializer
    func (s *Serializer) Reset() *Serializer
    func (s *Serializer) Serialize(t Token) ([]byte, error)
    func (s *Serializer) Sign(alg jwa.SignatureAlgorithm, key interface{}, options ...SignOption) *Serializer
    func (s *Serializer) Step(step SerializeStep) *Serializer
type SignOption
    func WithHeaders(hdrs jws.Headers) SignOption
    func WithJwsHeaders(hdrs jws.Headers) SignOption
type Token
    func New() Token
    func Parse(s []byte, options ...ParseOption) (Token, error)
    func ParseForm(values url.Values, name string, options ...ParseOption) (Token, error)
    func ParseHeader(hdr http.Header, name string, options ...ParseOption) (Token, error)
    func ParseReader(src io.Reader, options ...ParseOption) (Token, error)
    func ParseRequest(req *http.Request, options ...ParseOption) (Token, error)
    func ParseString(s string, options ...ParseOption) (Token, error)
    func ReadFile(path string, options ...ReadFileOption) (Token, error)
type TokenWithDecodeCtx
type ValidateOption
    func WithAcceptableSkew(dur time.Duration) ValidateOption
    func WithAudience(s string) ValidateOption
    func WithClaimValue(name string, v interface{}) ValidateOption
    func WithClock(c Clock) ValidateOption
    func WithContext(ctx context.Context) ValidateOption
    func WithIssuer(s string) ValidateOption
    func WithJwtID(s string) ValidateOption
    func WithMaxDelta(dur time.Duration, c1, c2 string) ValidateOption
    func WithMinDelta(dur time.Duration, c1, c2 string) ValidateOption
    func WithRequiredClaim(name string) ValidateOption
    func WithSubject(s string) ValidateOption
    func WithValidator(v Validator) ValidateOption
type ValidationError
    func NewValidationError(err error) ValidationError
type Validator
    func ClaimContainsString(name, value string) Validator
    func ClaimValueIs(name string, value interface{}) Validator
    func IsExpirationValid() Validator
    func IsIssuedAtValid() Validator
    func IsNbfValid() Validator
    func IsRequired(name string) Validator
    func MaxDeltaIs(c1, c2 string, dur time.Duration) Validator
    func MinDeltaIs(c1, c2 string, dur time.Duration) Validator
type ValidatorFunc
    func (vf ValidatorFunc) Validate(ctx context.Context, tok Token) error
type VerifyParameters
type Visitor
type VisitorFunc

Package files

builder_gen.go http.go interface.go io.go jwt.go options.go serialize.go token_gen.go validate.go

Constants

const (
    AudienceKey   = "aud"
    ExpirationKey = "exp"
    IssuedAtKey   = "iat"
    IssuerKey     = "iss"
    JwtIDKey      = "jti"
    NotBeforeKey  = "nbf"
    SubjectKey    = "sub"
)

func Equal

func Equal(t1, t2 Token) bool

Equal compares two JWT tokens. Do not use `reflect.Equal` or the like to compare tokens as they will also compare extra detail such as sync.Mutex objects used to control concurrent access.

The comparison for values is currently done using a simple equality ("=="), except for time.Time, which uses time.Equal after dropping the monotonic clock and truncating the values to 1 second accuracy.

if both t1 and t2 are nil, returns true

func ErrInvalidIssuedAt

func ErrInvalidIssuedAt() error

ErrInvalidIssuedAt returns the immutable error used when `iat` claim is not satisfied

func ErrTokenExpired

func ErrTokenExpired() error

ErrTokenExpired returns the immutable error used when `exp` claim is not satisfied

func ErrTokenNotYetValid

func ErrTokenNotYetValid() error

func IsValidationError

func IsValidationError(err error) bool

IsValidationError returns true if the error is a validation error

func RegisterCustomField

func RegisterCustomField(name string, object interface{})

RegisterCustomField allows users to specify that a private field be decoded as an instance of the specified type. This option has a global effect.

For example, suppose you have a custom field `x-birthday`, which you want to represent as a string formatted in RFC3339 in JSON, but want it back as `time.Time`.

In that case you would register a custom field as follows

jwt.RegisterCustomField(`x-birthday`, timeT)

Then `token.Get("x-birthday")` will still return an `interface{}`, but you can convert its type to `time.Time`

bdayif, _ := token.Get(`x-birthday`)
bday := bdayif.(time.Time)

func SetValidationCtxClock

func SetValidationCtxClock(ctx context.Context, cl Clock) context.Context

func SetValidationCtxSkew

func SetValidationCtxSkew(ctx context.Context, dur time.Duration) context.Context

func Settings

func Settings(options ...GlobalOption)

Settings controls global settings that are specific to JWTs.

func Sign

func Sign(t Token, alg jwa.SignatureAlgorithm, key interface{}, options ...SignOption) ([]byte, error)

Sign is a convenience function to create a signed JWT token serialized in compact form.

It accepts either a raw key (e.g. rsa.PrivateKey, ecdsa.PrivateKey, etc) or a jwk.Key, and the name of the algorithm that should be used to sign the token.

If the key is a jwk.Key and the key contains a key ID (`kid` field), then it is added to the protected header generated by the signature

The algorithm specified in the `alg` parameter must be able to support the type of key you provided, otherwise an error is returned.

The protected header will also automatically have the `typ` field set to the literal value `JWT`, unless you provide a custom value for it by jwt.WithHeaders option.

func Validate

func Validate(t Token, options ...ValidateOption) error

Validate makes sure that the essential claims stand.

See the various `WithXXX` functions for optional parameters that can control the behavior of this method.

func ValidationCtxSkew

func ValidationCtxSkew(ctx context.Context) time.Duration

type Builder

Builder is a convenience wrapper around the New() constructor and the Set() methods to assign values to Token claims. Users can successively call Claim() on the Builder, and have it construct the Token when Build() is called. This alleviates the need for the user to check for the return value of every single Set() method call. Note that each call to Claim() overwrites the value set from the previous call.

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

func NewBuilder

func NewBuilder() *Builder

func (*Builder) Audience

func (b *Builder) Audience(v []string) *Builder

func (*Builder) Build

func (b *Builder) Build() (Token, error)

Build creates a new token based on the claims that the builder has received so far. If a claim cannot be set, then the method returns a nil Token with a en error as a second return value

func (*Builder) Claim

func (b *Builder) Claim(name string, value interface{}) *Builder

func (*Builder) Expiration

func (b *Builder) Expiration(v time.Time) *Builder

func (*Builder) IssuedAt

func (b *Builder) IssuedAt(v time.Time) *Builder

func (*Builder) Issuer

func (b *Builder) Issuer(v string) *Builder

func (*Builder) JwtID

func (b *Builder) JwtID(v string) *Builder

func (*Builder) NotBefore

func (b *Builder) NotBefore(v time.Time) *Builder

func (*Builder) Subject

func (b *Builder) Subject(v string) *Builder

type ClaimPair

type ClaimPair = mapiter.Pair

type Clock

type Clock interface {
    Now() time.Time
}

func ValidationCtxClock

func ValidationCtxClock(ctx context.Context) Clock

ValidationCtxClock returns the Clock object associated with the current validation context. This value will always be available during validation of tokens.

type ClockFunc

type ClockFunc func() time.Time

func (ClockFunc) Now

func (f ClockFunc) Now() time.Time

type DecodeCtx

type DecodeCtx = json.DecodeCtx

type DecryptParameters

type DecryptParameters interface {
    Algorithm() jwa.KeyEncryptionAlgorithm
    Key() interface{}
}

type EncryptOption

EncryptOption describes an Option that can be passed to Encrypt() or (jwt.Serializer).Encrypt

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

func WithJweHeaders

func WithJweHeaders(hdrs jwe.Headers) EncryptOption

WithJweHeaders is passed to "jwt.Serializer".Encrypt() method to allow specifying arbitrary header values to be included in the protected header of the JWE message

type GlobalOption

GlobalOption describes an Option that can be passed to `Settings()`.

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

func WithFlattenAudience

func WithFlattenAudience(v bool) GlobalOption

WithFlattenAudience specifies if the "aud" claim should be flattened to a single string upon the token being serialized to JSON.

This is sometimes important when a JWT consumer does not understand that the "aud" claim can actually take the form of an array of strings.

The default value is `false`, which means that "aud" claims are always rendered as a arrays of strings. This setting has a global effect, and will change the behavior for all JWT serialization.

type Iterator

type Iterator = mapiter.Iterator

type KeySetProvider

KeySetProvider is an interface for objects that can choose the appropriate jwk.Set to be used when verifying JWTs

type KeySetProvider interface {
    // KeySetFrom returns the jwk.Set to be used to verify the token.
    // Keep in mind that the token at the point when the method is called is NOT VERIFIED.
    // DO NOT trust the contents of the Token too much. For example, do not take the
    // hint as to which signature algorithm to use from the token itself.
    KeySetFrom(Token) (jwk.Set, error)
}

type KeySetProviderFunc

KeySetProviderFunc is an implementation of KeySetProvider that is based on a function.

type KeySetProviderFunc func(Token) (jwk.Set, error)

func (KeySetProviderFunc) KeySetFrom

func (fn KeySetProviderFunc) KeySetFrom(t Token) (jwk.Set, error)

type Option

type Option = option.Interface

type ParseOption

ParseOption describes an Option that can be passed to `Parse()`. ParseOption also implements ReadFileOption, therefore it may be safely pass them to `jwt.ReadFile()`

type ParseOption interface {
    ReadFileOption
    // contains filtered or unexported methods
}

func InferAlgorithmFromKey

func InferAlgorithmFromKey(v bool) ParseOption

InferAlgorithmFromKey allows jwt.Parse to guess the signature algorithm passed to `jws.Verify()`, in case the key you provided does not have a proper `alg` header.

Compared to providing explicit `alg` from the key this is slower, and in case our heuristics are wrong or outdated, may fail to verify the token. Also, automatic detection of signature verification methods are always more vulnerable for potential attack vectors.

It is highly recommended that you fix your key to contain a proper `alg` header field instead of resorting to using this option, but sometimes it just needs to happen.

Your JWT still need to have an `alg` field, and it must match one of the candidates that we produce for your key

func UseDefaultKey

func UseDefaultKey(value bool) ParseOption

UseDefaultKey is used in conjunction with the option WithKeySet to instruct the Parse method to default to the single key in a key set when no Key ID is included in the JWT. If the key set contains multiple keys then the default behavior is unchanged -- that is, the since we can't determine the key to use, it returns an error.

func WithDecrypt

func WithDecrypt(alg jwa.KeyEncryptionAlgorithm, key interface{}) ParseOption

WithDecrypt allows users to specify parameters for decryption using `jwe.Decrypt`. You must specify this if your JWT is encrypted.

func WithFetchBackoff

func WithFetchBackoff(b backoff.Policy) ParseOption

WithFetchBackoff specifies the `backoff.Policy` object that should be passed to `jws.VerifyAuto()`, which in turn will be passed to `jwk.Fetch()`

This is a wrapper over `jws.WithFetchBackoff()` that can be passed to `jwt.Parse()`, and will be ignored if you spcify `jws.WithJWKSetFetcher()`

func WithFetchWhitelist

func WithFetchWhitelist(wl jwk.Whitelist) ParseOption

WithFetchWhitelist specifies the `jwk.Whitelist` object that should be passed to `jws.VerifyAuto()`, which in turn will be passed to `jwk.Fetch()`

This is a wrapper over `jws.WithFetchWhitelist()` that can be passed to `jwt.Parse()`, and will be ignored if you spcify `jws.WithJWKSetFetcher()`

func WithHTTPClient

func WithHTTPClient(httpcl *http.Client) ParseOption

WithHTTPClient specifies the `*http.Client` object that should be passed to `jws.VerifyAuto()`, which in turn will be passed to `jwk.Fetch()`

This is a wrapper over `jws.WithHTTPClient()` that can be passed to `jwt.Parse()`, and will be ignored if you spcify `jws.WithJWKSetFetcher()`

func WithJWKSetFetcher

func WithJWKSetFetcher(f jws.JWKSetFetcher) ParseOption

WithJWKSetFetcher specifies the `jws.JWKSetFetcher` object that should be passed to `jws.VerifyAuto()`

This is a wrapper over `jws.WithJWKSetFetcher()` that can be passed to `jwt.Parse()`.

func WithKeySet

func WithKeySet(set jwk.Set) ParseOption

WithKeySet forces the Parse method to verify the JWT message using one of the keys in the given key set.

The key and the JWT MUST have a proper `kid` field set. The key to use for signature verification is chosen by matching the Key ID of the JWT and the ID of the given key set.

When using this option, keys MUST have a proper 'alg' field set. This is because we need to know the exact algorithm that you (the user) wants to use to verify the token. We do NOT trust the token's headers, because they can easily be tampered with.

However, there _is_ a workaround if you do understand the risks of allowing a library to automatically choose a signature verification strategy, and you do not mind the verification process having to possibly attempt using multiple times before succeeding to verify. See `jwt.InferAlgorithmFromKey` option

If you have only one key in the set, and are sure you want to use that key, you can use the `jwt.WithDefaultKey` option.

If provided with WithKeySetProvider(), this option takes precedence.

func WithKeySetProvider

func WithKeySetProvider(p KeySetProvider) ParseOption

WithKeySetProvider allows users to specify an object to choose which jwk.Set to use for verification.

If provided with WithKeySet(), WithKeySet() option takes precedence.

func WithPedantic

func WithPedantic(v bool) ParseOption

WithPedantic enables pedantic mode for parsing JWTs. Currently this only applies to checking for the correct `typ` and/or `cty` when necessary.

func WithToken

func WithToken(t Token) ParseOption

WithToken specifies the token instance that is used when parsing JWT tokens.

func WithTypedClaim

func WithTypedClaim(name string, object interface{}) ParseOption

WithTypedClaim allows a private claim to be parsed into the object type of your choice. It works much like the RegisterCustomField, but the effect is only applicable to the jwt.Parse function call which receives this option.

While this can be extremely useful, this option should be used with caution: There are many caveats that your entire team/user-base needs to be aware of, and therefore in general its use is discouraged. Only use it when you know what you are doing, and you document its use clearly for others.

First and foremost, this is a "per-object" option. Meaning that given the same serialized format, it is possible to generate two objects whose internal representations may differ. That is, if you parse one _WITH_ the option, and the other _WITHOUT_, their internal representation may completely differ. This could potentially lead to problems.

Second, specifying this option will slightly slow down the decoding process as it needs to consult multiple definitions sources (global and local), so be careful if you are decoding a large number of tokens, as the effects will stack up.

Finally, this option will also NOT work unless the tokens themselves support such parsing mechanism. For example, while tokens obtained from `jwt.New()` and `openid.New()` will respect this option, if you provide your own custom token type, it will need to implement the TokenWithDecodeCtx interface.

func WithValidate

func WithValidate(b bool) ParseOption

WithValidate is passed to `Parse()` method to denote that the validation of the JWT token should be performed after a successful parsing of the incoming payload.

func WithVerify

func WithVerify(alg jwa.SignatureAlgorithm, key interface{}) ParseOption

WithVerify forces the Parse method to verify the JWT message using the given key. XXX Should have been named something like WithVerificationKey

func WithVerifyAuto

func WithVerifyAuto(v bool) ParseOption

WithVerifyAuto specifies that the JWS verification should be performed using `jws.VerifyAuto()`, which in turn attempts to verify the message using values that are stored within the JWS message.

Only passing this option to `jwt.Parse()` will not result in a successful verification. Please make sure to carefully read the documentation in `jws.VerifyAuto()`, and provide the necessary Whitelist object via `jwt.WithFetchWhitelist()`

You might also consider using a backoff policy by using `jwt.WithFetchBackoff()` to control the number of requests being made.

type ParseRequestOption

ParseRequestOption describes an Option that can be passed to `ParseRequest()`.

type ParseRequestOption interface {
    ParseOption
    // contains filtered or unexported methods
}

func WithFormKey

func WithFormKey(v string) ParseRequestOption

WithFormKey is used to specify header keys to search for tokens.

While the type system allows this option to be passed to jwt.Parse() directly, doing so will have no effect. Only use it for HTTP request parsing functions

func WithHeaderKey

func WithHeaderKey(v string) ParseRequestOption

WithHeaderKey is used to specify header keys to search for tokens.

While the type system allows this option to be passed to jwt.Parse() directly, doing so will have no effect. Only use it for HTTP request parsing functions

type ReadFileOption

ReadFileOption describes options that can be passed to ReadFile.

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

type SerializeCtx

type SerializeCtx interface {
    Step() int
    Nested() bool
}

type SerializeStep

type SerializeStep interface {
    Serialize(SerializeCtx, interface{}) (interface{}, error)
}

type Serializer

Serializer is a generic serializer for JWTs. Whereas other conveinience functions can only do one thing (such as generate a JWS signed JWT), Using this construct you can serialize the token however you want.

By default the serializer only marshals the token into a JSON payload. You must set up the rest of the steps that should be taken by the serializer.

For example, to marshal the token into JSON, then apply JWS and JWE in that order, you would do:

serialized, err := jwt.NewSerialer().
   Sign(jwa.RS256, key).
   Encrypt(jwa.RSA_OAEP, key.PublicKey).
   Serialize(token)

The `jwt.Sign()` function is equivalent to

serialized, err := jwt.NewSerializer().
   Sign(...args...).
   Serialize(token)
type Serializer struct {
    // contains filtered or unexported fields
}

func NewSerializer

func NewSerializer() *Serializer

NewSerializer creates a new empty serializer.

func (*Serializer) Encrypt

func (s *Serializer) Encrypt(keyalg jwa.KeyEncryptionAlgorithm, key interface{}, contentalg jwa.ContentEncryptionAlgorithm, compressalg jwa.CompressionAlgorithm, options ...EncryptOption) *Serializer

func (*Serializer) Reset

func (s *Serializer) Reset() *Serializer

Reset clears all of the registered steps.

func (*Serializer) Serialize

func (s *Serializer) Serialize(t Token) ([]byte, error)

func (*Serializer) Sign

func (s *Serializer) Sign(alg jwa.SignatureAlgorithm, key interface{}, options ...SignOption) *Serializer

func (*Serializer) Step

func (s *Serializer) Step(step SerializeStep) *Serializer

Step adds a new Step to the serialization process

type SignOption

SignOption describes an Option that can be passed to Sign() or (jwt.Serializer).Sign

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

func WithHeaders

func WithHeaders(hdrs jws.Headers) SignOption

WithHeaders is passed to `jwt.Sign()` function, to allow specifying arbitrary header values to be included in the header section of the jws message

This option will be deprecated in the next major version. Use jwt.WithJwsHeaders() instead.

func WithJwsHeaders

func WithJwsHeaders(hdrs jws.Headers) SignOption

WithJwsHeaders is passed to `jwt.Sign()` function or "jwt.Serializer".Sign() method, to allow specifying arbitrary header values to be included in the header section of the JWE message

type Token

Token represents a generic JWT token. which are type-aware (to an extent). Other claims may be accessed via the `Get`/`Set` methods but their types are not taken into consideration at all. If you have non-standard claims that you must frequently access, consider creating accessors functions like the following

func SetFoo(tok jwt.Token) error func GetFoo(tok jwt.Token) (*Customtyp, error)

Embedding jwt.Token into another struct is not recommended, because jwt.Token needs to handle private claims, and this really does not work well when it is embedded in other structure

type Token interface {

    // Audience returns the value for "aud" field of the token
    Audience() []string

    // Expiration returns the value for "exp" field of the token
    Expiration() time.Time

    // IssuedAt returns the value for "iat" field of the token
    IssuedAt() time.Time

    // Issuer returns the value for "iss" field of the token
    Issuer() string

    // JwtID returns the value for "jti" field of the token
    JwtID() string

    // NotBefore returns the value for "nbf" field of the token
    NotBefore() time.Time

    // Subject returns the value for "sub" field of the token
    Subject() string

    // PrivateClaims return the entire set of fields (claims) in the token
    // *other* than the pre-defined fields such as `iss`, `nbf`, `iat`, etc.
    PrivateClaims() map[string]interface{}

    // Get returns the value of the corresponding field in the token, such as
    // `nbf`, `exp`, `iat`, and other user-defined fields. If the field does not
    // exist in the token, the second return value will be `false`
    //
    // If you need to access fields like `alg`, `kid`, `jku`, etc, you need
    // to access the corresponding fields in the JWS/JWE message. For this,
    // you will need to access them by directly parsing the payload using
    // `jws.Parse` and `jwe.Parse`
    Get(string) (interface{}, bool)

    // Set assigns a value to the corresponding field in the token. Some
    // pre-defined fields such as `nbf`, `iat`, `iss` need their values to
    // be of a specific type. See the other getter methods in this interface
    // for the types of each of these fields
    Set(string, interface{}) error
    Remove(string) error
    Clone() (Token, error)
    Iterate(context.Context) Iterator
    Walk(context.Context, Visitor) error
    AsMap(context.Context) (map[string]interface{}, error)
}

func New

func New() Token

New creates a standard token, with minimal knowledge of possible claims. Standard claims include"aud", "exp", "iat", "iss", "jti", "nbf" and "sub". Convenience accessors are provided for these standard claims

func Parse

func Parse(s []byte, options ...ParseOption) (Token, error)

Parse parses the JWT token payload and creates a new `jwt.Token` object. The token must be encoded in either JSON format or compact format.

This function can work with encrypted and/or signed tokens. Any combination of JWS and JWE may be applied to the token, but this function will only attempt to verify/decrypt up to 2 levels (i.e. JWS only, JWE only, JWS then JWE, or JWE then JWS)

If the token is signed and you want to verify the payload matches the signature, you must pass the jwt.WithVerify(alg, key) or jwt.WithKeySet(jwk.Set) option. If you do not specify these parameters, no verification will be performed.

During verification, if the JWS headers specify a key ID (`kid`), the key used for verification must match the specified ID. If you are somehow using a key without a `kid` (which is highly unlikely if you are working with a JWT from a well know provider), you can workaround this by modifying the `jwk.Key` and setting the `kid` header.

If you also want to assert the validity of the JWT itself (i.e. expiration and such), use the `Validate()` function on the returned token, or pass the `WithValidate(true)` option. Validate options can also be passed to `Parse`

This function takes both ParseOption and ValidateOption types: ParseOptions control the parsing behavior, and ValidateOptions are passed to `Validate()` when `jwt.WithValidate` is specified.

func ParseForm

func ParseForm(values url.Values, name string, options ...ParseOption) (Token, error)

ParseForm parses a JWT stored in a url.Value.

func ParseHeader

func ParseHeader(hdr http.Header, name string, options ...ParseOption) (Token, error)

ParseHeader parses a JWT stored in a http.Header.

For the header "Authorization", it will strip the prefix "Bearer " and will treat the remaining value as a JWT.

func ParseReader

func ParseReader(src io.Reader, options ...ParseOption) (Token, error)

ParseReader calls Parse against an io.Reader

func ParseRequest

func ParseRequest(req *http.Request, options ...ParseOption) (Token, error)

ParseRequest searches a http.Request object for a JWT token.

Specifying WithHeaderKey() will tell it to search under a specific header key. Specifying WithFormKey() will tell it to search under a specific form field.

By default, "Authorization" header will be searched.

If WithHeaderKey() is used, you must explicitly re-enable searching for "Authorization" header.

# searches for "Authorization"
jwt.ParseRequest(req)

# searches for "x-my-token" ONLY.
jwt.ParseRequest(req, jwt.WithHeaderKey("x-my-token"))

# searches for "Authorization" AND "x-my-token"
jwt.ParseRequest(req, jwt.WithHeaderKey("Authorization"), jwt.WithHeaderKey("x-my-token"))

func ParseString

func ParseString(s string, options ...ParseOption) (Token, error)

ParseString calls Parse against a string

func ReadFile

func ReadFile(path string, options ...ReadFileOption) (Token, error)

type TokenWithDecodeCtx

type TokenWithDecodeCtx = json.DecodeCtxContainer

type ValidateOption

ValidateOption describes an Option that can be passed to Validate(). ValidateOption also implements ParseOption, therefore it may be safely passed to `Parse()` (and thus `jwt.ReadFile()`)

type ValidateOption interface {
    ParseOption
    // contains filtered or unexported methods
}

func WithAcceptableSkew

func WithAcceptableSkew(dur time.Duration) ValidateOption

WithAcceptableSkew specifies the duration in which exp and nbf claims may differ by. This value should be positive

func WithAudience

func WithAudience(s string) ValidateOption

WithAudience specifies that expected audience value. `Validate()` will return true if one of the values in the `aud` element matches this value. If not specified, the value of issuer is not verified at all.

func WithClaimValue

func WithClaimValue(name string, v interface{}) ValidateOption

WithClaimValue specifies the expected value for a given claim

func WithClock

func WithClock(c Clock) ValidateOption

WithClock specifies the `Clock` to be used when verifying claims exp and nbf.

func WithContext

func WithContext(ctx context.Context) ValidateOption

WithContext allows you to specify a context.Context object to be used with `jwt.Validate()` option.

Please be aware that in the next major release of this library, `jwt.Validate()`'s signature will change to include an explicit `context.Context` object.

func WithIssuer

func WithIssuer(s string) ValidateOption

WithIssuer specifies that expected issuer value. If not specified, the value of issuer is not verified at all.

func WithJwtID

func WithJwtID(s string) ValidateOption

WithJwtID specifies that expected jti value. If not specified, the value of jti is not verified at all.

func WithMaxDelta

func WithMaxDelta(dur time.Duration, c1, c2 string) ValidateOption

WithMaxDelta specifies that given two claims `c1` and `c2` that represent time, the difference in time.Duration must be less than equal to the value specified by `d`. If `c1` or `c2` is the empty string, the current time (as computed by `time.Now` or the object passed via `WithClock()`) is used for the comparison.

`c1` and `c2` are also assumed to be required, therefore not providing either claim in the token will result in an error.

Because there is no way of reliably knowing how to parse private claims, we currently only support `iat`, `exp`, and `nbf` claims.

If the empty string is passed to c1 or c2, then the current time (as calculated by time.Now() or the clock object provided via WithClock()) is used.

For example, in order to specify that `exp` - `iat` should be less than 10*time.Second, you would write

jwt.Validate(token, jwt.WithMaxDelta(10*time.Second, jwt.ExpirationKey, jwt.IssuedAtKey))

If AcceptableSkew of 2 second is specified, the above will return valid for any value of `exp` - `iat` between 8 (10-2) and 12 (10+2).

func WithMinDelta

func WithMinDelta(dur time.Duration, c1, c2 string) ValidateOption

WithMinDelta is almost exactly the same as WithMaxDelta, but force validation to fail if the difference between time claims are less than dur.

For example, in order to specify that `exp` - `iat` should be greater than 10*time.Second, you would write

jwt.Validate(token, jwt.WithMinDelta(10*time.Second, jwt.ExpirationKey, jwt.IssuedAtKey))

The validation would fail if the difference is less than 10 seconds.

func WithRequiredClaim

func WithRequiredClaim(name string) ValidateOption

WithRequiredClaim specifies that the claim identified the given name must exist in the token. Only the existence of the claim is checked: the actual value associated with that field is not checked.

func WithSubject

func WithSubject(s string) ValidateOption

WithSubject specifies that expected subject value. If not specified, the value of subject is not verified at all.

func WithValidator

func WithValidator(v Validator) ValidateOption

WithValidator validates the token with the given Validator.

For example, in order to validate tokens that are only valid during August, you would write

 validator := jwt.ValidatorFunc(func(_ context.Context, t jwt.Token) error {
   if time.Now().Month() != 8 {
     return fmt.Errorf(`tokens are only valid during August!`)
   }
   return nil
 })
err := jwt.Validate(token, jwt.WithValidator(validator))

type ValidationError

type ValidationError interface {
    error
    // contains filtered or unexported methods
}

func NewValidationError

func NewValidationError(err error) ValidationError

type Validator

Validator describes interface to validate a Token.

type Validator interface {
    // Validate should return an error if a required conditions is not met.
    // This method will be changed in the next major release to return
    // jwt.ValidationError instead of error to force users to return
    // a validation error even for user-specified validators
    Validate(context.Context, Token) error
}

func ClaimContainsString

func ClaimContainsString(name, value string) Validator

ClaimContainsString can be used to check if the claim called `name`, which is expected to be a list of strings, contains `value`. Currently because of the implementation this will probably only work for `aud` fields.

func ClaimValueIs

func ClaimValueIs(name string, value interface{}) Validator

ClaimValueIs creates a Validator that checks if the value of claim `name` matches `value`. The comparison is done using a simple `==` comparison, and therefore complex comparisons may fail using this code. If you need to do more, use a custom Validator.

func IsExpirationValid

func IsExpirationValid() Validator

IsExpirationValid is one of the default validators that will be executed. It does not need to be specified by users, but it exists as an exported field so that you can check what it does.

The supplied context.Context object must have the "clock" and "skew" populated with appropriate values using SetValidationCtxClock() and SetValidationCtxSkew()

func IsIssuedAtValid

func IsIssuedAtValid() Validator

IsIssuedAtValid is one of the default validators that will be executed. It does not need to be specified by users, but it exists as an exported field so that you can check what it does.

The supplied context.Context object must have the "clock" and "skew" populated with appropriate values using SetValidationCtxClock() and SetValidationCtxSkew()

func IsNbfValid

func IsNbfValid() Validator

IsNbfValid is one of the default validators that will be executed. It does not need to be specified by users, but it exists as an exported field so that you can check what it does.

The supplied context.Context object must have the "clock" and "skew" populated with appropriate values using SetValidationCtxClock() and SetValidationCtxSkew()

func IsRequired

func IsRequired(name string) Validator

IsRequired creates a Validator that checks if the required claim `name` exists in the token

func MaxDeltaIs

func MaxDeltaIs(c1, c2 string, dur time.Duration) Validator

MaxDeltaIs implements the logic behind `WithMaxDelta()` option

func MinDeltaIs

func MinDeltaIs(c1, c2 string, dur time.Duration) Validator

MinDeltaIs implements the logic behind `WithMinDelta()` option

type ValidatorFunc

ValidatorFunc is a type of Validator that does not have any state, that is implemented as a function

type ValidatorFunc func(context.Context, Token) error

func (ValidatorFunc) Validate

func (vf ValidatorFunc) Validate(ctx context.Context, tok Token) error

type VerifyParameters

type VerifyParameters interface {
    Algorithm() jwa.SignatureAlgorithm
    Key() interface{}
}

type Visitor

type Visitor = iter.MapVisitor

type VisitorFunc

type VisitorFunc = iter.MapVisitorFunc

Subdirectories

Name Synopsis
..
openid Package openid provides a specialized token that provides utilities to work with OpenID JWT tokens.