JSON Web Token

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

{
  "loggedInAs": "admin",
  "iat": 1422779638
}

HMAC-SHA256(
  secret,
  base64urlEncoding(header) + '.' +
  base64urlEncoding(payload)
)

The three parts are encoded separately using Base64url Encoding, and concatenated using periods to produce the JWT:

const token = base64urlEncoding(header) + '.' + base64urlEncoding(payload) + '.' + base64urlEncoding(signature)

The above data and the secret of "secretkey" creates the token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI

This resulting token can be easily passed into HTML and HTTP.[3]

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 or session storage, but cookies can also be used), instead of the traditional approach of creating a session in the server and returning a cookie. For unattended processes the client may also authenticate directly by generating and signing its own JWT with a pre-shared secret and pass it to a oAuth compliant service like so:

POST /oauth2/token?
Content-type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhb...

If the client passes a valid JWT assertion the server will generate an access_token valid for making calls to the application and pass it back to the client:

{
  "access_token": "eyJhb...",
  "token_type": "Bearer",
  "expires_in": 3600
}

When the client 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 might look like the following:

Authorization: Bearer eyJhbGci...<snip>...yu5CSpyHI

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 is 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.

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

The following fields are commonly used in the header of a JWT:

JWT implementations exist for many languages and frameworks, including but not limited to:

JSON web tokens may contain session state. But if project requirements allow session invalidation before JWT expiration, services can no longer trust token assertions by the token alone. To validate the session stored in the token is not revoked, token assertions must be checked against a data store. This renders the tokens no longer stateless, undermining the primary advantage of JWTs.[36]

Security consultant Tim McLean reported vulnerabilities in some JWT libraries that used the alg field to incorrectly validate tokens. While these vulnerabilities were patched, McLean suggested deprecating the alg field altogether to prevent similar implementation confusion.[10]

With proper design, developers can address algorithm vulnerabilities by taking precautions:[37][38]

1. Never let the JWT header alone drive verification
2. Know the algorithms
3. Use an appropriate key size

Software security architect Kurt Rodarmer points out additional JWT design vulnerabilities around cryptographic signing keys and a significant vulnerability that exposes a library’s JSON parser to open attack.[39] This is a direct result of choosing JSON to express the token header, and is more difficult to mitigate.

• RFC 7519
• jwt.io – specialized website about JWT with tools and documentation, maintained by Auth0
• Spring Boot JWT Auth – Integrating JWT authentication with Spring framework
• JWT Security – JWT Security e-Book PDF (Polish language)
• Why do we need JWT in the modern web - a detailed article on the topic with some historical considerations