Using custom claim templates

If you want to add the same set of custom claims to every session for your project, Custom Claim Templates may be a good fit.

Custom Claim Templates can be used to:

• Pass RBAC information from User Metadata to Sessions.
• Integrate with third-party providers that support JWT-based authentication, such as Hasura.

Custom Claim Templates use a markup language to generate a JSON object using the user's information.

• The JSON object output for a particular user will be used as the initial set of custom claims for all of that user's sessions.
• Claims from templates can still be updated, deleted, or added to by passing in a session_custom_claims argument in an API request.
• Claims from Custom Claim Templates are subject to the same set of limitations that API-driven custom claims have: the total size cannot exceed 4kb, and no registered claims may be used to ensure interoperability.
• Updates to the Custom Claim Template or User Metadata will propagate to existing sessions the next time a JWT is minted. Previously minted JWTs are immutable and cannot be updated. Clients can force a new JWT to be minted by calling the Authenticate Session endpoint.

The Custom Claim Template markup language uses {{ variable }} syntax to denote information that should be passed in at runtime. When dealing with User Metadata, use dot notation to access nested fields, e.g. {{ user.trusted_metadata.subscription.level }} will access the level field of the subscription object in trusted_metadata on a Stytch User object.

Variables can evaluate to any JSON object - strings, numbers, null, objects, or arrays. Variables can only be used as JSON values, and cannot be used as object keys.

If a variable evaluates to null, or attempts to access a value that does not exist, the generated claim will not be present in the output.

Today, the following template variables are supported:

• {{ user.user_id }}
• {{ user.full_name }}
• {{ user.trusted_metadata.$PATH }}

More variables will be added in the future.

For example, the template:

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "reader",
    "x-hasura-allowed-roles": {{ user.trusted_metadata.roles }},
    "x-hasura-user-id": {{ user.user_id }}
  }
}

could be combined with the user information:

{
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "trusted_metadata": {
    "roles": ["admin", "reader"]
  }
}

to produce the final set of custom claims:

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "reader",
    "x-hasura-allowed-roles": ["admin", "reader"],
    "x-hasura-user-id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
  }
}

Any feedback? We'd love to hear it! Reach out to support@stytch.com.