JWT Templates

Overview

JSON Web Tokens (JWTs) are used for authentication and integration with various tools. Different tools have unique JWT formats, and Descope provides JWT Templates to help you customize your JWTs to match these formats seamlessly.

Managing JWTs in Descope

There are two primary ways to manage JWTs in Descope:

1. JWT Templates (Preferred Method)

   • JWT Templates allow for easy, code-manageable customization.
   • They are applied project-wide, making them the ideal solution for consistent JWT formatting.

2. Custom Claims in Flows

   • For flow-specific claims or claims related to scenarios like step-up authentication, use a custom claims action in a flow.
   • Learn more about custom claims actions here.

This doc explains how to set up each of the different types of JWT templates (User and Access Keys) along with different features of JWT templates, and how you manage them via Terraform.

User JWT Templates

User JWT Templates define the structure of JWTs issued to authenticated users. Descope offers default templates for popular tools and allows custom configurations to streamline integration.

Adding a User JWT Template

1. Navigate to Project Settings > JWT Templates in the Descope Console.
2. Click + JWT Template at the top right.
3. Select a User JWT template (filterable via the User JWT category).

Configuring a User JWT Template

Once added, customize the template to fit your integration needs. Below is an example of configurations available for Default User JWT and Hasura JWT templates.

General Settings

• Template Name - Custom name for the template.
• Template Description - Description for internal reference.

Authorization Claims Configuration

This section determines how authorization-related claims are structured:

• Default Descope JWT - Project-level roles and permissions in the root, tenant-specific roles inside each tenant object.
• Current Tenant, No Tenant Reference - Tenant-specific roles appear in the root, omitting the tenants claim.
• No Descope Claims - Excludes Descope's default claims, only including custom claims.

Custom Claims

• You can add string, boolean, numerical, or dynamic values.
• Advanced mode allows defining claims using a JSON object.

Setting the Project's User Token Format

1. Navigate to Project Settings > Session Management.
2. Select the preferred User JWT Token Format.
3. Click Save.

Testing the User JWT Template

Once configured, you can see the new JWT via the flow runner, under your flow editor page in the Descope Console, or through Descope Explorer.

Access Key JWT Templates

Access Key JWT Templates define the structure of JWTs issued when an Access Key is exchanged for a session.

Adding an Access Key JWT Template

1. Navigate to Project Settings > JWT Templates in the Descope Console.
2. Click + JWT Template at the top right.
3. Select an Access Key JWT template (filterable via the Access Keys JWT category).

Configuring an Access Key JWT Template

After adding a template, configure its settings. Below is an example of the MongoDB Access Key JWT Template.

General Settings

• Template Name - Custom name for the template.
• Template Description - Description for internal reference.

Authorization Claims Configuration

Same options as User JWT Templates:

• Default Descope JWT
• Current Tenant, No Tenant Reference
• No Descope Claims

Custom Claims

• You can add string, boolean, numerical, or dynamic values.
• Advanced mode allows defining claims using a JSON object.

Setting the Project's Access Key Token Format

1. Navigate to Project Settings > Session Management.
2. Select the preferred Access Key JWT Token Format.
3. Click Save.

Testing the Access Key JWT Template

You can test Access Key JWTs using any Descope SDK or API, as well as client credentials flow to exchange an Access Key for a session token.

Now that you've set up your JWT templates, you can ensure that your JWTs integrate smoothly with your application by customizing them to meet your specific requirements.

Empty Claims Policy

At the bottom of the JWT Template configuration page, you can define how to handle empty claims:

• Default (Leave as Is) - Claims with no values appear as empty strings ("").
• Null - Claims with no values are explicitly set to null.
• Empty - Claims with no values are omitted from the JWT.

This can also be managed via Terraform.

Dynamic Claims with JWT Templates

Claims in JWT templates can be dynamically updated based on real-time changes to user attributes or other relevant data. When a custom attribute is used as a claim in a JWT, its value will automatically update whenever the user's session is refreshed, provided the attribute has changed.

This ensures that JWTs always reflect the most current state of user information without requiring manual intervention or additional API calls.

This behavior is especially useful for enforcing real-time access control, adapting user permissions dynamically, and ensuring that dependent services always receive the latest claim data.

Managing JWT Templates via Terraform

You can configure JWT Templates using Terraform. Below is an example JWT template managed via our Terraform provider.

Example Terraform Configuration:

resource "descope_jwt_template" "example" {
  name               = "MyJWTTemplate"
  description        = "Custom JWT for my app"
  empty_claim_policy = "nil",
  auth_schema        = "default"
  enforce_issuer     = true
  template           = "{\"aud\":\"custom-aud\",\"custom_claim\":\"hellothere\"}"
}

Available Attributes:

• name (string, required) - JWT template name.
• description (string) - Template description.
• auth_schema (string, default: "default") - Defines authorization claims format.
• enforce_issuer (bool) - Enforce JWT issuer validation.
• template (string, required) - JSON schema for the JWT template.

For more details, visit our Terraform documentation.

By following this guide, you can effectively configure JWT templates to meet your application's needs.