When to set up identity verification
To improve security and prevent impersonation we recommend setting up signed identities if you plan to add Candu to a logged in experience and:
Use Variables and/or
Use Segmentation
Then we highly recommend setting up identity verification. It protects you and your users from having data passed to third parties.
If you plan to use variables, there is a chance that bad actors could impersonate other users to gain access to private information. Identity verification helps ensure that the data stored in variables is kept private. We strongly encourage any Candu clients that plan to use variables to set up and enable identity verification.
How to set up identity verification
You will set up identity verification during installation (although you can always update your script after the initial Candu installation).
In your initial installation, you will need to add an encrypted hash of your user's user_id (HMAC) on the server-side (that you generate on your server using SHA256) that you will pass to your embed installation snippet along with your user’s user_id.
If you choose to set up identity verification, Candu will not store identify calls for any logged-in users without a valid HMAC. In this case, logged in users without a valid HMAC will still see Candu content, and if you are using variables, these users will see the fallback option. This ensures that no information is passed to third parties that might be impersonating your users.
ℹ️ Please note: If you embed Candu outside of the logged-in experience where user traits are anonymous (e.g. on a marketing site or other public-facing URL), then it will not be possible to set up identity verification.
You will find the script in Settings > Installation, and the Workspace's secret key will be in the Signed Identities section of your Settings.
On the server-side, you will need to pass the secret key to generate an HMAC for your app. For example in PHP, it might look something like this. Please note that currently the HMAC must be passed to Candu in base 64:
$hash = hash_hmac(
'sha256', // hash function
'123', // User ID
'3UUohEXcGB2FVWEt79xkwVzwW' // secret key (keep safe!)
);
$encoded = base64_encode(hex2bin($hash));
Once you have generated the HMAC, you can pass that value to the front end along with the userId via the typical installation script tag. If you were using the above secret key, it might look something like this:
<script src="https://cdn.candu.ai/sdk/latest/candu.umd.js"</script>
<script>
Candu.init({
clientToken: "0Xz1x0xzXz",
userId: "123", // User ID
hmac: "pJVItuOtHnVWIdEE6aJ3TdGdiAbWTgUIT/rI34poJQ8=" // HMAC signature for user_id encoded in base646 });
</script>
If you add identity verification after installation, please note that if you turn on Signed Identities in Settings before updating the code, all users will see fallback variables until the code update is complete. Also, please note that if you generate a new secret key, the variables will be cached for a single session and then will show their fallback values for users until you pass the new secret key.
ℹ️ If you enforce Signed Identities before updating your code, all users will see fallback variables and content until the code update is complete.
FAQs and Troubleshooting
The hash must be generated with the same identifier that you're sending to Candu and it must be labelled user_id. If you are using an email or other identifier, you can use that here.
If you just send the user_hash, the identity verification check will fail. You must send the user_id as well.
Your embed code is workspace-specific, so make sure you've set up identity verification on the workspace that is installed on the frontend. If you set up identity verification to test in a sandbox environment, you will need to set it up again when you move to a production installation.
Only workspace Owners and Admins are able to enable/disable Signed Identities.
If you run into any issues setting up identity verification, please contact our support team and we'll be happy to help you.