Identity verification stops anyone else from sending or reading Userflow data as one of your users. Your back end signs each user ID (and company ID, if you use Companies) with a Secret Key from Userflow, Userflow.js sends that signature, and Userflow rejects any request without a valid one. We strongly recommend turning it on.
What can happen without identity verification?
Without identity verification, a malicious third party who knows a user's or company's ID could send or read Userflow data as them, and:
Update their attributes in Userflow.
Track events on behalf of them.
Start/dismiss flows, checklists and launchers for them.
Respond to surveys on behalf of them.
Under some circumstances, read the user’s attributes: If any of your content contains user attributes (e.g. a “Hi {name}” message), the third party could start this flow, and then obtain the user’s name from the content displayed.
Some of these risks are mitigated if your user IDs are not publicly accessible and not easily-guessable. If the third party does not know a user’s ID, they can’t impersonate that user. The third party could still pollute your Userflow account by creating users with arbitrary IDs, so we still recommend enforcing identity verification in this case.
Set up identity verification
To set up identity verification, compute a signature on your server, pass it to Userflow.js, and then tell Userflow to reject requests without one.
Step 1: Compute the signature on your server
The signature is generated by computing a SHA-256 HMAC of the user’s ID (the same ID you later give to userflow.identify()) signed with your Userflow environment’s Secret Key. Note that each Userflow environment has a separate Secret Key, so make sure you grab the right one. Find it under Settings → Identity verification in Userflow.
Important: The Userflow Secret Key is a secret! Do not store it in your code repository, include it in your front-end code or otherwise expose it to third parties.
Your programming language probably has an easy way to compute HMAC. Here’s what it looks like in Node.js:
import crypto from 'crypto'
let signature = crypto
.createHmac('sha256', 'USERFLOW_SECRET_KEY')
.update(user.id)
.digest('hex')For PHP, Ruby, Python, and Elixir, see Identity verification signature code for Node.js, PHP, Ruby, Python, and Elixir.
If you’re using Companies, you also need to compute a signature for the companyId (the same ID you later give to userflow.group(companyId)).
Step 2: Pass the signature to Userflow.js
Include the signature (not the secret!) in your Userflow.js snippet (where you run userflow.identify()).
userflow.identify(
// TODO: Replace with real user ID
'USER_ID',
{
// TODO: Add your regular user attributes here
name: 'NAME',
email: 'EMAIL'
},
// Third argument is an options object
{
// TODO: Replace with computed user signature
signature: 'SIGNATURE'
}
)If your app is a “Single-page application”, which gets the user’s ID and other info via an API call, you can include the computed signature in this API response, and add it to your snippet.
If you’re using Companies, you also need to include a signature (based on the companyId, not the user ID) in your userflow.group(companyId) call:
userflow.group(
// TODO: Replace with real company ID
'COMPANY_ID',
{
// TODO: Add your regular company attributes here
name: 'NAME'
},
// Third argument is an options object
{
// TODO: Replace with computed group signature
signature: 'SIGNATURE'
}
)Before you go on to Step 3, check that Userflow.js still works in your app and that the DevTools Console shows no Userflow errors. An error such as “Incorrect user identity verification signature” means a signature is wrong.
Step 3: Turn on Enforce identity verification
In Userflow, go to Settings > Identity verification and turn on Enforce identity verification. From then on, Userflow rejects any Userflow.js request that doesn't carry a correct signature.
Identity verification signature code for Node.js, PHP, Ruby, Python, and Elixir
Each identity verification recipe uses USERFLOW_SECRET_KEY as a placeholder. Replace it with the Secret Key for your Userflow environment, from Settings > Identity verification.
Node.js
import crypto from 'crypto'
let signature = crypto
.createHmac('sha256', 'USERFLOW_SECRET_KEY')
.update(user.id)
.digest('hex')PHP
hash_hmac(
'sha256',
$user->id,
'USERFLOW_SECRET_KEY'
)Ruby
OpenSSL::HMAC.hexdigest(
'sha256',
'USERFLOW_SECRET_KEY',
user.id
)Python
import hashlib
import hmac
message = str(user.id).encode("utf-8")
secret = "USERFLOW_SECRET_KEY".encode("utf-8")
signature = hmac.new(secret, message, digestmod=hashlib.sha256).hexdigest()Elixir
:crypto.mac(:hmac, :sha256, "USERFLOW_SECRET_KEY", user.id)
|> Base.encode16(case: :lower)