Identity Verification

Introduction

Identity Verification is a security mechanism to protect your Refiner installation from malicious attacks from third parties.

Enabling Identity Verification mitigates the risk of third parties impersonating other users or creating bogus user profiles.

We highly recommend to enable Identify Verification in production environments.

How it works

When Identify Verification is enabled on your Refiner environment, all communications between the your users and our servers need to be signed with a special hash token.

The signature hash token is unique for each user and only you can calculate it using a secret API key.

Communications without a user identifier and a corresponding valid signature will be rejected by our servers.

As valid signature tokens can only be calculated by you, you are effectively preventing third parties from impersonating other users or creating bogus user profiles.

Please note: Identify Verification can only be used if you can provide unique identifiers for each user. When enabled, our Web-Client can’t be operated in Anonymous Mode and all Survey Links need to contain a user identifier.

Enable Identity Verification

Go to SETTINGS > Identity Verification and enable the option for every survey channel where you want to enforce a verification check.

Compute the signature

The signature is a HMAC computed using the SHA-256 hashing functions. The SHA-256 hashing function is natively supported by most programming languages. Below, we’ll list a couple of examples.

Please make sure to replace the SECRET_KEY and the USER_ID in the examples below with the correct values. The SECRET_KEY is unique for each Refiner environment and can be find the environment settings as described above. The USER_ID is the one you’ll later use to identify your users using the identifyUser method.

Important: The secret key is … a secret! Do not include the key in your code repository or expose it in your frontend HTML code at any moment.

import crypto from 'crypto'

let signature = crypto.createHmac('sha256', 'SECRET_KEY').update(USER_ID).digest('hex')

$signature = hash_hmac('sha256', $userId, 'SECRET_KEY')

signature = OpenSSL::HMAC.hexdigest('sha256', 'SECRET_KEY', USER_ID)

For testing purposes, you can keep Identity Verification in your Refiner settings disabled (see above). When disabled, Refiner will validate provided signatures, but also accept requests without a signature.

Using the computed signature

Web-Client

To pass the computed signature to the Refiner Web-Client you can provide a second object to the identifyUser method as shown in our client reference.

If you are using the Google Tag Manager installation method, you can provide the signature as a user trait using “identify_verification_signature” for the field identifier.

Mobile SDK

To pass the computed signature to the Mobile SDK you can provide an additional parameter to the identifyUser method.

Please refer to our the reference for iOS, Android or React-Native platform for detailed instructions.

Survey Links

To pass the computed signature to Survey Links, you can provide it as a signature URL parameter as described in our Survey Link Personalization documentation.