Security Settings

Unlayer allows developers to enforce Identity Verification to enhance the security of the embedded builder. By verifying the identity of the users interacting with the builder, you can prevent unauthorized third parties from impersonating your logged-in users and misusing the builder. This feature is especially important for ensuring that only authenticated users have access to the builder.

We strongly recommend that you enforce identity verification to protect your application and users.

Prerequisites

In order to enable enhanced security and identity verification, you must set up the following first:

• End-User Identification

Setup Identity Verification

To set up identity verification, you’ll need to generate a secure HMAC (Hash-based Message Authentication Code) signature on your server for each logged-in user. This HMAC signature is then passed to Unlayer along with the user’s information when initializing the editor.

Sending User Object with HMAC Signature

When initializing the Unlayer builder, you need to pass a user object that includes:

• A unique id for the logged-in user
• A securely generated signature (HMAC)
• Optional information such as name and email for the user

Here’s an example of how to initialize the builder with a user object:

unlayer.init({
  user: {
    id: 1,                                // The user's unique ID
    signature: 'XXX',                     // HMAC signature generated on the server
    name: 'John Doe',                     // Optional user name
    email: '[email protected]',           // Optional user email
  }
});

Generating the HMAC Signature

To ensure security, the HMAC signature must be generated on your server using a secret key. The secret key must never be exposed in client-side code or shared publicly. Here’s how to generate the signature using Node.js and the crypto module:

🚧

Project Secret

Your Project Secret is a sensitive piece of information that should never be exposed in your client-side code, repositories, or any place where it could be accessed by third parties. Always store it securely on your server and limit access to it.

const crypto = require('crypto');

const signature = crypto
	.createHmac("sha256", "[PROJECT-SECRET]") // secret key (keep safe!)
	.update("[USER-ID]")
	.digest("hex");

require 'openssl'

OpenSSL::HMAC.hexdigest(
  'sha256', # hash function
  '[PROJECT-SECRET]', # secret key (keep safe!)
  '[USER-ID]' # user's id
)

hash_hmac(
  'sha256', // hash function
  $user->id, // user's id
  '[PROJECT-SECRET]' // secret key (keep safe!)
);

import hmac
import hashlib

hmac.new(
  b'[PROJECT-SECRET]', # secret key (keep safe!)
  bytes(request.user.id, encoding='utf-8'), # user's id
  digestmod=hashlib.sha256 # hash function
).hexdigest()

You can get your project secret from project settings in the Unlayer console.

Explanation

• [PROJECT-SECRET]: This is your project-specific secret key. It must be kept secure and never exposed to the public or in your client-side code.
• [USER-ID]: This is the unique ID for the user (for example, id: 1 in the user object).
• The resulting HMAC signature is a cryptographic hash that verifies the identity of the user when passed to Unlayer during initialization.

Why Use Identity Verification?

• Prevent Impersonation: Without identity verification, third parties could potentially impersonate your logged-in users and access or modify content in the editor. By requiring a valid HMAC signature, you ensure that only authorized users can interact with the Unlayer editor.
• Enhanced Security: This feature ensures that your users’ actions in the builder are authenticated and protected from potential tampering.

Example Workflow

1. User logs in to your application.
2. On the server, you generate an HMAC signature using the user’s unique ID and your secret key.
3. Initialize the Unlayer builder with the user object containing the user’s ID and the generated HMAC signature.
4. Unlayer verifies the signature and ensures that the user accessing the editor is authenticated.

Notes

• Do not commit your secret key to any public repositories or client-side code.
• Always generate the HMAC signature server-side to prevent exposure of your secret key.
• Identity verification only affects users interacting with the Unlayer builder within your application, ensuring they are properly authenticated.