JWT Templates
Within the web development industry, JSON Web Tokens (JWTs) have various uses beyond authentication, and many tools have their preferred format for integrating JWTs seamlessly with their tools. Descope understands the need to deliver JWTs that match these formats and offers the ability to utilize JWT Templates to empower you to match these formats easily. This guide will cover implementing and using user and access key JWT Templates within Descope.
User JWT Templates
User JWT Templates affect the template utilized for user authentication. These templates will configure the JWT the end user receives after valid authentication via Descope flows or the SDK.
Descope provides a wide range of out-of-the-box templates for known tools and constantly adds more. This flexibility allows you to integrate with third-party tools seamlessly. Moreover, you can also configure the default Descope User JWT template, eliminating the need to configure custom claims throughout your various Descope flows.
Adding User JWT Template
To configure User JWT templates, within the Descope console, navigate to
the JWT Templates tab within project settings, click the
blue + JWT Template
at the top right, and then click the applicable user related JWT template. The user-related
templates can be filtered from this modal by selecting User JWT
next to the search bar and are identified by a
blue Users
label.
Configuring the User JWT Template
Once you have selected and added a user JWT template, you can customize it. The below section will guide you through the available configurations and how they impact the templates. Below is an example of the configuration page for the Default User JWT and Hasura templates.
General
- Template Name: Your configured name for the JWT template.
- Template Description: Your configured description for the JWT template.
Authorization Claims
This section allows you to define the format in which authorization related claims will appear.
This section allows you to define the format in which authorization-related claims will appear. The configuration options are:
- Default Descope JWT: Project level roles and permissions appear in the root of the JWT, while tenant roles and permissions appear within each tenant.
- Current tenant, no tenant reference: Tenant level roles and permissions will appear in the root of the JWT, and there will be no reference to the tenant itself (no tenants claim).
- No Descope claims: Only custom claims will be added to the JWT. No Descope claims will be present.
Custom Claims
Within the custom claims simple configuration, you can add string, boolean, numerical, or dynamic values and assign to your desired keys. The dynamic values are populated from available data from Descope pertaining to the user.
You can also utilize the advanced configuration by clicking Advanced within the custom claims action. There, you can work with the custom claims as a JSON object.
Set the Project's User Token Format
Now that you have configured your User JWT template navigate back to the Project Settings tab, scroll to the Session Management section, select the desired User JWT token format, and save.
Test the User JWT Template
Once fully configured for the project, you can test the configuration within your application, the Descope flow runner or Descope Explorer.
Access Key JWT Templates
Access Key JWT templates affect the template utilized for JWTs granted when an access key is exchanged for a session.
Descope provides a wide range of out-of-the-box templates for known tools and constantly adds more. This flexibility allows you to integrate with third-party tools seamlessly. Moreover, you can also configure the default Descope Access Key JWT template, eliminating the need to configure custom claims during the access key exchange with Descope's API or SDK.
Adding Access Key JWT Tokens
To configure Access Key JWT templates, within the Descope console, navigate to
the JWT Templates tab within project settings, click the
blue + JWT Template
at the top right, and then click the applicable access key related JWT template. The access
key-related templates can be filtered from this model by selecting Access Keys JWT
next to the search bar, identified
by a blue Access Keys
label.
Configuring the Access Key JWT Template
Once you have selected and added an Access Key JWT template, you can customize it. The below section will guide you through the available configurations and how they impact the templates. Below is an example of the configuration page for the Mongo DB Access Key template.
General
- Template Name: Your configured name for the JWT template.
- Template Description: Your configured description for the JWT template.
Authorization Claims
This section allows you to define the format in which authorization related claims will appear.
This section allows you to define the format in which authorization-related claims will appear. The configuration options are:
- Default Descope JWT: Project level roles and permissions appear in the root of the JWT, while tenant roles and permissions appear within each tenant.
- Current tenant, no tenant reference: Tenant level roles and permissions will appear in the root of the JWT, and there will be no reference to the tenant itself (no tenants claim).
- No Descope claims: Only custom claims will be added to the JWT. No Descope claims will be present.
Custom Claims
Access Key JWT templates will affect any JWTs created with Access Keys. This includes JWTs created using OAuth 2.0 Client Credentials flow, as described in our OIDC Application guide.
Within the custom claims simple configuration, you can add string, boolean, numerical, or dynamic values and assign to your desired keys. The dynamic values are populated from available data from Descope pertaining to the access key.
You can also utilize the advanced configuration by clicking Advanced within the custom claims action. There, you can work with the custom claims as a JSON object.
Set the Project's Access Key Token Format
Now that you have configured your Access Key JWT template navigate back to the Project Settings tab, scroll to the Session Management section, select the desired Access Key JWT token format, and save.
Test the Access Key JWT Template
Once fully configured for the project, you can test the configuration using any of the Descope SDKs or API to exchange the access key for a session token. You can then parse the session token to check the claim items.