If you would like to evaluate Guides and Surveys, please reach out to a member of your account team or fill out this form to be connected with a Fullstory team member.
Who can use this feature?
- Part of Guides and Surveys, an add-on for Business, Advanced, and Enterprise plans.
- Requires an Admin role to configure. If you don't see this functionality, reach out to an Admin within your organization.
Guides and Surveys is in active development. Product functionality and documentation may change without notice.
User Identity Verification lets you require that Guides and Surveys accept a user's identity only when your server has signed it. Without verification, Guides and Surveys accepts the user ID that the page sends, so a user ID changed in the browser could be used to load or save another user's guide progress and survey data. With verification on, guide progress and survey data for identified users are loaded and saved only for requests that carry a valid token from your server.
Verification is optional and recommended. Setting it up takes an Admin, who generates the secret key and manages verification in settings, and a developer, who signs tokens on your server.
Developers: This article covers the settings an Admin manages. Before you write any signing code, read Signing a User Token in the developer guide. Fullstory rejects any token that doesn't meet every requirement listed there.
This article will cover the following:
- Before you begin
- How verification works
- Set up User Identity Verification
- Testing mode reminders
- Rotate or replace a secret key
- Turn off User Identity Verification
Before you begin
Confirm the following before you start setup:
- Admin role: Only an Admin can generate or delete secret keys, activate enforcement, or turn off verification. Users with the Architect role can open the Guides and Surveys settings page, but the controls on the User Identity Verification card are disabled for them.
- A developer: Someone who can change your server code must sign a token for each signed-in user and add it to your pages. Before writing any code, the developer needs to read the token requirements in Signing a User Token. The same developer guide has signing samples and troubleshooting.
- Reminder recipients: While your org is in testing mode, Fullstory sends reminder emails to every recipient listed for Product Updates Requiring User Action in Settings > Account Management > Notifications. To check or change the recipients, see Product and service notifications.
How verification works
Verification applies only to identified users. A visitor is identified when your site sends Guides and Surveys a user ID, either through FS('setIdentity') or window.usetifulTags.userId, or when the page sends a token. Visitors with no user ID and no token are not affected by verification at any stage.
Your server signs a short-lived token for each signed-in user with a secret key that an Admin generates in Fullstory, and your page passes that token to Guides and Surveys. Your org is in one of three stages. The labels on the User Identity Verification card match these stages. Until a secret key exists, the card shows a Set up Identity Verification button or a toggle that reads In setup. Both are the same stage, and tokens are not checked. After a key exists, the toggle reads In testing mode or On, where On is enforcement.
| Stage | What happens |
|---|---|
| User Identity Verification not set up | No secret key has been generated. Tokens are not checked. |
| In testing mode | Testing mode starts when you generate your first secret key. A valid token is accepted, and an invalid or expired token is rejected. An identified user whose page sends no token is still allowed, so you can roll out tokens without breaking guides and surveys. |
| Enforcement on | Identified users need a valid token. Without one, guides and surveys do not load or save for them. |
In testing mode and when verification is on, the user ID in a valid token replaces any other user ID the page sends. For how each type of request is handled at each stage, see How Verification Works in the developer guide.
Set up User Identity Verification
Setup has three steps: an Admin generates a secret key, a developer implements and tests token signing while your org is in testing mode, and an Admin activates enforcement.
Step 1: Generate a secret key
- Within Fullstory, navigate to Settings > Account Management > Guides and Surveys.
- On the User Identity Verification card, click Set up Identity Verification.
- Click New Secret Key.
- In the Download Secret Key dialog, click Download to save the key as
fullstory-secret-key.pem, or click Copy to copy it. - Store the key in a secure location, such as your secret manager.
- Click Close.
Important: The secret key is shown only once. Fullstory stores only the matching public key. If you close the dialog or reload the page before you download or copy the key, the key can't be recovered, and you need to generate a new one.
Generating your first key turns on testing mode, and the toggle in the card header changes to In testing mode. Your org can have up to two active keys at a time. A second key is used when you rotate or replace a secret key.
Step 2: Implement and test
In this step, a developer adds token signing to your server and tests it while your org is in testing mode.
Developers: Read the token requirements before you write signing code. Signing a User Token in the developer guide lists the required claims, the signing algorithm, the time format, and the maximum token lifetime. A token that misses any one of these is rejected, and guides and surveys do not load for that user. This applies in testing mode too, not only after enforcement is active.
- Give the secret key to the developer through a secure channel, such as your secret manager, along with a link to the Secure User Identity Verification developer guide.
- The developer reads Signing a User Token and implements signing on your server so that every token meets each requirement. The signing samples on the User Identity Verification card are the same as the ones in the developer guide. If the developer changes a sample, they need to check it against the requirements again.
- The developer sets the signed token as
window.usetifulTags.userTokenbefore the Guides and Surveys snippet loads, on every page rendered for a signed-in user, as described in Sending the Token. - To check a token, click Test Your Token on the User Identity Verification card and paste a token signed by your server. The token is sent to Fullstory, and the result shows which requirement, if any, the token fails. The button is disabled until your org has a secret key.
- Sign in to your site and confirm that guides and surveys load, and that requests to
/api/getand/api/savereturn 200, as described in Testing a Token.
Note: Test Your Token uses the same rules as requests from your site. A token that passes isn't rejected later because of its claims or its timing, as long as you use it before it expires. For a valid token, the tester can also show a warning without rejecting the token. It warns when the expiration time looks like milliseconds, and it warns when the token is valid for more than 24 hours.
Step 3: Activate enforcement
When enforcement is on, every request for an identified user must include a valid token. Requests without a valid token are rejected with a 403 error, and guides and surveys do not load or save for that user. Invalid tokens are already rejected in testing mode, so the change at enforcement is that identified users whose page sends no token are rejected too. Visitors with no user ID and no token are not affected.
Before you activate enforcement, confirm the following:
- Your developer has checked your signing code against every requirement in Signing a User Token.
- Every page where users are identified sets
window.usetifulTags.userToken. - While your org is in testing mode, requests from your site to
/api/getand/api/savereturn 200, not 403. Test Your Token doesn't show that the page sends the token. - The token lifetime covers how long a page stays open, or your app issues a new token before the old one expires. See Token Lifetime and Re-issuing.
- The secret key is stored in a secure location, such as your secret manager.
- Your team knows that the way to roll back is to turn off User Identity Verification, which deletes every secret key.
To activate enforcement:
- Within Fullstory, navigate to Settings > Account Management > Guides and Surveys.
- On the User Identity Verification card, go to the Activate Enforcement step and click Activate Verification Enforcement. The button is available only while your org is in testing mode, and only to Admins.
- In the Activate Enforcement dialog, review the warning and click Activate Enforcement.
Important: The dialog warns: "Once enforced, any user identity not signed by a valid token will be refused and will lead to Guides and Surveys not being displayed. Enable only after the implementation was tested."
After you activate enforcement, the toggle in the card header changes to On. You can't move from enforcement back to testing mode. If you need to roll back, see Turn off User Identity Verification.
Testing mode reminders
Testing mode has no time limit, but identified users whose page sends no token are still allowed until you activate enforcement. To keep setup from stalling, Fullstory sends a reminder email 14 days after testing mode starts, and every 14 days after that while your org remains in testing mode.
The reminder goes to every recipient listed for Product Updates Requiring User Action in Settings > Account Management > Notifications. If no one is listed, no reminder is sent. The subject is "Action needed: Guides and Surveys identity verification is not enforced," and the FINISH SETUP button in the email opens the Guides and Surveys settings page, where you can activate enforcement.
Rotate or replace a secret key
Your org can have up to two active secret keys. Fullstory accepts a token signed with either key, and there is no deadline for removing the old one, so you can switch your server to a new key without interrupting guides and surveys. While two keys are active, the card shows a warning that more than one active secret increases risk. Delete the old key once your server no longer uses it.
To rotate a secret key:
- Within Fullstory, navigate to Settings > Account Management > Guides and Surveys.
- On the User Identity Verification card, click New Secret Key. If your org already has two keys, New Secret Key is disabled. Delete a key that your server no longer uses first.
- In the Download Secret Key dialog, click Download or Copy, store the new key in a secure location, and click Close.
- Switch your server to sign tokens with the new key.
- Confirm that requests from your production site signed with the new key are accepted. Keep signing with the previous key until they are.
- In the list of keys on the card, find the old key by its hint and creation date. The hint shows the first three and last four characters of the key body in the
.pemfile, for exampleMII****FsY=. - Delete the old key, and click Delete to confirm.
Important notes about rotating keys:
- Create the new key first: If you delete your only key, the confirmation button is Delete and Deactivate. Confirming it turns off User Identity Verification, in testing mode or with enforcement on. Always generate the new key before you delete the old one.
- New keys: A new key normally takes effect immediately. In rare cases, a new key can be rejected for up to 24 hours. Keep signing with the previous key until requests signed with the new key are accepted.
- Deleted keys: A deleted key is normally rejected immediately. In rare cases, a deleted key can still be accepted for up to 24 hours.
Replace a lost or exposed key
If a secret key is lost or exposed, replace it by following the same rotation steps: generate a new key, switch your server to it, then delete the old key. Don't turn off User Identity Verification to replace a key. Turning it off deletes every key and, if enforcement is on, removes that protection until you set up verification again.
Turn off User Identity Verification
To turn off verification, use the toggle in the header of the User Identity Verification card. There is no separate deactivate button. Turning off verification deletes every secret key and returns your org to In setup, where tokens are not checked.
- Within Fullstory, navigate to Settings > Account Management > Guides and Surveys.
- On the User Identity Verification card, turn off the toggle in the card header. The toggle reads In testing mode or On.
- Confirm in the dialog that opens:
- In testing mode, the dialog is Deactivate Testing Mode. Click Deactivate.
- With enforcement on, the dialog is Deactivate User Identity Verification. Click Deactivate Identity Verification.
Deleting your only secret key with Delete and Deactivate has the same result.
Note: You can't move from enforcement back to testing mode. To return to testing mode, turn off verification, then generate a new secret key, which starts testing mode again. Switch your server to the new key, because tokens signed with a deleted key are rejected once testing mode starts.
If identified users get 403 errors, see Troubleshooting in the developer guide.