Projects

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.

Add a user JWT token to your Descope project

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.

Example of the configurations available within the Default User JWT template in Descope

Example of the configurations available within the Hasura JWT template in Descope

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

If a user has a single tenant they're associated with, there is a control for automatically setting the DCT (Descope Current Tenant) claim to the default tenant. The user can enable this feature by toggling and setting the current/default tenant as active.

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.

Custom claims configuration in simple mode on user JWT Template within Descope

Custom claims configuration in advanced mode on user JWT Template within Descope

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.

Set the project's user token format within Descope project settings

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.

Test the configured user JWT template within Descope flow runner

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.

Add an access key JWT token to your Descope project

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.

Example of the configurations available within the Mongo DB Access Key JWT template in Descope

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.

Custom claims configuration in advanced mode on an access key JWT Template within Descope

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.

Set the project's Access Key token format within Descope project settings

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.

{
  "aud": [
    "xxxx"
  ],
  "drn": "DS",
  "exp": 1716306477,
  "iat": 1716305877,
  "iss": "xxxxx",
  "myCustomClaim": false,
  "rexp": "2024-06-18T15:37:57Z",
  "sub": "xxxx",
  "tenants": {
    "xxxxx": {
      "permissions": [
        "SSO Admin",
        "User Admin",
        "Impersonate"
      ],
      "roles": [
        "Tenant Admin"
      ]
    }
  }
}
Was this helpful?

Previous

Managing Environments

Next

Company Settings

On this page

JWT TemplatesUser JWT TemplatesAdding User JWT TemplateConfiguring the User JWT TemplateGeneralAuthorization ClaimsCustom ClaimsSet the Project's User Token FormatTest the User JWT TemplateAccess Key JWT TemplatesAdding Access Key JWT TokensConfiguring the Access Key JWT TemplateGeneralAuthorization ClaimsCustom ClaimsSet the Project's Access Key Token FormatTest the Access Key JWT Template