Using JSON Web Token (JWT)
Tokens are reliable and secure mechanisms for authorizing and authenticating users. They are stateless objects created by a server that contain information to identify a user. Using a token, you can gain access to the server without having to provide the credentials for every resource. You request a token from the server by providing valid user credentials. On successive requests to the server, you provide the token as a source of authentication instead of providing the user credentials.
There are different mechanisms for authenticating and authorizing users using tokens. Authentication using JSON Web Tokens (JWT) is one of them. The JWT is an open standard that defines a secure way of transmitting data between two entities as JSON objects.
One of the common uses of JWT is as an API authentication mechanism that allows you to access the protected API resources on your server. You present the JWT generated from the server to access the protected APIs. The JWT is signed using a secret key. Using this secret key, the server verifies the token provided by the client. Any modification to the JWT results in an authentication failure. The information about tokens are not stored on the server.
Only a privileged user can create a JWT. To create a token, ensure that the Can Create JWT Token permission/privilege is assigned to the user role.
The JWT consists of the following three parts:
- Header: The header contains the type of token and the signing algorithm, such as, HS512, HS384, or HS256.
- Payload: The payload contains the information about the user and additional data.
- Signature: Using a secret key, you create the signature to sign the encoded header and payload.
The header and payload are encoded using the Base64Url encoding. The following is the format of JWT:
<encoded header>.<encoded payload>.<signature>
Implementing JWT
On Protegrity appliances, you must have the required authorization to access the REST API services. The following figure illustrates the flow of JWT on the appliances.
As shown in the figure, login with your credentials to access the API. The credentials are validated against a local or external LDAP. A verification is performed to check the API access for the username. After the credentials are validated, a JWT is created and sent to the user as an authentication mechanism. Using JWT, information can be verified and trusted as it is digitally signed. The JWTs can be signed using a secret with the HMAC algorithm or a private key pair using RSA. After you successfully login using your credentials, a JWT is returned from the server. When you want to access a protected resource on the server, you must send the JWT with the request in the headers.
Working with the Secret Key
The JWT is signed using a private secret key and sent to the client to ensure message is not changed during transmission. The secret key encodes that token sent to the client. The secret key is only known to the server for generating new tokens. The client presents the token to access the APIs on the server. Using the secret key, the server validates the token received by the client.
The secret key is generated when you install or upgrade your appliance. You can change the secret key from the CLI Manager. This secret key is stored in the appliance in a scrambled form.
For more information about setting the secret key, refer to section Configuring JWT
For appliances in a TAC, the secret key is shared between appliances in the cluster. Using the export-import process for a TAC, secret keys are exported and imported between the appliances.
If you want to export the JWT configuration to a file or another machine, ensure that you select the Appliance OS Configuration option, in the Export screen. Similarly, if you want to import the JWT configurations between appliances in a cluster, from the Cluster Export Wizard screen, select the Appliances JWT Configuration check box, under Appliance OS Configuration.
For example, consider ESA 1 and ESA 2 in a TAC setup.
- JWT is created on ESA 1 for appliance using a secret key.
- ESA 1 and ESA 2 are added to TAC. The secret key of ESA 1 is shared with ESA 2.
- Client application requests API access from ESA 1. A JWT is generated and shared with the client application. The client accesses the APIs available in ESA 1.
- To access the APIs of ESA 2, the same token generated by ESA1 is applicable for authentication.
Configuring JWT
You can configure the encoding algorithm, secret key, and JWT token expiry.
To configure the JWT settings:
On the CLI Manager, navigate to Administration > JWT Configuration.
A screen to enter the root credentials appears.
Enter the root credentials and select OK.
The JWT Settings screen appears.
Select Set JWT Algorithm to set the algorithm for validating a token.
The Set JWT Algorithm screen appears.
Select the one of the following algorithms:
- HS512
- HS384
- HS256
Select OK.
Select Set JWT Secret to set the secret key.
The Set JWT Secret screen appears.
Enter the secret key in the New Secret and Confirm Secret fields.
Select OK.
Select Set Token Expiry to set the token expiry period.
In the Set Token Expiry field, enter the token expiry value and select OK.
Select Set Token Expiry Unit to set the unit for token expiry value.
Select second(s), minute(s), hour(s), day(s), week(s), month(s), or year(s) option and select OK.
Select Done.
Refreshing JWT
Tokens are valid for certain period. When a token expires, you must request a new token by providing the user credentials. Instead of providing your credentials on every request, you can extend your access to the server resources by refreshing the token.
In the refresh token process, you request a new token from the server by presenting your current token instead of the username and password. The server checks the validity of the token to ensure that the current token is not expired. After the validity check is performed, a new token is issued to you for accessing the API resources.
In the Protegrity appliances, you can refresh the token by executing the REST API for token refresh.
Last modified February 7, 2025