JSON Web Token for authorizing access

Find out what JWT is and explore its structure. Learn why you need to use it and check its examples.

JWT concept

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, ACP signs JWT with its private key. When the client application gets the JWT from ACP, it can verify if the JWT is signed by ACP by using the public key of ACP. Since the digital signature uses the private key of ACP, the only party that could create the signature is ACP, which proves the legitimacy of the JWT.

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 ACP. When ACP 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.

ACP uses the JWT format to generate access tokens when it’s requested by the client application on behalf of the user. ACP 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: To access specific resources, the client application request authorization to APIs by calling particular endpoints 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

{
  "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. ACP rejects JWTs with invalid signatures.

How it works

Note

For information on the authentication flow using JWT, see Client authentication using private_key_jw.

[mermaid-begin]
sequenceDiagram Client application->>ACP: JWT requested (1) ACP->>ACP: JWT issued and encoded ACP->>Client application: JWT returned (2) Client application->>Client application: JWT verified Client application->>API: API called with JWT (3) note right of ACP: JWT passed in the header API->>API: JWT verified API->>Client application: Data returned (4)
  1. Client application requests a JWT from ACP.
  2. After issuing and encoding the JWT, ACP delivers it to the client application.
  3. Client application calls the protected API with the JWT received.
  4. After the resource server (API) verifies the authenticity of the JWT, it returns the protected resource to the the client application.

Read more

Check Introduction to JSON Web Tokens for more information on JWT.

JWT in ACP

In ACP, 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 Workspace settings > Tokens.

ACP allows for using JWTs as access tokens. For this purpose, you need set the access token type to JWT in a particular workspace: Navigating to Workspace settings > Tokens > Access token type > JSON WEB TOKEN (JWT).

Note

The other access token type that ACP 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.