JSON Web Tokens
Find out what JWT is and explore its structure. Learn why you need to use it and check its examples.
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, SecureAuth signs JWT with its private key. When the client application gets the JWT from SecureAuth, it can verify if the JWT is signed by SecureAuth by using the public key of SecureAuth. Since the digital signature uses the private key of SecureAuth, the only party that could create the signature is SecureAuth, 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 SecureAuth. When SecureAuth 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.
SecureAuth uses the JWT format to generate access tokens when it's requested by the client application on behalf of the user. SecureAuth 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. SecureAuth rejects JWTs with invalid signatures.
JWT in SecureAuth
In SecureAuth, 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.
SecureAuth 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 SecureAuth allows is the opaque token, which unlike JWT is an unreadable random string of characters.
For more information on access tokens, see Access Token.