JSON Web Token

JSON Web Token (JWT) is a JSON-based open standard (RFC 7519) for creating access tokens that assert some number of claims. For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that he/she is logged in as admin. The tokens are signed by the server's key, so the client is able to verify that the token is legitimate. 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

JWTs generally have three parts: a header, a payload, and a signature. The header identifies which algorithm is used to generate the signature, and looks something like this:

header = '{"alg":"HS256","typ":"JWT"}'

HS256 indicates that this token is signed using HMAC-SHA256.

The payload contains the claims that we wish to make:

payload = '{"loggedInAs":"admin","iat":1422779638}'

As suggested in the JWT spec, we include a timestamp called iat, short for "issued at".

The signature is calculated by base64url encoding the header and payload and concatenating them with a period as a separator:

key           = 'secretkey'
unsignedToken = encodeBase64(header) + '.' + encodeBase64(payload)
signature     = HMAC-SHA256(key, unsignedToken) 

To put it all together, we base64url encode the signature, and join together the three parts using periods:

token = encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature) # token is now: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI 

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]

How it works

In authentication, when the user successfully logs in using their credentials, a JSON Web Token will be returned and must be saved locally (typically in local storage, but cookies can be also used), instead of the traditional approach of creating a session in the server and returning a cookie.

Whenever the user wants to access a protected route or resource, the user agent should send the JWT, typically in the Authorization header using the Bearer schema. The content of the header should look like the following:

Authorization: Bearer <token> 

This is a stateless authentication mechanism as the user state is never saved in server memory. The server's protected routes will check for a valid JWT in the Authorization header, and if it's present, the user will be allowed to access protected resources. As JWTs are self-contained, all the necessary information is there, reducing the need to query the database multiple times.

See more details and online tools at JWT.io

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) - If present, it is recommended to set this to JWT.^[9]
• Content type (cty) - If nested signing or encryption is employed, it is recommended to set this to JWT, otherwise omit this field.^[9]
• Message authentication code algorithm (alg) - The issuer can freely set an algorithm to verify the signature on the token. However, some supported algorithms are insecure.^[4]
• All other headers introduced by JWS and JWE^[6][7]

Implementations

JWT implementations exist for Clojure, .NET (Public domain software),^[10] Go, Haskell, Python, Node.js, Java, JavaScript, Lua, Perl, PHP, Ruby,^[11] Rust,^[12] 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.
10. jwt-dotnet on github.com
11. ruby-jwt on github.com
12. frank_jwt on github.com

^[1]

1. John, Bradley,; Nat, Sakimura,; Michael, Jones,. "JSON Web Token (JWT)". tools.ietf.org. Retrieved 2016-11-14.