JSON Web Tokens (JWTs) provide a mechanism to securely transmit information between parties in the format of encoded JSON objects. JWTs follow a compacted format and are defined by the open standard (RFC 7519). They can be signed with a secret using the HMAC algorithm, or a public/private key pair using RSA or ECDSA. With a Signed JWT, their information can be verified and trusted since it’s cryptographically signed. This enables systems to verify a JWT is valid and signed by a specific party without needing the private key.
JWTs are commonly used as a mechanism to implement authentication for APIs. This is partly due to the ability to represent additional user data beyond the basic authentication process. JWTs can also be used for authorization by including permissions in the payload. They are lightweight, easy to use, and supported by most programming languages and frameworks. However, it is important to keep in mind that JWTs are not a silver bullet and should be used in conjunction with other security measures.
JWTs consist of three parts: a header, a payload, and a signature. The header contains information about the type of token and the algorithm used to sign it. The payload contains the information that is being transmitted, such as user data or permissions. The signature is used to verify that the message has not been tampered with.
The header component (also called a JOSE header) is a JSON object used to identify the type of algorithm used to sign the payload.
{
"alg": "HS256",
"typ": "JWT"
}
The payload contains the information being shared. In the use case of authentication, the payload can contain identifiable information about a user and their permissions. There are also Registered fields (called Registered Claims) used to exchange common bits of information about the token. Claims are further covered in this post.
{
"sub": "EdgeOrb",
"client": "b50f22ea-4a3f-11ee-be56-0242ac120002",
"iat": 1516239022
}
The signature component is commonly referred to as a JSON Web Signature (JWS). They provide the mechanism to prove that the token is signed by a specific party and that the payload has not been tampered with. Unlike the header and payload component, the signature is not defined in a JSON format. If you wanted to use the HMAC SHA256 algorithm (Secret text), it would be created with he following algorithm.
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)
A well-formed token consists of these three components in the following format.
[Header].[Payload].[Signature]
Bringing it all together, this is how a JSON Web Token is represented.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJFZGdlIE9yYiIsImNsaWVudCI6ImI1MGYyMmVhLTRhM2YtMTFlZS1iZTU2LTAyNDJhYzEyMDAwMiJ9.IYe-80mXP58N6ChsPshXYQZ2XMKs-jocl8NIViQIlpE
Claims are the fields within the payload. There are two types of JWT claims, Registered and Custom claims. Registered claims are fields that have been registered by the Internet Assigned Numbers Authority (IANA). This IANA registry tracks commonly used claims that have been defined in other standards such as OIDC, RFC7519 and RFC9246. For example, the RFC7519 specification defines the following Registered Claims and their recommended use cases to ensure interoperability.
Custom claims are fields that are not registered by the IANA. They are used to share information between parties that are specific to the use case. For example, a JWT used for authentication may contain the unique identity of a User. The following is an example of a JWT with custom claims.
{
"sub": "EdgeOrb",
"client": "b50f22ea-4a3f-11ee-be56-0242ac120002",
"iat": 1516239022
}
As JSON Web Tokens allow isolated systems to both sign and validate the legitimacy of data, they have become increasingly popular in recent years for implementing authentication and authorization in APIs. With this rise in popularity, there are many libraries and frameworks that have been created to make it easier to implement JWTs in your application. Here is just a quick list of libaries across different languages and frameworks that support JWTs.