JWT Claims

Custom claims are included in your JWTs (session tokens, refresh tokens, and ID tokens when using Descope as an OIDC provider). You can add custom claims to your JWTs by adding the Custom Claims action in your flow, or by using a JWT Template.

Important

Since refresh tokens in production are typically stored as cookies, be aware that custom claims will contribute to the cookie size and must stay within browser cookie limits.

See the Cookie Size section below for more information.

When using custom claims however, it's important to understand all of the functionalities inherent in them, as well as how to use them securely and responsibly. This guide will focus on all of the different security aspects of custom claims, as well as recommended best practices to employ when using them.

Descope stores your custom claims in the refresh token. In order to properly store your refresh tokens, we typically suggest storing them in a samesite=strict, httpOnly=true, secure cookie.

Since cookies have a maximum size of 4kb supported by browsers, storing information in a custom claim while using cookies (the recommended way) might be a problem. Therefore, it's best to not store too much in the JWT to make sure you don't run into any storage limitation issues.

Note that each key can have a maximum of 60 chars, each claim value can have a maximum of 500 chars, and each JWT can have a maximum of 100 keys.

Do Not Store Sensitive Information

You should never store any sensitive user information in a JWT. This can be sensitive user PII, or other secrets related to your application or authentication architecture. JWTs are just Base 64 encoded tokens, and even if they are stored securely, that sensitive information could be exposed if your JWT was ever compromised by a malicious hacker.

Secure vs Non-Secured Custom Claims

The backend cannot trust custom claims specified by the client SDK or API due to the following items:

Potential tampering and spoofing by malicious hackers
The lack of a verification mechanism for client-added claims
The violation of defined trust boundaries which treat client data as untrusted
Inconsistent enforcement policies on accepted claims
The foundational security principle that cautions against trusting user input.

With this security in mind, custom claims added by the client SDK will be within the nsec claim in the session token JWT.

When utilizing the management SDK or Descope flows, custom claims that are added will be marked secure, and will not be within the nsec claim.

Below is an example of a session JWT with custom claims added under the nsec claim since they were added by the client.

{
  "amr": [
    "email"
  ],
  "drn": "DS",
  "exp": 1692304651,
  "iat": 1692304051,
  "iss": "P2RFvFexVaxxNFK6rhP0ePtaGfTK",
  "nsec": {
    "email": "example@email.com",
    "name": "Joe Person"
  }
  "sub": "U2RG6grrbT3REKYqk5yC4SjkMqzA",
  "tenants": {
    "T2U7vUH1NPy4JzWHruoOVIGyzYlu": {
      "permissions": [
        "AppSecEngineer",
        "Marketing",
        "Support"
      ],
      "roles": [
        "Engineering",
        "Product Manager"
      ]
    },
    "T2U7vVBqyZv6HdGtGLdnkgCbNxrC": {
      "permissions": [
        "AppSecEngineer",
        "Support"
      ],
      "roles": [
        "Support"
      ]
    }
  }
}

Using the Audience (aud) Claim

The aud (Audience) claim in a JWT specifies the intended recipients of the token, ensuring the correct application or server uses it. It can be a single entity or multiple entities, defined as a string or an array of strings, to prevent the token from being accepted by unintended parties.

Descope allows you to append to the aud claim by utilizing the Custom Claims action to append an item. Below is an example of appending to the aud claim using the Descope custom claims action.

The returned JWT would look similar to the below.

Terminal

{
  "amr": [
    "oauth"
  ],
  "aud": [
    "xxxx",
    "something"
  ],
  "drn": "DS",
  "eml": "xxxx",
  "enabled": true,
  "exp": 1709674989,
  "iat": 1709674809,
  "iss": "xxxx",
  "name": "xxxx",
  "rexp": "2024-04-02T21:40:09Z",
  "sub": "xxxx",
  "tenants": {
    "xxxx": {}
  }
}

Overriding the AMR Claim

The amr (Authentication Methods Reference) claim is a standard claim in JWTs that indicates which authentication methods were used during the authentication process. By default, Descope sets this claim automatically based on the authentication method used (e.g., oauth, email, pwd, mfa, etc.).

However, in certain scenarios—particularly when using SSO authentication—you may want to override the amr claim to reflect the actual authentication methods used by the SSO provider, rather than just fed (federated authentication).

Note

This is especially useful when your SSO provider includes detailed authentication method information in their OIDC token, and you want to pass that information through to your application's JWT.

How to Override the AMR Claim

You can override the amr claim using either:

Custom Claims Action in Flows - Add a Custom Claims action in your authentication flow and set the amr key with your desired value
JWT Templates - Configure the amr claim in your JWT Template

Example using Custom Claims Action:

In the Custom Claims action, you can use the advanced configuration to override the amr claim:

{
  "amr": ["pwd", "mfa"]
}

Limitations

You should only use this override if your SSO provider actually supports and populates the amr claim in its OIDC tokens. Since not all providers do (for example, Google and Azure AD typically omit it), you should always verify that your SSO provider includes this information before implementing the override.

Additional Standard Claims

Azp Claim

When using Descope as an OIDC provider, we will automatically append the azp claim to your JWT as well. This is something you will only see if you're using OIDC.

Was this helpful?

On this page