README

THIS REPOSITORY IS NO LONGER MAINTANED

The new repository can be found at: https://github.com/golang-jwt/jwt

For more information, see issue 462.

 jwt-go




A go (or 'golang' for search engine friendliness) implementation of JSON Web Tokens

NEW VERSION COMING: There have been a lot of improvements suggested since the version 3.0.0 released in 2016. I'm working now on cutting two different releases: 3.2.0 will contain any non-breaking changes or enhancements. 4.0.0 will follow shortly which will include breaking changes. See the 4.0.0 milestone to get an idea of what's coming. If you have other ideas, or would like to participate in 4.0.0, now's the time. If you depend on this library and don't want to be interrupted, I recommend you use your dependency mangement tool to pin to version 3. 

SECURITY NOTICE: Some older versions of Go have a security issue in the cryotp/elliptic. Recommendation is to upgrade to at least 1.8.3. See issue 216 for more detail.

SECURITY NOTICE: It's important that you validate the alg presented is what you expect. This library attempts to make it easy to do the right thing by requiring key types match the expected alg, but you should take the extra step to verify it in your usage.  See the examples provided.

 What the heck is a JWT?

JWT.io has a great introduction to JSON Web Tokens.

In short, it's a signed JSON object that does something useful (for example, authentication).  It's commonly used for Bearer tokens in Oauth 2.  A token is made of three parts, separated by .'s.  The first two parts are JSON objects, that have been base64url encoded.  The last part is the signature, encoded the same way.

The first part is called the header.  It contains the necessary information for verifying the last part, the signature.  For example, which encryption method was used for signing and what key was used.

The part in the middle is the interesting bit.  It's called the Claims and contains the actual stuff you care about.  Refer to the RFC for information about reserved keys and the proper way to add your own.

 What's in the box?

This library supports the parsing and verification as well as the generation and signing of JWTs.  Current supported signing algorithms are HMAC SHA, RSA, RSA-PSS, and ECDSA, though hooks are present for adding your own.

 Examples

See the project documentation for examples of usage:

 Simple example of parsing and validating a token
 Simple example of building and signing a token
 Directory of Examples

 Extensions

This library publishes all the necessary components for adding your own signing methods.  Simply implement the SigningMethod interface and register a factory method using RegisterSigningMethod.  

Here's an example of an extension that integrates with multiple Google Cloud Platform signing tools (AppEngine, IAM API, Cloud KMS): https://github.com/someone1/gcp-jwt-go

 Compliance

This library was last reviewed to comply with RTF 7519 dated May 2015 with a few notable differenc