JSON Web Token Cheat Sheet for Java

Many applications use JSON Web Tokens (JWT) to allow the client to indicate its identity for further exchange after authentication.

From JWT.IO:

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.

JSON Web Token is used to carry information related to the identity and characteristics (claims) of a client. This information is signed by the server in order for it to detect whether it was tampered with after sending it to the client. This will prevent an attacker from changing the identity or any characteristics (for example, changing the role from the simple user to admin or changing the client login).

This token is created during authentication (is provided in case of successful authentication) and is verified by the server before any processing. It is used by an application to allow a client to present a token representing the user’s “identity card” to the server and allow the server to verify the validity and integrity of the token in a secure way, all of this in a stateless and portable approach (portable in the way that client and server technologies can be different including also the transport channel even if HTTP is the most often used).

Token Structure

Token structure example token from JWT.IO:

[Base64(HEADER)].[Base64(PAYLOAD)].[Base64(SIGNATURE)]

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

Chunk 1: Header

{ “alg”: “HS256”, “typ”: “JWT” }

Chunk 2: Payload

{ “sub”: “1234567890”, “name”: “John Doe”, “admin”: true }

Chunk 3: Signature

HMACSHA256( base64UrlEncode(header) + “.” + base64UrlEncode(payload), KEY )

Objective

This cheat sheet provides tips to prevent common security issues when using JSON Web Tokens (JWT) with Java.

The tips presented in this article are part of a Java project that was created to show the correct way to handle the creation and validation of JSON Web Tokens.

You can find the Java project here, it uses the official JWT library.

In the rest of the article, the term token refers to the JSON Web Tokens (JWT).

Consideration about Using JWT

Even if a JWT token is “easy” to use and allow to expose services (mostly REST-style) in a stateless way, it’s not the solution that fits all applications because it comes with some caveats, like for example the question of the storage of the token (tackled in this cheatsheet) and others…

If your application does not need to be fully stateless, you can consider using a traditional session system provided by all web frameworks and follow the advice from the dedicated session management cheat sheet. However, for stateless applications, when well implemented, it’s a good candidate.

Issues

None Hashing Algorithm

Symptom

This attack, described here occurs when an attacker alters the token and changes the hashing algorithm to indicate, though, the none keyword, that the integrity of the token has already been verified. As explained in the link above some libraries treated tokens signed with the none algorithm as a valid token with a verified signature, so an attacker can alter the token claims and the token will be trusted by the application.

We will be with you in the continuation of a sample project.