home

Zephr

Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies
Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies

Welcome to Zuora Product Documentation

Explore our rich library of product information

Show Contents

thumbnailZephr

JSON Web Tokens (JWT)

Enabling user mapping with JWT

Learn how to enable User Mapping in Zephr using JWT to identify user sessions across devices.

When using Zephr with a third-party identity management tool, you may wish to enable User Mapping. User Mapping allows you to take information from a JWT token and use it to further identify a user's session within Zephr by setting a Foreign User ID Property as the cross-device session ID.

This is particularly important if you wish to use Trials or Bucket test groups within Zephr as it allows Zephr to recognise Users who are not in stored within the Zephr IDM but have had previous sessions where they may have been granted a trial or fallen into a Bucket test group.

To set this up:

  1. Navigate to Settings > JSON Web Tokens within your Zephr Admin Console.
  2. Scroll to the User Mapping section and click Enable User Mapping.
    Here you will need to add the Foreign User ID Property that you wish Zephr to use as your cross-device session ID. This is also known as your claim name.
    Zephr also allows you to set a Foreign Key System, which allows Zephr to look for a user's entitlement model based on their Foreign Key. The specified Foreign User ID Property links to the field of the same name in the JWT; for example, prodsub. This means that Zephr can use the field to identify the user's session by the user ID provided in the JWT field when the end user is stored in a third-party identity management system. For example this allows Zephr to recognise that the end user has had previous sessions where they might have been granted a trial or fallen into a split test group.
  3. To enable this, tick the box labeled Map Foreign User ID to User Store.
  4. Once ticked, enter a name for the Foreign Key System you want to use to map a JWT body to a Zephr User.
    When using this feature in conjunction with the manual User Import feature, be sure to set the same Foreign System, as an exact match.

Last updated: October 10, 2025