Encoding UIDs is a feature that you can leverage when installing Chameleon to ensure better security and prevent unauthorized third parties from accessing your user data. Although optional, we encourage all our customers to Encode their user IDs.
ℹ This feature is fully available to new customers. However, for existing customers, to make sure migrating to this method goes smoothly, please email us if you're interested in transitioning to Secure Identity Verification.
Availability & Usage
🔐 Available for all plans
📍 For safer data syncs when installing via Twilio Segment, npm, JavaScript
⚙️ Configure from the Dashboard
How does Encoding UIDs work in Chameleon?
Chameleon uses an identity verification method to ensure no unauthorized third parties can access your data. Encoding UIDs works by ensuring that 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.
The Encoding process enforces two simple rules:
Requests to Chameleon must have only originated from your application.
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).
The code snippet you install in your web app - and the user ID you send are not private. We provide you with a secret key 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?
Encoding UIDs 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 the browser console.
Your users' data will be more secure since one user cannot "act as" another.
Setup
To Encode your UIDs visit the Chameleon installation page in your Dashboard and select your preferred installation method:
With Twilio Segment, npm, or the JavaScript method, you'll find the option to add Encoding UIDs to your code (either by toggling it on or within a separate code block on the page).
From the dropdown, pick your server-side language
Copy the Secret Key and include it in the generated code -- this key is used to generate a SHA256 HMAC signature to send alongside the User ID as part of the code installation.
👉 See more examples of how to do this for a range of languages, including Javascript, Ruby, and Python:
ℹ Don't share or expose your Secret Key in any way. When using within your backend, we suggest you store this as an environment variable to avoid exposing the key.
ℹ If you believe a third party has gained access, the security of your user data can be compromised, so please contact us to rotate your secret key.
How does the Chameleon installation change?
Add the uid_hash into the call to chmln.identify.
When using plain JavaScript:
chmln.identify(USER_ID, { uid_hash: USER_ID_HASH_FROM_BACKEND });
When using Twilio Segment:
// Send uid_hash *only* to Chameleon
//
analytics.identify(USER_ID, OPTIONS, { Chameleon: { uid_hash: USER_ID_HASH_FROM_BACKEND } });
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. You can do so from the Installation section of your Chameleon Dashboard.
ℹ If you install Chameleon on a domain that's different from your email domain, it will be automatically disabled, and you should manually enable it in your Environments, or during the last step of your installation. The same goes for new subdomains that you add to already-enabled domains.
Encoding is enforced when the first verified request is received. This means that if the uid_hash being sent does not verify, Encoding UIDs 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 and will return a 401 error HTTP response.
This means that users identified without the verification hash will not see any Chameleon Experiences until they are securely identified.
You can also test your Encoding from the Dashboard, by pressing the "Test Enconding" button. In the modal that opens, you can add an example UID and its hashed version to verify that this is working correctly.
Adding Encoding UIDs to an existing installation
If you are switching from sending unsecured data to securing your user 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.
ℹ Once you Encode your User IDs, all REST API requests must use your Secret API key found on the installation page and not your account token (identifier in the installed Chameleon code snippet). Any requests using your account token will be ignored (401 error response).
FAQ and Troubleshooting
When is Encoding enabled?
When is Encoding enabled?
When Chameleon receives your first verified request, identity verification is turned on and enforced.
Can I disable UID Encoding?
Can I disable UID Encoding?
You cannot turn off Encoding UIDs once you have started sending us secure data. Contact us if you need to disable it.
Will it work if I have multiple user accounts for testing my application?
Will it work if I have multiple user accounts for testing my application?
The short answer is yes. But because your backend generates this signature, when you login as a different user, your system will send a signature corresponding to the different user.
Can I have rotating secret keys?
Can I have rotating secret keys?
Yes! We're so glad you asked. We can generate a new key for you when you request it and it'll show up on your installation page. We'll leave both keys enabled while you switch them, then just contact us and we'll remove the old one.
Possible reasons for failure
Are you sending a User ID along with the
uid_hash? If you just send theuid_hashwithout theuidor just theuidonce verification is on, the 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 Secret Key? You need to use the Secret Key provided on the Installation page under the Encode UID option. This is different from 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_hashwith your user data in which case the check might also fail.
👉 Still having trouble Encoding your UIDs? Please email us and we’ll be happy to take a look!