Using JWT

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 to select the Appliance OS Configuration option, on 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.

1. JWT is created on ESA 1 for client application using a secret key.
2. ESA 1 and ESA 2 are added to TAC. The secret key of ESA 1 is shared with ESA 2.
3. 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.
4. 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:

1. On the CLI Manager, navigate to Administration > JWT Configuration.

   A screen to enter the root credentials appears.

2. Enter the root credentials and select OK.

   The JWT Settings screen appears.

3. Select Set JWT Algorithm to set the algorithm for validating a token.

   The Set JWT Algorithm screen appears.

   1. Select the one of the following algorithms:

      • HS512
      • HS384
      • HS256

   2. Select OK.

4. Select Set JWT Secret to set the secret key.

   The Set JWT Secret screen appears.

   1. Enter the secret key in the New Secret and Confirm Secret fields.

   2. Select OK.

5. Select Set Token Expiry to set the token expiry period.

6. In the Set Token Expiry field, enter the token expiry value and select OK.

7. Select Set Token Expiry Unit to set the unit for token expiry value.

8. Select second(s), minute(s), hour(s), day(s), week(s), month(s), or year(s) option and select OK.

9. Select Done.

Refreshing JWT

Tokens are valid for a 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.