Overview

Identity Verification ensures that interactions between you and your users are kept private and that a bad actor can't impersonate your users. In short, if you set up user identification and send critical information to UserGuiding, you should set up and enforce Identity Verification.

Note: If you only use UserGuiding for website visitors who don’t log in, you don't need Identity Verification. It only applies to users for whom you have identifiers like email address or user_id.

What is a User Impersonation Attack?

On workspaces without Identity Verification, it's possible for a bad actor to impersonate a user. This means a bad actor could see a user's historical conversations, appear to your teammates as that user and deceive them into taking actions on that user's account.

For example, without Identity Verification, someone can interact with your UserGuiding materials and spoof the identity of another user, by providing a known identifier like their email address or user_id. This allows an attacker to pose as a real user to your teammates, giving access to previous interactions and potentially sensitive data.

How Does Identity Verification Protect My Account?

With Identity Verification, you generate a unique user hash for each of your users based on their email address or user_id and your account's identity verification secret. Your integration will generate and send these hashes along with every UserGuiding request allowing us to trust that the user request truly came from you.

Here’s how your UserGuiding requests are protected from impersonation when you properly enable Identity Verification for your workspace.

Identity Verification prevents cross-user impersonation on your workspace because, without access to your secret, a third party attempting to spoof a user's identifier to UserGuiding will be unable to send UserGuiding a valid user hash for that user.

Once Identity Verification is enforced, the UserGuiding container will not load or accept requests for logged-in users without a valid user hash.

Does Identity Verification Affect the User Experience?

With Identity Verification correctly set up, there is no impact to your customers. Users will experience the UserGuiding as normal. There is no extra action required from them to authenticate themselves or use UserGuiding materials.

Why Don't You Have One Secret for All Platforms?

We made a unique secret for each platform so it would be easier to rotate each one or enable Identity Verification on each platform independently.

How Do I Generate a Unique Hash per Platform When I Use the Same Backend for All Users?

You shouldn't generate the hash and store it in your database. You should instead generate it and dynamically send it when identifying the user to UserGuiding. This will mean that when you change secrets or the user is using a different platform, you’ll have the correct hash being sent.

If you store the hash and send it, you would have to do a mass regeneration upon any changes to your secret, which would create friction.

How can I Set Up Identity Verification?

1. Enable Identity Verification in the Panel

• Go to the Installation section in your UserGuiding Panel.
• Under User Identification, click the Enable Identity Verification button.
• You’ll be shown your workspace’s unique secret key. This key is used to securely generate the user hash (HMAC) for each logged-in user.
  

⚠️ Important: Keep your secret key safe. Never store it in your frontend code or in any location accessible to third parties.

2. Generate user_hash on Your Server

For each logged-in user, you must generate an HMAC (Hash-based Message Authentication Code) using your secret key and a unique user identifier (like user_id or email).

We support multiple backend languages. You’ll find examples for Node.js, Rails, Django, PHP, Go, and Java in the panel.

3. Identify the User with user_hash

When identifying the user to UserGuiding on your frontend, include the generated HMAC as the user_hash

userGuiding.identify(
  user_id,
  {
     email: "[email protected]",
     user_hash: "user#hash#value"
  }
)

4. Check the Installation

Once you've added the user_hash to your identify call, return to the panel and click Check Installation to verify everything is set up correctly.

Once the check is successful, Identity Verification will be active and enforced on your workspace.

👉 Note: The custom domains you set for your Knowledge Base and Product Updates Pages should be the same domain with your web application, if you are using the Identity Verification method for controlling the Access for your Knowledge Base and Product Updates Pages.