Note: this is being rolled out to new customers, and slowly to existing customers. We want to make sure that everything goes smoothly for existing customers as they switch to this installation method and will communicate once this is out of beta and fully available. If you are interested in joining the beta then please email us here.

Context

What is Identity Verification?

Identify Verification enforces two simple rules

  1. Requests to Chameleon must have only originated from your application.
  2. Data sent to Chameleon cannot be obtained by another party.

It works by providing a way for Chameleon to verify the authenticity of requests made to our APIs (via a digital signature).


Although this is optional, we encourage all Chameleon customers to enable secure Identify Verification.

How does Identity Verification work?

Identity Verification works because the "signature" you generate (when sending data to Chameleon) can only have been generated by you.

The code snippet you install in your web app, and the user ID you send are not private. Therefore we provide you with a secret with which you generate a verification hash, which we check. Only you can generate this hash, which validates that no third-party is sending us a request.

Additionally, we ask that you include the current timestamp when the token was generated so that we can reject requests that are too old, or being replayed back to us, and so that we can rotate your key.

How does this affect my end-users?

Your users' data will be more secure since one user cannot "act as" another.

It does not impact end-user experience or performance in any way. Your end-users will not notice that identity verification is on/off unless they attempt to download their or another user's data via browser console.

Rollout planning

Identity Verification is turned on and enforced when the first verified request is received. This means that if the uid_hash being sent does not verify, Identity Verification will fail and not be enabled for your account.

Once we receive any secured data from any page where your account's Chameleon token is used, all un-verified data (sent without the signature) will be ignored by Chameleon. This means that users identified without the verification hash will not see any Chameleon Experiences until they are securely identified.

New Customers

If you are installing Chameleon for the first time then we strongly recommend you use this method from the beginning, if you are installing via JS.

Support for Identity Verification via Segment.com is not available yet as it requires a longer process in engaging the Segment team, so we will keep working on this and announce when/if it becomes available in future.

Existing Customers

If you are making a switch from sending unsecured data to secured data, then we recommend deploying this change to production first, to enable a smooth roll-out to your users.

An alternative path is to deploy to your staging environment in off-hours and then to production as soon as possible. During the period between first verification on staging and verification on production, no Chameleon Experiences will be shown to end-users in your production environment.

Note: once you enable Identity Verification, all REST API requests must use your Secret API key (found at the bottom of this page) and not your account token (identifier in the installed Chameleon code snippet). Any requests using your account token will be ignored.

Setup

How do I enable Identity verification?

Note: this is only available to certain accounts. Please email us to get access.

To do this, visit the Chameleon installation page in your web dashboard. This is only currently available to those installing via JS, so select this installation method:

Below the code snippet, you will see the "Identity Verification" section where you can find your secret key.

During the beta, we will send you your secure key and ask you for an example uid and uid_hash to verify in order to make sure the deployment goes smoothly.

⚠️ This key should not be shared with anyone outside authorized users within your account. If a third-party had access to this key, this secure method would be compromised.

This key is used to generate SHA256 HAMC signatures that are sent alongside User ID. This is a small addition to the installation.

We have provided examples of how to do this for a range of languages, including Javascript, Ruby, Python and others in the following Github repo:

How do I know if everything is working?

You can test any domain you have installed Chameleon on and verify that secure data is being received. Do this from the same Install page:

Unverified requests after verification is enabled will return a 401 error HTTP response.

Troubleshooting / FAQ

When is Identity Verification enabled?

Upon receiving your first verified request, verification is turned on and enforced.

Can I turn off Identity Verification?

You cannot turn off Identity Verification once you have started sending us secure data.

Will it work if I have multiple user accounts for testing my application?

Short answer is yes. Longer answer is that because your backend generates this signature, when you login as a different user, your system will send a signature corresponding to the different user.

Possible reasons for failure

  • Are you sending a User ID along with the uid_hash? If you just send the uid_hash without the uid or just the uid once verification is on, Identity Verification check will fail (401 HTTP error code)
  • Are you sending the current timestamp inside and outside the signature? The current timestamp is required to be transmitted at the end of the signature and to have also been part of the signature. Refer to the code samples for language-specific instructions. Without this timestamp value signatures are valid in perpetuity.
  • Are you using the correct Identity Verification secret? You need to use the Verification key provided. This is different to the token in your installation code snippet or other API keys. Making up a key will also not work.
  • Is this the latest version of your code? If this is an older version of your app, or your JavaScript code is cached you might not be sending a uid_hash with your user data in which case the check might also fail.

If you’re still having trouble with Identity Verification, please email us and we’ll be happy to take a look!

Did this answer your question?