What JSON Web Token (JWT) Is

JSON Web Token (JWT) is an open standard that provides a secure way for authenticating data owners and transmitting information between parties using the JSON format. JWT is sent in the HTTP request with a digital signature. It can be signed using a secret (with the HMAC algorithm) or a public/private key pair (with RSA or ECDSA).

To create a digital signature, Cloudentity signs JWT with its private key. When the client application gets the JWT from Cloudentity, it can verify if the JWT is signed by Cloudentity by using the public key of Cloudentity. Since the digital signature uses the private key of Cloudentity, the only party that could create the signature is Cloudentity, which proves the legitimacy of the JWT.

Try it now

Cloudentity comes with multi-tenant authorization server as a service.

Launch OAuth Server

Learn More

For request objects sent from the client application to the authorization endpoint, the client application signs JWT with its private key. The public key is registered within Cloudentity. When Cloudentity receives the JWT, it is able to verify the signature using the public key of the client application.

Each JWT needs to be signed in accordance with JSON Web Signature (JWS). Optionally, JWTs can be also encrypted as specified by JSON Web Encryption (JWE). What actually gets encrypted is the payload part, which holds claims. JWE makes the payload difficult to penetrate and claims secure against being compromised. If JWS is used only, plaintext claims in the non-encrypted payload are easily verifiable but also less secure when an unauthorized party tries to read them.

Cloudentity uses the JWT format to generate access tokens when it’s requested by the client application on behalf of the user. Cloudentity returns the JWT access token, which can be used by the client applications to make calls to APIs stored on the resource server.

JWT Usage

JWT support authentication for applications that try to access particular resources. Two most typical usage scenarios for JWT are the following:

• Authorization: JWTs can be used to authorize client applications before they request access tokens as a part of the JWT Bearer grant type

• Client authentication: To access specific resources, the client application authenticates itself with JWTs included as access tokens.

• Data transmission: JWTs can be used for safe and secure information exchange between two parties. Since they use digital signatures, the transmitted data can be verified and trusted in terms of parties involved in the exchange. Also, the integrity of the content can be verified as the signature gets calculated with the header and the payload.

JWT Structure

JWTs consist of three Base64-URL-encoded strings separated by dots:

• Header: The element that specifies the token type and the signing algorithm (HMAC SHA256 or RSA).

• Payload: The element that specifies the token issuer, the token expiration, and more. It includes claims, which are pieces of information regarding a particular entity, for example, the user.

• Signature: The element certifying that the message hasn’t been corrupted in transit. It is produced by combining the encoded header, the encoded payload, a secret, the algorithm defined in the header, and signing it. If your token is signed with a private key, you can check the identity of the JWT sender.

JWT Template

By coding, the three components are tied together so that the generic JWT structure can be represented as follows:

Header.Payload.Signature

JWT Example

Header

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

encoded to:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Payload

{
  "client_id": "YzEzMGdoMHJnOHBiOG1ibDhyNTA=",
  "response_type": "code",
  "scope": "introscpect_tokens, revoke_tokens",
  "iss": "bjhIRjM1cXpaa21zdWtISnp6ejlMbk44bTlNZjk3dXE=",
  "sub": "YzEzMGdoMHJnOHBiOG1ibDhyNTA=",
  "aud": "https://localhost:8443/{tid}/{aid}/oauth2/authorize",
  "jti": "1516239022",
  "exp": "2021-05-17T07:09:48.000+0545"
}

encoded to:

eyJjbGllbnRfaWQiOiJZekV6TUdkb01ISm5PSEJpT0cxaWJEaHlOVEE9IiwicmVzcG9uc2Vf
dHlwZSI6ImNvZGUiLCJzY29wZSI6ImludHJvc2NwZWN0X3Rva2VucywgcmV2b2tlX3Rva2Vu
cyIsImlzcyI6ImJqaElSak0xY1hwYWEyMXpkV3RJU25wNmVqbE1iazQ0YlRsTlpqazNkWEU9
Iiwic3ViIjoiWXpFek1HZG9NSEpuT0hCaU9HMWliRGh5TlRBPSIsImF1ZCI6Imh0dHBzOi8v
bG9jYWxob3N0Ojg0NDMve3RpZH0ve2FpZH0vb2F1dGgyL2F1dGhvcml6ZSIsImp0aSI6IjE1
MTYyMzkwMjIiLCJleHAiOiIyMDIxLTA1LTE3VDA3OjA5OjQ4LjAwMCswNTQ1In0

Signature

RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload), public key, private key
)

encoded to:

IxvaN4ER-PlPgLYzfRhk_JiY4VAow3GNjaK5rYCINFsEPa7VaYnRsaCmQVq8CTgddihEPPXe
t2laH8_c3WqxY4AeZO5eljwSCobCHzxYdOoFKbpNXIm7dqHg_5xpQz-YBJMiDM1ILOEsER8A
DyF4NC2sN0K_0t6xZLSAQIRrHvpGOrtYr5E-SllTWHWPmqCkX2BUZxoYNK2FWgQZpuUOD55H
fsvFXNVQa_5TFRDibi9LsT7Sd_az0iGB0TfAb0v3ZR0qnmgyp5pTeIeU5UqhtbgU9RnUCVmG
IK-SZYNvrlXgv9hiKAZGhLgeI8hO40utfT2YTYHgD2Aiufqo3RIbJA

Full JSON Web Token

Extra line breaks are added for display purposes.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJjbGllbnRfaWQiOiJZekV6TUdkb01ISm5PSEJpT0cxaWJEaHlOVEE9IiwicmVzcG9uc2Vf
dHlwZSI6ImNvZGUiLCJzY29wZSI6ImludHJvc2NwZWN0X3Rva2VucywgcmV2b2tlX3Rva2Vu
cyIsImlzcyI6ImJqaElSak0xY1hwYWEyMXpkV3RJU25wNmVqbE1iazQ0YlRsTlpqazNkWEU9
Iiwic3ViIjoiWXpFek1HZG9NSEpuT0hCaU9HMWliRGh5TlRBPSIsImF1ZCI6Imh0dHBzOi8v
bG9jYWxob3N0Ojg0NDMve3RpZH0ve2FpZH0vb2F1dGgyL2F1dGhvcml6ZSIsImp0aSI6IjE1
MTYyMzkwMjIiLCJleHAiOiIyMDIxLTA1LTE3VDA3OjA5OjQ4LjAwMCswNTQ1In0.
IxvaN4ER-PlPgLYzfRhk_JiY4VAow3GNjaK5rYCINFsEPa7VaYnRsaCmQVq8CTgddihEPPXe
t2laH8_c3WqxY4AeZO5eljwSCobCHzxYdOoFKbpNXIm7dqHg_5xpQz-YBJMiDM1ILOEsER8A
DyF4NC2sN0K_0t6xZLSAQIRrHvpGOrtYr5E-SllTWHWPmqCkX2BUZxoYNK2FWgQZpuUOD55H
fsvFXNVQa_5TFRDibi9LsT7Sd_az0iGB0TfAb0v3ZR0qnmgyp5pTeIeU5UqhtbgU9RnUCVmG
IK-SZYNvrlXgv9hiKAZGhLgeI8hO40utfT2YTYHgD2Aiufqo3RIbJA

Note

JWT needs to be digitally signed. Cloudentity rejects JWTs with invalid signatures.

JWT in Cloudentity

In Cloudentity, tokens are configurable per workspace (authorization server). You can preview and modify tokens settings for a particular workspace by entering the workspace and navigating to Auth Server > Tokens.

Cloudentity allows for using JWTs as access tokens. For this purpose, you need set the access token type to JWT in a particular workspace under Auth Server > Tokens > Type > JSON WEB TOKEN (JWT).

Note

The other access token type that Cloudentity allows is the opaque token, which unlike JWT is an unreadable random string of characters.

Read More

For more information on access tokens, see Access token: concept, purpose, way it works.