Documentation

Overview

    Package jwt provides an implementation of the JSON Web Token standard.

    Index

    Examples

    Constants

    View Source
    const (
    	// DefaultLeeway defines the default leeway for matching NotBefore/Expiry claims.
    	DefaultLeeway = 1.0 * time.Minute
    )

    Variables

    View Source
    var ErrExpired = errors.New("square/go-jose/jwt: validation failed, token is expired (exp)")

      ErrExpired indicates that token is used after expiry time indicated in exp claim.

      View Source
      var ErrInvalidAudience = errors.New("square/go-jose/jwt: validation failed, invalid audience claim (aud)")

        ErrInvalidAudience indicated invalid aud claim.

        View Source
        var ErrInvalidClaims = errors.New("square/go-jose/jwt: expected claims to be value convertible into JSON object")

          ErrInvalidClaims indicates that given claims have invalid type.

          View Source
          var ErrInvalidContentType = errors.New("square/go-jose/jwt: expected content type to be JWT (cty header)")

            ErrInvalidContentType indicates that token requires JWT cty header.

            View Source
            var ErrInvalidID = errors.New("square/go-jose/jwt: validation failed, invalid ID claim (jti)")

              ErrInvalidID indicates invalid jti claim.

              View Source
              var ErrInvalidIssuer = errors.New("square/go-jose/jwt: validation failed, invalid issuer claim (iss)")

                ErrInvalidIssuer indicates invalid iss claim.

                View Source
                var ErrInvalidSubject = errors.New("square/go-jose/jwt: validation failed, invalid subject claim (sub)")

                  ErrInvalidSubject indicates invalid sub claim.

                  View Source
                  var ErrIssuedInTheFuture = errors.New("square/go-jose/jwt: validation field, token issued in the future (iat)")

                    ErrIssuedInTheFuture indicates that the iat field is in the future.

                    View Source
                    var ErrNotValidYet = errors.New("square/go-jose/jwt: validation failed, token not valid yet (nbf)")

                      ErrNotValidYet indicates that token is used before time indicated in nbf claim.

                      View Source
                      var ErrUnmarshalAudience = errors.New("square/go-jose/jwt: expected string or array value to unmarshal to Audience")

                        ErrUnmarshalAudience indicates that aud claim could not be unmarshalled.

                        View Source
                        var ErrUnmarshalNumericDate = errors.New("square/go-jose/jwt: expected number value to unmarshal NumericDate")

                          ErrUnmarshalNumericDate indicates that JWT NumericDate could not be unmarshalled.

                          Functions

                          This section is empty.

                          Types

                          type Audience

                          type Audience []string

                            Audience represents the recipients that the token is intended for.

                            func (Audience) Contains

                            func (s Audience) Contains(v string) bool

                            func (*Audience) UnmarshalJSON

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

                              UnmarshalJSON reads an audience from its JSON representation.

                              type Builder

                              type Builder interface {
                              	// Claims encodes claims into JWE/JWS form. Multiple calls will merge claims
                              	// into single JSON object. If you are passing private claims, make sure to set
                              	// struct field tags to specify the name for the JSON key to be used when
                              	// serializing.
                              	Claims(i interface{}) Builder
                              	// Token builds a JSONWebToken from provided data.
                              	Token() (*JSONWebToken, error)
                              	// FullSerialize serializes a token using the full serialization format.
                              	FullSerialize() (string, error)
                              	// CompactSerialize serializes a token using the compact serialization format.
                              	CompactSerialize() (string, error)
                              }

                                Builder is a utility for making JSON Web Tokens. Calls can be chained, and errors are accumulated until the final call to CompactSerialize/FullSerialize.

                                func Encrypted

                                func Encrypted(enc jose.Encrypter) Builder

                                  Encrypted creates builder for encrypted tokens.

                                  Example
                                  Output:
                                  
                                  

                                  func Signed

                                  func Signed(sig jose.Signer) Builder

                                    Signed creates builder for signed tokens.

                                    Example
                                    Output:
                                    
                                    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibGVlbGEiLCJmcnkiXSwiaXNzIjoiaXNzdWVyIiwibmJmIjoxNDUxNjA2NDAwLCJzdWIiOiJzdWJqZWN0In0.4PgCj0VO-uG_cb1mNA38NjJyp0N-NdGIDLoYelEkciw
                                    
                                    Example (MultipleClaims)
                                    Output:
                                    
                                    eyJhbGciOiJIUzI1NiJ9.eyJTY29wZXMiOlsiZm9vIiwiYmFyIl0sImlzcyI6Imlzc3VlciIsInN1YiI6InN1YmplY3QifQ.esKOIsmwkudr_gnfnB4SngxIr-7pspd5XzG3PImfQ6Y
                                    
                                    Example (PrivateClaims)
                                    Output:
                                    
                                    

                                    type Claims

                                    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"`
                                    }

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

                                      func (Claims) Validate

                                      func (c Claims) Validate(e Expected) error

                                        Validate checks claims in a token against expected values. A default leeway value of one minute is used to compare time values.

                                        The default leeway will cause the token to be deemed valid until one minute after the expiration time. If you're a server application that wants to give an extra minute to client tokens, use this function. If you're a client application wondering if the server will accept your token, use ValidateWithLeeway with a leeway <=0, otherwise this function might make you think a token is valid when it is not.

                                        Example
                                        Output:
                                        
                                        valid!
                                        
                                        Example (WithParse)
                                        Output:
                                        
                                        valid!
                                        

                                        func (Claims) ValidateWithLeeway

                                        func (c Claims) ValidateWithLeeway(e Expected, leeway time.Duration) error

                                          ValidateWithLeeway checks claims in a token against expected values. A custom leeway may be specified for comparing time values. You may pass a zero value to check time values with no leeway, but you should not that numeric date values are rounded to the nearest second and sub-second precision is not supported.

                                          The leeway gives some extra time to the token from the server's point of view. That is, if the token is expired, ValidateWithLeeway will still accept the token for 'leeway' amount of time. This fails if you're using this function to check if a server will accept your token, because it will think the token is valid even after it expires. So if you're a client validating if the token is valid to be submitted to a server, use leeway <=0, if you're a server validation a token, use leeway >=0.

                                          type Expected

                                          type Expected struct {
                                          	// Issuer matches the "iss" claim exactly.
                                          	Issuer string
                                          	// Subject matches the "sub" claim exactly.
                                          	Subject string
                                          	// Audience matches the values in "aud" claim, regardless of their order.
                                          	Audience Audience
                                          	// ID matches the "jti" claim exactly.
                                          	ID string
                                          	// Time matches the "exp", "nbf" and "iat" claims with leeway.
                                          	Time time.Time
                                          }

                                            Expected defines values used for protected claims validation. If field has zero value then validation is skipped.

                                            func (Expected) WithTime

                                            func (e Expected) WithTime(t time.Time) Expected

                                              WithTime copies expectations with new time.

                                              type JSONWebToken

                                              type JSONWebToken struct {
                                              	Headers []jose.Header
                                              	// contains filtered or unexported fields
                                              }

                                                JSONWebToken represents a JSON Web Token (as specified in RFC7519).

                                                func ParseEncrypted

                                                func ParseEncrypted(s string) (*JSONWebToken, error)

                                                  ParseEncrypted parses token from JWE form.

                                                  Example
                                                  Output:
                                                  
                                                  iss: issuer, sub: subject
                                                  

                                                  func ParseSigned

                                                  func ParseSigned(s string) (*JSONWebToken, error)

                                                    ParseSigned parses token from JWS form.

                                                    Example
                                                    Output:
                                                    
                                                    iss: issuer, sub: subject
                                                    

                                                    func (*JSONWebToken) Claims

                                                    func (t *JSONWebToken) Claims(key interface{}, dest ...interface{}) error

                                                      Claims deserializes a JSONWebToken into dest using the provided key.

                                                      Example (Map)
                                                      Output:
                                                      
                                                      iss: issuer, sub: subject
                                                      
                                                      Example (Multiple)
                                                      Output:
                                                      
                                                      iss: issuer, sub: subject, scopes: foo,bar
                                                      

                                                      func (*JSONWebToken) UnsafeClaimsWithoutVerification

                                                      func (t *JSONWebToken) UnsafeClaimsWithoutVerification(dest ...interface{}) error

                                                        UnsafeClaimsWithoutVerification deserializes the claims of a JSONWebToken into the dests. For signed JWTs, the claims are not verified. This function won't work for encrypted JWTs.

                                                        type NestedBuilder

                                                        type NestedBuilder interface {
                                                        	// Claims encodes claims into JWE/JWS form. Multiple calls will merge claims
                                                        	// into single JSON object. If you are passing private claims, make sure to set
                                                        	// struct field tags to specify the name for the JSON key to be used when
                                                        	// serializing.
                                                        	Claims(i interface{}) NestedBuilder
                                                        	// Token builds a NestedJSONWebToken from provided data.
                                                        	Token() (*NestedJSONWebToken, error)
                                                        	// FullSerialize serializes a token using the full serialization format.
                                                        	FullSerialize() (string, error)
                                                        	// CompactSerialize serializes a token using the compact serialization format.
                                                        	CompactSerialize() (string, error)
                                                        }

                                                          NestedBuilder is a utility for making Signed-Then-Encrypted JSON Web Tokens. Calls can be chained, and errors are accumulated until final call to CompactSerialize/FullSerialize.

                                                          func SignedAndEncrypted

                                                          func SignedAndEncrypted(sig jose.Signer, enc jose.Encrypter) NestedBuilder

                                                            SignedAndEncrypted creates builder for signed-then-encrypted tokens. ErrInvalidContentType will be returned if encrypter doesn't have JWT content type.

                                                            Example
                                                            Output:
                                                            
                                                            

                                                            type NestedJSONWebToken

                                                            type NestedJSONWebToken struct {
                                                            	Headers []jose.Header
                                                            	// contains filtered or unexported fields
                                                            }

                                                            func ParseSignedAndEncrypted

                                                            func ParseSignedAndEncrypted(s string) (*NestedJSONWebToken, error)

                                                              ParseSignedAndEncrypted parses signed-then-encrypted token from JWE form.

                                                              Example
                                                              Output:
                                                              
                                                              iss: issuer, sub: subject
                                                              

                                                              func (*NestedJSONWebToken) Decrypt

                                                              func (t *NestedJSONWebToken) Decrypt(decryptionKey interface{}) (*JSONWebToken, error)

                                                              type NumericDate

                                                              type NumericDate int64

                                                                NumericDate represents date and time as the number of seconds since the epoch, including leap seconds. Non-integer values can be represented in the serialized format, but we round to the nearest second.

                                                                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.