JSON Web Tokens (JWT)
In some instances, you may wish to use an Identity Management Provider that is separate to the Zephr Identity Store. Integrating an external identity store with Zephr is simple, as Zephr has a number of integration points with other data sources. Our recommendation for doing this, however, is to use a JWT for each user.
In this scenario, the identity provider signs a JWT and sets it as a cookie or otherwise; requests to Zephr that have the appropriate Bearer token will inherit products (entitlement grants) and user attributes based upon claims in the payload. This guide discusses the use of JWT tokens with Zephr and guides you through the setup process.
What is a JWT token?
JSON Web Tokens are cryptographically verified payloads that can be passed with HTTP requests, much like a cookie. JWTs are used to pass information between server-side systems, via an end user’s client (a Web browser) without allowing the information to be tampered with.
A JWT consists of three parts: a metadata header, a payload (JSON) and a signature. A JWT is created by signing then payload using a private key, the public key can then be shared with interested 3rd parties who can then verify the integrity of the payload.
How does JWT work with Zephr?
When using JWT with Zephr, it is important to know that your identity provider is able to provide a JWT when a user logs in. This is typically done as a browser cookie (using the Set-Cookie header) but can be handled in other ways too.
In these implementations, login and registration requests will happen against your Identity Management system, independently to any Zephr function.
For all site requests running through Zephr, there will be a check for a valid JWT which, if present, will be used as the inputs to any decisions, including whether a user has a particular entitlement.
Configuring the Zephr JWT Integration
JWT mappings can be used within Zephr to map products from another identity source, to the products set up within Zephr, in order to be used in Decisions.
To configure your JWT integration and enable product syncing, navigate to Setting > Integrations > JWT. Here you will see fields to enter your Secret or Public Key which will be used to verify signatures and enable product syncing. Once you have entered these details, click Save.
Enabling Product Syncing with JWT
Following this, tick the box Enable Product Syncing and click OK. Set the Private Claim Name to be the key from the JWT payload that your Identity Management provider will use to describe the entitlements. Once complete, click Save.
Enabling Product syncing will allow products to be granted based on the contents of the JWT token. Once the integration is set up, you will need to create Zephr Products with set JWT values.
Navigate to Entitlement Manager > Products and click Add Product.
Add a Label and assign the relevant Entitlement Bundle.
Next, you will need to add a Claim Value, under the heading Session auto-assignment methods. Set this value to the value your IDM will put into the JWT payload if a user should have the product (note that arrays and string values are supported in the payload). Click Add Product.
When the JWT syncing for a product is set up, any bearer with a JWT payload that asserts they hold a product will inherit the mapped entitlement bundle (and all descendants).
An example payload including a product subscription, and first-party data:
{
“sub”: [“subscription-a”],
“city”: “NY”
}
Following this setup, you’ll be able to use the Zephr Rules builder to create rule-based upon both the entitlements set within your Product bundle and the first-party data (such as city above) that is being set in the JWT token.
Enabling User Mapping with JWT
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 Authenticated Meters and Credits, or A/B 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 used meters and credits, or fallen into an A/B test group.
To set this up, navigate to Settings > JWT within your Zephr Admin Console. 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, meaning Zephr can look for a User’s entitlement model based upon their Foreign Key. To enable this, tick the box labeled Map Foreign User ID to Blaize User Store. 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.
Considerations
The main consideration for a JWT-based integration is managing the lifecycle of the token. JWT uses an “exp” claim for expiry time, which Zephr honors. However, as the token is set by your identity provider, it will need to be periodically updated if Zephr is to act upon up-to-date information about a user.
A second consideration is that the Zephr identity module will not be in use, so some features such as user search will be redundant. This includes using the Session Segments within a Feature or Request Rule, which allows you to check if a user is logged in.