JSON Web Token

JSON Web Token (JWT) is a JSON-based open standard (RFC 7519) for passing claims between parties in web application environment. The tokens are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context. JWT claims can be typically used to pass identity of authenticated users between an identity provider and a service provider, or any other type of claims as required by business processes.^[1][2] The tokens can also be authenticated and encrypted.^[3][4]

JWT relies on other JSON-based standards: JWS (JSON Web Signature) RFC 7515 and JWE (JSON Web Encryption) RFC 7516.^[5][6][7]

Structure

Token is a set of claims (JSON fields). The following example token, issued by Identity Provider, states that John Doe is an administrator:

{"iss":"Identity Provider","name":"John Doe","admin":true}

A claim set can be sent with an authentication header, declaring a cryptographic message authentication code (HMAC with SHA-256 in the following example):

{"typ":"JWT","alg":"HS256"}

After canonicalization both structures are encoded as Base64 and the declared message authentication code is calculated over the encoded string. The output is three Base64 strings separated by dots that can be easily passed in HTML and HTTP environments, while being more compact compared to XML-based standards such as SAML.

Typical cryptographic algorithms used are HMAC with SHA-256 (HS256) and RSA signature with SHA-256 (RS256). JWA (JSON Web Algorithms) RFC 7518 introduces many more for both authentication and encryption.^[8]

Standard fields

The Internet drafts define the following standard fields ("claims") that can be used inside a JWT claim set:

• Issuer (iss) - identifies principal that issued the JWT;
• Subject (sub) - identifies the subject of the JWT;
• Audience (aud) - The "aud" (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the aud claim when this claim is present, then the JWT MUST be rejected.
• Expiration time (exp) - The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
• Not before (nbf) - Similarly, the not-before time claim identifies the time on which the JWT will start to be accepted for processing.
• Issued at (iat) - The "iat" (issued at) claim identifies the time at which the JWT was issued.
• JWT ID (jti) - case sensitive unique identifier of the token even among different issuers.

The following fields can be used in authentication headers:

• Token type (typ)
• Content type (cty) - This claim should always be JWT.
• Message authentication code algorithm (alg) - The issuer can freely set an algorithm to verify the signature on the token. However, some asymmetrical algorithms pose security concerns.^[4]
• All other headers introduced by JWS and JWE^[6][7]

Implementations

JWT implementations exist for Clojure, .NET (Public domain software),^[9] Go, Haskell, Python, Node.js, Java, JavaScript, Lua, PHP, Ruby,^[10] Rust,^[11] Scala,^[3] and Elixir

References

1. Sevilleja, Chris. "The Anatomy of a JSON Web Token". Retrieved 2015-05-08.
2. "Atlassian Connect Documentation". developer.atlassian.com. Retrieved 2015-05-08.
3. "JSON Web Tokens - jwt.io". jwt.io. Retrieved 2015-05-08.
4. Tim McLean (March 31, 2015). "Critical vulnerabilities in JSON Web Token libraries". Auth0. Retrieved 2016-03-29.
5. "draft-ietf-oauth-json-web-token-32 - JSON Web Token (JWT)". tools.ietf.org. Retrieved 2015-05-08.
6. "draft-ietf-jose-json-web-signature-41 - JSON Web Signature (JWS)". tools.ietf.org. Retrieved 2015-05-08.
7. "draft-ietf-jose-json-web-encryption-40 - JSON Web Encryption (JWE)". tools.ietf.org. Retrieved 2015-05-08.
8. "draft-ietf-jose-json-web-algorithms-40 - JSON Web Algorithms (JWA)". tools.ietf.org. Retrieved 2015-05-08.
9. jwt-dotnet on github.com
10. ruby-jwt on github.com
11. frank_jwt on github.com