Intro

A JSON Web Token (JWT, pronounced “jot”) is a token for sharing claims. Claims are encoded JSON objects that include some information about a subject and are often used in identity security applications to transfer information about a user. A JWT is an open-standards approach to securely sharing information between a client and a server in a compact, self-contained way that provides stateless authentication.

For example, after you sign in to a website, information about your account is encoded and passed around to the relevant parties in a JWT. This can enable single sign-on (SSO), which means you do not have to sign in again to another domain owned by the same company. Instead, your information can be passed between domains in the JWT, so the second domain knows who you are and that you have already been authenticated by a trusted party.

The main benefits of using a JWT are:

• Compact representation of information about a subject or user
• They can be encrypted or digitally signed so the information can be passed around securely

Components of a JWT

Technically, a JWT is represented as a JWS (JSON Web Signature) object or a JWE (JSON Web Encryption) object. However, the entire string is often referred to as a JWT if the payload is an encoded JWT object. [JWTs are always represented using the JWS Compact Serialization or the JWE Compact Serialization](https://tools.ietf.org/html/rfc7519#section-1).

There are three main parts of a JWS or JWE that include a JWT claim:

1. Header: The type of encoded object in the payload and any extra encoding
2. Payload: The JWT claims set
3. Signature: An encoding of the header and payload

The main parts are encoded then concatenated with a “.” separating them, so that it looks like

  {header}.{payload}.{signature}

This is your JWS or JWE object.

The commponents are described below.

Header

The header includes information about how the JWT claims set, the payload, is encoded. For example, take a look at the following header:

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

This tells us that we have a JWT that is integrity protected with the HMAC SHA-256 algorithm. The payload with a JWE including this header will be of a JWT signed and encrypted with the HMAC SHA-256 algorithm. The type may be left out if the JWSs and JWEs used by the application are JWT types. It’s intended to avoid confusion when different types are being used.

Payload

The payload contains the JWT object itself, and the JWT itself is just a set of claims. For example, take a look at the following payload:

{
  "aud": "https://api.pingone.com",
  "iss": "https://auth.pingone.com/abcdefg12345/as",
  "exp": "1300819380”
}

This payload has an audience (“aud”) of the PingOne for Customers API, an issuer (“iss”) of the PingOne for Customers Authorization Server, and has a set expiration date (“exp”). These are some common claim names, but they will vary depending on the application and service being used.

Signature

The signature is the header and payload (JWT claims set) encoded using the algorithm specified in the header. In our example above it would be the encoded header concatenated with the encoded JWT claims set encoded with the HMAC SHA-256 algorithm.

JWT Encoder Tool

Use the tool by following these steps:

1. First, remember that JWTs are tokens that are often used as the credentials for SSO applications (mostly for OAuth 2.0). The token is entirely decoded client side in the browser, so make sure to take proper precautions to protect your token
2. Fill out the header. A common usecase is supplied as an example to work off of or to use. The tool currently supports the algorithms of RS256 and HS256
3. Fill out the payload. Use custom claims or predefined ones like the ones listed at the start
4. Fill out the signature with either an RSA Private Key for RS56 or HS256 passcode.* The RSA Private key should have the header and footer shown in the example.
5. Press the Encode button
6. Enjoy your newly created JWT. Try out the JWT Decoder tool to verify the contents of the JWT.

 

*These should be kept private! All calculations happen within the browser, but you should still be careful with sharing these values for production apps. Suggested use is for testing only.

Sign up for a free trial of PingOne to play around with OAuth 2.0 apps and learn the flow and how JWTs fit into an SSO scenario.

For more information

• Ping Identity Developer Resources
• Ping Identity Glossary