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 Member or Organization 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 member's information.

• The JSON object output for a particular member will be used as the initial set of custom claims for all of that member'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 Member 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 Member or Organization Metadata , use dot notation to access nested fields, e.g. {{ member.trusted_metadata.subscription.level }} will access the level field of the subscription object in trusted_metadata on a Stytch Member object.

When dealing with Member RBAC values, the variable {{ member.rbac.roles }} will be evaluated as an array of all role IDs assigned to the member, e.g. ["stytch_member", "editor", "support_admin"] . The variable {{ member.rbac.$RESOURCE_ID.actions }} will be evaluated as an array of all actions the member can perform on the specific resource. For example, {{ member.rbac.documents.actions }} might be evaluated as ["create", "read", "delete"].

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:

• {{ member.external_id }}
• {{ member.member_id }}
• {{ member.name }}
• {{ member.email_address }}
• {{ member.rbac.roles }}
• {{ member.rbac.$RESOURCE_ID.actions }}
• {{ member.trusted_metadata.$PATH }}
• {{ organization.external_id }}
• {{ organization.organization_id }}
• {{ organization.organization_name }}
• {{ organization.trusted_metadata.$PATH }}

More variables may be added in the future.

For example, the template:

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "reader",
    "x-hasura-allowed-roles": {{ member.rbac.roles }},
    "x-hasura-user-id": {{ member.member_id }},
    "x-hasura-custom-key": {{ member.trusted_metadata.custom_key }},
    "x-hasura-organization-id": {{ organization.organization_id }}
  }
}

could be combined with the member's information:

{
  "member_id": "member-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "trusted_metadata": {
    "custom_key": "custom-value"
  }
}

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": "member-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "x-hasura-custom-key": "custom-value",
    "x-hasura-organization-id": "org-test-12345"
  }
}

• Learn about adding custom claims to sessions
• Explore RBAC overview to understand role-based access control
• Set up your first Custom Claim Template

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