Note: This functionality must be enabled by a Pendo employee. Please reach out to help@pendo.io to request access.
Installation
Snippet installation with JWT (JSON Web Token) requires requests to be signed using your shared secret with JWT. This type of installation is optional and requires an identified Visitor ID to process data.
Note: this is not encryption. Think of it as a hotel key: you register at the front desk, and they give you a plastic electronic key with which you can access your room, the pool, and the garage - but you can't open other people's rooms or go into the manager's office. And, like a hotel key, when your stay has ended, you're simply left with a useless piece of plastic (i.e., the token doesn't do anything anymore after it's expired).
The JWT that is passed into pendo.initialize() should contain a "nonce" property. This is a string that is randomly generated by the client. It must be at the top level in the JSON - a sibling property to "visitor" or "account", not contained within one of those sections. The value is not explicitly validated, but a value is required. It is used so that there is data to sign when anonymous visitors are used and a visitor id is not passed from the client to the agent.
Enabling JWT
To get started, you can find the shared secret by logging in to the Subscription Settings page, then going to View App Details, and clicking on the Install Settings tab (only accessible by Admins). To use JWT keys to install the Pendo snippet, click Enable:
Key Generation
Next, you'll need to generate a new signing key. To do so, click the Generate Key button located under the snippet section:
Give the key a Description, then click Create:
Note: you can have up to five active keys at a time.
You can edit the description later if you choose. By default the key is hidden - to show the key, click the Show button:
Once you have created the shared secret, instead of calling in with the JSON body of all the metadata, the JWT and the Key ID should be sent. The agent includes that information with events for processing. Pendo will verify that the JWT has not been tampered with and will not process any of the invalid requests or events.
- If “use JWT keys” is enabled, then we will accept either metadata with or without JWT signatures.
- Once “only allow JWT authenticated event data” is enabled, we will only process events that have a verified signed JWT.
- If “use JWT keys” is disabled, we will not accept events with JWT.
To only allow JWT authenticated data, click the Enable button next to this option:
Once selected, you will see a confirmation model. You may not proceed until you confirm this action:
Exchanging and Revoking the JWT Shared Secret
To revoke a previously used JWT shared secret, a new key should be generated on the Install Settings page. Once the new key is properly inserted, the previous key should be revoked.
To revoke a key, click the Revoke Key icon when hovering over the key, then accept the confirmation to revoke the key permanently (this action cannot be undone):
You can find a log of all Revoked Keys underneath the Active Keys section.
Important: If an active key is revoked before updating the snippet with a new key, data will not be processed until the snippet has an active key.