JSON Web Token
A JSON Web Token (JWT) is a JSON object that is defined in RFC 7519 as a safe way of transmitting information between two parties. Information in the JWT is digitally-signed, so that it can be verified and trusted.
- Less verbose – JWT is compact in size and can be passed in the URL, POST parameter, or HTTP header.
- Self-contained – JWT carries all of information needed for exchanging information and authentication.
JWT Use Cases
- Information Exchange – JWT can be used between two parties to exchange information. JWT is digitally-signed and can be used in a secure public/private key pair. Information is verified using the public key on the other end.
- Authentication – JWT can contain user information in the payload and can be used in the session to authenticate the user. Once authenticated, users can access protected resources in an application using the JWT included in the request. So, every request will be authenticated by verifying the JWT.
JWT contains three parts: Header, Payload, and Signature which are separated by a dot.
The JWT Header consists of 2 parts:
- The token type (typ): JWT
- Algorithm used to sign the token (alg)
Header Algorithm Types:
- Symmetric Algorithms – This algorithm type uses a single secret key to both sign and verify the JWT token. For example: HMAC algorithms.
- Asymmetric Algorithms – This algorithm type uses a private key to sign the token and a public key to verify the signature. For example: RSA and ECDSA algorithms.
|alg Value||Digital Signature or MAC Algorithm|
|HS256||HMAC using SHA-256 hash algorithm|
|HS384||HMAC using SHA-384 hash algorithm|
|HS512||HMAC using SHA-512 hash algorithm|
|RS256||RSASSA using SHA-256 hash algorithm|
|RS384||RSASSA using SHA-384 hash algorithm|
|RS512||RSASSA using SHA-512 hash algorithm|
|ES256||ECDSA using P-256 curve and SHA-256 hash algorithm|
|ES384||ECDSA using P-384 curve and SHA-384 hash algorithm|
|ES512||ECDSA using P-521 curve and SHA-512 hash algorithm|
The Base64Url-encoded Header, which is first part of our JWT, looks like the following:
The Payload, also known as the JWT claim, contains all of the information we want to transmit.
Different types of claims can be used to build the Payload:
- Registered Claim – These claims are optional but recommended as they contain some metadata about the token:
|iss||issuer||Identifies the principal that issued the JWT.|
|sub||subject||Identifies the principal that is the subject of the JWT.|
|aud||audience||Identifies the recipients that the JWT is intended for.|
|exp||Expiration time||Identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.|
|nbf||Not before||Identifies the time before which the JWT MUST NOT be accepted for processing.|
|iat||Issue at||Identifies the time at which the JWT was issued.|
|jti||JWT id||Unique identifier for the JWT, can be used to prevent the JWT from being replayed.|
- Public Claim – These claims are defined by you, such as user name, and other important information.
- Private Claim – A producer and consumer may agree to use claim names that are private. These are subject to collision, so use them with caution.
This example contains a combination of registered and public claims. “sub”,”jti”,”iat”, and “exp” are registered claims and “name” is a public claim.
The Base64Url-encoded Payload, which is the second part of our JWT, looks like the following:
The final part of our JWT is the Signature. To create the Signature, we need 3 components:
- Algorithm used to sign the Header and Payload
|var encodedString = base64UrlEncode(header) + “.” + base64UrlEncode(payload);
The secret is the Signature held by the server in order to verify tokens and sign new ones.
The above Base64Url-encoded Header and Payload are combined with a dot, and then digitally-signed using the secret. This generates the Signature as the third part of the our JWT:
Putting It All Together
This is our final JWT, containing the Header, Payload, and Signature joined together with dots. It can be passed as a URL parameter, a POST parameter, or in the HTTP header to authenticate or exchange information.
You can play around with JWT using our JWT SSO Tool.
Note: JWT does not hide information; it just encodes information using the digitally-signed signature and verifies that the information has not been altered over the network. So, do not add any sensitive information in the JWT claim.
JWT comprises three encoded parts: Header, Payload, and Signature. It can be passed as a URL or POST parameter, or in an HTTP header. Due to JWT’s lightweight, self-containing, and versatile strucutre, it remains a popular tool for information exchange and authentication.