What is Identity Verification and how it works?

Identity Verification is a security measure that ensures conversations between you and your users are kept private and prevents unauthorized users from impersonating your genuine users. In the context of a Messenger integration, identity verification is strongly recommended for maintaining user privacy and data integrity.

Do I need Identity Verification?

The need for Identity Verification significantly depends on the nature of your operations and your user base. If your Gist Messenger setup involves a logged-in user integration, setting up and enforcing Identity Verification is highly recommended.

In workspaces without Identity Verification, it’s possible for a malicious user to impersonate a genuine user. This can lead to unauthorized access to historical conversations, misrepresenting the attacker as the user to your team, and deception leading to unwanted actions on the user’s account.

How it works?

Identity Verification uses a unique user hash generated for each of your users based on their email address or user_id and your workspace’s identity verification secret. This hash is sent along with every identify request, validating the authenticity of the user request.

Without access to your secret, a third-party trying to spoof a user's identifier will be unable to send a valid user hash, preventing cross-user impersonation on your workspace.

Consider a situation where Mike has made a purchase on your e-commerce store. However, he realizes he has entered an incorrect shipping address and wants to correct it before the order is shipped.

In this scenario, you receive a support request from "Mike" for an address change. But how can you verify if the person contacting you via live chat as "Mike" is indeed the person who has made the purchase? This is where Identity Verification comes into play.

Case 1: The real Mike contacts you

1. Mike logs in to his account on your e-commerce website using his email address, mike@yourdomain.com.
2. Upon login, your backend signs Mike’s email with the Identity Verification key that both Gist and your backend know, returning the hash to Mike's browser.
3. Mike's browser, after login, makes the gist.identify call with his user_id, email address, and user_hash.
4. Mike then sends a message to your support team through Gist Messenger on your website, requesting the shipping address change.
5. In your Gist Inbox, you see the conversation with a green checkmark next to Mike's email address, confirming that Mike's email address is verified. Thus, you can be assured that the request is genuinely from Mike (as long as Mike's account credentials have not been stolen by someone else).
6. With this assurance, you can proceed to address Mike's request.

Case 2: An impostor tries to impersonate Mike

1. The impostor visits your e-commerce website and attempts to set mike@yourdomain.com as their email by calling the gist.identify method (using Gist’s JavaScript SDK). However, they cannot sign the email since they don't have access to your Identity Verification key.
2. The impostor sends a message to your support requesting a shipping address change.
3. Unfortunately for the impostor, you notice that mike@yourdomain.com was not verified. This raises suspicion, and you can request additional personal identification information to confirm the user's identity.

In both these cases, Identity Verification provides an additional layer of security, ensuring the person you're communicating with is indeed the individual they claim to be. This system is critical to prevent potential user impersonation attacks, protect users' data and ensure a secure communication environment.

Setting Up Identity Verification

Setting up Identity Verification involves technical changes to your Gist Messenger installation and most often requires access to server-side code.

Step 1: Generate and Send Hashes for Your Users

Begin by generating hashes for your users using your Identity Verification secret. Go to the Settings > Tracking & Events > Security page in your Gist workspace to get code examples for generating user hashes.

When sending user hashes along with user requests, include the identifier that was hashed. Below is a sample request where the workspace created the hash on the user_id value.

OpenSSL::HMAC.hexdigest(
  'sha256', # hash function
  'Z8Oy16MS9Jed2OZS6ofgNb4YprIiazpxOSewXLOvjpLISjxWLFnIvQ==', # secret key (keep safe!)
  current_user.id.to_s # user's id
)

Step 2: Verify Your Installation

After setting up Identity Verification and sending the user_hash for each user, ensure that the installation works as expected.

Log into your App and initiate a chat conversation through the Gist Messenger. In your Gist Inbox, you should see a green tick mark next to your name. This means the verification is working properly.

Step 3: Enforce Identity Verification

Once your signed-in user installation is set up with the correct user hash, enforce Identity Verification in your Gist settings. For Gist installations with the WordPress app, you can enable Identity Verification in your Plugin settings without additional configuration.

How to Turn Off Identity Verification

You can disable Identity Verification anytime by navigating to Settings > Tracking & Events > Security page and turning off the 'Enforce Identity Verification' setting. However, note that your app will be unprotected during this period.

Rotating Your Identity Verification Secret

As of now, you cannot rotate your secret from inside your workspace. If you need to rotate your secret, contact our support team on Messenger for assistance.