JWT claims include information about a subject and transfer information about a user. JWTs are trusted because they are signed using either a secret (HMAC) or a public-private key pair (RSA or ECDSA). JWTs are defined in JSON Web Token (JWT) and Introduction to JSON Web Tokens.

JWTs are commonly used for authorization, and particularly single sign-on (SSO). For example, after authenticating to a service, information about the user is encoded and shared between other relevant parties in a JWT. Subsequent domains know who the user is and that they have already been authenticated by a trusted party, so the user can access many different services after signing on once.

JWTs are an increasingly common way to secure APIs. You can share JWTs using URLs, POST parameters, or headers. JWT claims are embedded as JSON objects, which are used as the payload of a JSON Web Signature (JWS) structure or as text for a JSON Web Encryption (JWE) structure.

JWT Components

A JWT is defined as either a JWS object or a JWE object. When a token is signed it uses JWS, and when encrypted it uses JWE. There are three main parts of a JWS or JWE that include a JWT claim:

Header

The type of encoded object in the payload and information about how it is encoded.

See the following example header:

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

This header shows 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 property can be left out if the JWSs and JWEs used by the application are JWT types. This property is intended to prevent confusion when different types are being used.

Payload

The JWT object itself, which is a set of claims.

See the following example payload:

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

This payload has an audience, aud, of the PingOne API, an issuer, iss, of the PingOne Authorization Server, and has a set expiration date, exp. The claim names might vary depending on the application and service being used.

Signature

The header and payload encoded using the algorithm specified in the header. In this example, the signature is the encoded header concatenated with the encoded JWT payload encoded with the HMAC SHA-256 algorithm.

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

Javascript Object Signing and Encryption (JOSE)

A JWT defines the token format and uses supporting specifications to handle signing and encryption. This collection of specifications is known as JOSE and consists of the following components:

JSON Web Signature (JWS)
Defines the process to digitally sign a JWT
JSON Web Encryption (JWE)
Defines the process to encrypt a JWT
JSON Web Algortihm (JWA)
Defines a list of algorithms for digitally signing or encrypting
JSON Web Key (JWK)
Defines how a cryptographic key and sets of keys are represented

Encoded JSON objects within JWTs include a set of claims signed using an algorithm so that they cannot be altered after a token is issued. Claims can be signed digitally or protected using message authentication code (MAC) with encryption. Encryption without MAC is also an option. When a user signs on using credentials, the OpenID Connect (OIDC) specification dictates that they receive an ID token in return, which is always a JWT.

For more information on JOSE, see Javascript Object Signing and Encryption (JOSE).