JSON Web Tokens (JWTs)

JSON Web Tokens (JWTs) represent encoded data. They are compact, self-contained, and secure. There are two primary types of JSON Web Tokens:

• Encrypted JWT: ensures the confidentiality of the token, and only the intended recipient can read its contents.
• Signed JWT: ensures the integrity of the token, and the recipient can be sure that it isn’t modified.

Feature	Signed JWT	Encrypted JWT
Integrity	Yes	Yes
Confidentiality	No	Yes
Purpose	Ensure that the token has not been tampered with and to verify the identity of the sender.	Ensure that only the intended recipient can read the token

JWTs contain claims. In the case of encrypted JWTs, claims are hidden. In the case of signed JWTs, you can verify the integrity of the claims. Liferay makes use of signed JWTs to verify the identity of the sender. There are two ways for a client to sign a JWT:

• Symmetric Key (Shared Secret): Symmetric key signing involves sharing the client secret between the required parties. After signing the JWT with the shared secret, it’s verified by the authorization server. If valid, the authorization server issues an access token.
• Asymmetric Key (Public/Private Key Pair): Asymmetric key signing involves signing the JWT with a private key. The server holds the public key to verify the signature. If valid, the authorization server issues an access token.

JWT Structure

A JWT contains three parts: a header, a payload, and a signature, separated by dots (.).

Header

Also known as the JOSE (JSON Object Signing and Encryption) header, it contains key-value pairs declaring the hashing algorithm used, the type of the JWT, and sometimes a key id (kid).

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

Payload

The payload contains attributes about an entity (typically, the user). These attributes are commonly referred to as claims.

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

Signature

The signature identifies the sender. A minor change made to the JWT results in an invalid signature. To obtain the signature, the header and payload are Base64 encoded and signed using a hashing algorithm with a shared secret or private key. This is then Base64 encoded again.

Part	Original	Base64 Encoded
Header	{"alg":"HS256","typ":"JWT"}	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Payload	{"sub":"1234567890","name":"John Doe","iat":1516239022}	eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
Signature	Base64 (encoded header & payload signed using shared secret or private key)	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

In case of a shared secret, the algorithm must be symmetric (HS256) and in case of a private key, the algorithm must be asymmetric (RS256).

Forming the JWT

The header and payload are Base64 encoded and separated by a dot (.). The signature value is Base64 encoded and appended after the payload separated by a (.).

Combining the three gives a sample JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Why use JWTs

• Since JWTs contain all the required information about an entity, the server needn’t store session data. This makes the system stateless and scalable.
• Regular access tokens often require the server to store them and check for expiry. This increases the number of API calls and database look-ups reducing their efficiency compared to JWTs.
• JWTs follow industry standards and are easier to adopt between different systems. Regular access tokens may use proprietary formats.