README.md

Modular JWT / JWS provider in Golang

This packages implements JSON Web Token as defined in RFC 7519 in Go.

It is build with a modular architecture to make it easy to adapt to most use cases.

For this reason all verification of signatures and contents is implemented independently and does explicitly have to be activated.

All tokens decoded by this package will automatically be validated using the activated signature and content verification providers. To check if the token is valid use token.Valid() which returns a boolean. If you want to know the exact error, use token.ValidationError().

The default algorithms for signature verification specified in RFC7518 and RFC8037 can be found in sub-packages in this repository.

EdDSA with Ed25519 and Ed448 (unstable), HMAC-SHA2, RSA PKCS#1 v1.5, RSA-PSS and ECDSA can all be found in the respective folders.

You may add a signature provider by calling AddSignatureProvider(name string, provider SignatureProvider) error with name being the value of the alg header this algorithm uses and alg being a properly initialized instance of the respective algorithm. To enable signing and select the algorithm to use, call SetSigningAlgorithm(name string) error with the name of the algorithm to use.

The main package includes some implementations of content validation providers in contentValidation.go. To add a content validator, call AddValidationProvider(name string, provider ContentValidationProvider) error with a name of your choosing and the initialized provider. It will automatically be used to validate all tokens that are decoded after adding it.

In case the providers included in this package do not fit your needs, you can always implement your own. For details see API.md.

Data structures

JWTs are stored as a struct with the following layout

type JWT struct {
	Header struct {
		Typ string // Type of the token, has to be JWT.
		Alg string // Algorithm used to sign the token (this package signs using EdDSA).
		Kid string // Key ID of the key used to sign the token.
		Jku string // URL presenting public key necessary for validation.
	}
	Content []byte // Encoded JSON as specified in RFC 7519 (Should be based on map or struct in Go)
}

Due to the header being a struct some values may be ignored when decoding.

Usage

Generating a new JWT

Creating a JWT is quite easy. You just have to supply your content encoded as JSON and this package will generate a JWT for you.

jwt.New(content []byte) (JWT, error)

Encoding a JWT

To actually use a JWT you will have to encode it. This is done by simply calling Encode on the JWT you created.

Please note that you will need to add a signature provider first and also set the singing provider to use.

token.Encode() ([]byte, error)

Decoding a JWT

To validate a JWT you will first have to decode it. Just supply it to the Decode function.

jwt.Decode(encodedtoken []byte) (JWT, error)

Validating the hash

When decoding a JWT, it is automatically validated but you will have to retieve the result using:

token.Valid() bool
token.ValidationError() error

Keep in mind that this only checks if the token was valid when it was decoded and also only using the validation providers registered at that time. You will also need to add the signature validation provider and add the necessary keys before decoding the token or it will be treated as invalid.