Docs

JSON Web Token Structure

JSON Web Token Structure

All Auth0-issued JSON Web Tokens (JWTs) are JSON Web Signatures (JWS), meaning they are signed rather than encrypted. As such, this document describes the JWS structure of a JWT.

A well-formed JSON Web Token (JWT) consists of three concatenated Base64url-encoded strings, separated by dots (.):

  • Header: contains metadata about the type of token and the cryptographic algorithms used to secure its contents.
  • Payload (set of claims): contains verifiable security statements, such as the identity of the user and the permissions they are allowed.
  • Signature: used to validate that the token is trustworthy and has not been tampered with. You must verify this signature before storing and using a JWT.

A JWT typically looks like this: Encoded JWT

To see for yourself what is inside a JWT, use the JWT.io Debugger. It will allow you to quickly check that a JWT is well formed and manually inspect the values of the various claims.

JWT.IO Debugger

Where can I find my secret or public key?

For RS256:

  1. Navigate to the Applications page in the Auth0 Dashboard, and click the name of the Application to view.
  2. Scroll to the bottom of the page, click Advanced Settings, and click the Certificates tab. You will find the Public Key in the Signing Certificate field.

For HS256:

  1. Navigate to the Applications page in the Auth0 Dashboard, and click the name of the Application to view. You will find your Secret in the Client Secret field.

The header typically consists of two parts: the hashing algorithm being used (e.g., HMAC SHA256 or RSA) and the type of the token (JWT).

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

Payload

The payload contains statements about the entity (typically, the user) and additional entity attributes, which are called claims. In this example, our entity is a user.

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}

When working with JWT claims, you should be aware of the different claim types and naming rules.

Signature

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

To create the signature, the Base64-encoded header and payload are taken, along with a secret, and signed with the algorithm specified in the header.

For example, if you are creating a signature for a token using the HMAC SHA256 algorithm, you would do the following:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

However you use a JWT, you must check its signature before storing and using it.