Webacus (logo)
Watch Video

JSON Web Token (JWT)

JSON Web Token is an Internet standard for creating data with optional signature and/or optional encryption whose payload holds JSON that asserts some number of claims. The tokens are signed either using a private secret or a public/private key. For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that it is logged in as admin. The tokens can be signed by one party's private key (usually the server's) so that party can subsequently verify the token is legitimate. If the other party, by some suitable and trustworthy means, is in possession of the corresponding public key, they too are able to verify the token's legitimacy.

The tokens are designed to be compact, URL-safe, and usable especially in a web-browser single-sign-on (SSO) context. JWT claims can typically be used to pass identity of authenticated users between an identity provider and a service provider, or any other type of claims as required by business processes.[1]

Encode

A JSON Web Token (JWT) consists of three distinct parts: the header, the payload, and the signature. The header typically contains metadata about the token, such as the type of token and the cryptographic algorithm used for signing. The payload holds the claims, which are statements about an entity (usually the user) and additional data. Finally, the signature is generated by encoding the header and payload, then signing them using the specified algorithm and a secret or private key. This structure ensures both the integrity and authenticity of the token, allowing secure transmission of information between parties.

Header

Sample header:

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

Identifies which algorithm is used to generate the signature. HS256 indicates that this token is signed using HMAC-SHA256.

Supported algorithms:
- HS256: HMAC using SHA-256 hash algorithm (requires a secret)
- HS384: HMAC using SHA-384 hash algorithm (requires a secret)
- HS512: HMAC using SHA-512 hash algorithm (requires a secret)
- RS256: RSA-SSA-PKCS1-v1_5 using SHA-256 hash algorithm (requires a private key)
- RS384: RSA-SSA-PKCS1-v1_5 using SHA-384 hash algorithm (requires a private key)
- RS512: RSA-SSA-PKCS1-v1_5 using SHA-512 hash algorithm (requires a private key)
- ES256: ECDSA using P-256 curve and SHA-256 hash algorithm (requires a private key)
- ES384: ECDSA using P-384 curve and SHA-384 hash algorithm (requires a private key)
- ES512: ECDSA using P-512 curve and SHA-512 hash algorithm (requires a private key)
- PS256: RSA-SSA-PSS using SHA-256 hash algorithm (requires a private key)
- PS384: RSA-SSA-PSS using SHA-384 hash algorithm (requires a private key)
- PS512: RSA-SSA-PSS using SHA-512 hash algorithm (requires a private key)

Payload

Sample payload:

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

Contains a set of claims. The JWT specification defines seven Registered Claim Names which are the standard fields commonly included in tokens. Custom claims are usually also included, depending on the purpose of the token. This example has the standard Issued At Time claim (iat) and a custom claim (loggedInAs).

JWT specification defines seven Registered Claim Names:

  1. iss (Issuer): Identifies the principal that issued the JWT.
  2. sub (Subject): Identifies the principal that is the subject of the JWT.
  3. aud (Audience): Identifies the recipients that the JWT is intended for.
  4. exp (Expiration Time): Identifies the expiration time on or after which the JWT must not be accepted for processing.
  5. nbf (Not Before): Identifies the time before which the JWT must not be accepted for processing.
  6. iat (Issued At): Identifies the time at which the JWT was issued.
  7. jti (JWT ID): Provides a unique identifier for the JWT.

Signature

Signature calculation:

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

Securely validates the token. The signature is calculated by encoding the header and payload using Base64url Encoding and concatenating the two together with a period separator. That string is then run through the cryptographic algorithm specified in the header, in this case HMAC-SHA256. The Base64url Encoding is similar to base64, but uses different non-alphanumeric characters and omits padding.

Securing JWT Tokens

JWT tokens are secured by signing them. The signing method depends on the algorithm:

  • Secret key algorithms (e.g., HS256, HS384, HS512): Use a shared secret key for signing. You can also use a binary key, but in that case, the secret must be provided as a base64-encoded string.
  • Public/private key algorithms (e.g., RS256, ES256, PS256): Use a private key to sign the token and a public key to verify it. The private key must be provided in PKCS#8 PEM 2 format.

Choosing the right algorithm and securely managing your keys is essential to maintain the integrity and authenticity of your JWT tokens.

When to use a secret key (HMAC algorithms):

  • Use a shared secret key (e.g., with HS256, HS384, HS512) when both the issuer and the verifier of the token are under your control, such as in a single-application or microservices environment where all services can securely share the same secret.
  • Secret key algorithms are simpler to set up but require careful management of the secret, as anyone with access to it can both sign and verify tokens.

When to use a public/private key pair (RSA, ECDSA, or PSS algorithms):

  • Use a public/private key pair (e.g., with RS256, ES256, PS256) when the token needs to be verified by third parties or external systems, or when you want to separate the ability to sign tokens (private key) from the ability to verify them (public key).
  • Public/private key algorithms are recommended for distributed systems, federated identity, or when exposing public endpoints, as only the private key holder can sign tokens, while anyone with the public key can verify them.

Choose the approach that best fits your application's trust boundaries and security requirements.

Sample

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

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI

Decode

The decode tool (JWT decoder) takes a JWT and splits it into its three components: header, payload, and signature. If a secret or public key is provided, the tool also verifies the token's signature to ensure its authenticity and integrity. This process allows you to inspect the claims and metadata contained within the token, and to confirm that the token has not been tampered with. Decoding a JWT is useful for debugging, auditing, or understanding the information being transmitted between parties in a secure and standardized way.

Source:
[1] wikipedia.org/wiki/JSON_Web_Token
[2] wikipedia.org/wiki/PKCS_8