Liminal supports HMAC authentication on top of IP whitelist security using a trusted SecureAPI app. It ensures that only authorised applications from trusted networks can access Liminal Express APIs, protecting against credential theft and unauthorised access.

You can add an enhanced layer of security using HMAC authentication with a secret key after you have whitelisted the Source IP and Express Server IP addresses of your environment’s API key. The HMAC authentication enforces protection against:

• IP spoofing by validating the Source and Express IP addresses using the HMAC signature.
• Replay attacks using timestamps (x-timestamp), ensuring signatures cannot be reused.
• HMAC signature validation ensures only trusted clients can access headers.

How HMAC secures whitelisted IPs

Hash-based message authentication code (HMAC) is a cryptographic authentication method that generates a signature using a hash function (in this case, SHA-256) and a secret key. The signature ensures the authenticity of the message payload, ensuring whitelisted IP addresses are authorised.

The HMAC secret is generated and added to the client’s server-side Liminal Express SDK environment variables. Owners and Admins can configure the HMAC secret in the following ways:

1. Liminal Vaults account, and
2. The environment variable file (.env) of your Liminal Express SDK.

The HMAC signature is applied to the following values:

Configure HMAC secret

The HMAC secret must be set up for the whitelisted Origin IP and Express IP addresses associated with your API key. It should be added to the client’s SDK environment variables and your Liminal Vaults account.

1. Add HMAC_SECRET to your sandbox (development) environment:
   1. Follow Step 1: For the Development Environment,
   2. Step 2: Update Docker Image
   3. Step 3: Add key to Liminal Vaults to add it in Vaults.
2. Add HMAC_SECRET to your production environment:
   1. Follow Step 1 - For Production Environment, and
   2. Step 2: Update Docker Image
   3. Step 3: Add key to Liminal Vaults to add it in Vaults.

Required Parameters

Prerequisites

1. You need to have at least one Source IP and Express IP whitelisted for your environment’s API key to implement HMAC authentication.
2. Ensure you have the latest version of the Liminal Express SDK.
3. You have an active API key on Vaults. Learn how to create one here.

Step 1: Generate the HMAC secret key

Generate and deploy the HMAC secret in your environment. Ensure that you use the correct HMAC secret key format. It is a String of 20-64 Alphanumeric characters only.

For Development Environment

The Liminal Express development environment is shared across users. Please use the following test HMAC_SECRET value in Vaults when working in this environment.

testhmacsecret123456

Check out the Liminal Express API changelog for the latest development version.

For Production Environment

Generate the HMAC secret key: Contact your deployment team to assist in generating the key.

👍

Tip

• Ensure you do not expose the HMAC_SECRET in logs, public repositories, or client-side code.
• Contact Liminal Support for any assistance.

Step 2: Update Docker Image

Depending on your Liminal Express deployment configuration, follow the steps listed in the respective column:

Step 3: Add key to Liminal Vaults

Add the HMAC secret key to your Liminal Vaults account.

1. Log in to your Liminal Vaults account.

2. Navigate to Apps from the left navigation bar.

3. Click View in the SecureAPI section.

   

4. Enter the HMAC secret and click Save.

   

   The pop-up message confirms the action. Close and continue.

📘

Note

The HMAC secret must be entered both in the Liminal Vaults web app and your Liminal Express SDK’s API keys.

You have successfully enhanced the security of your whitelisted Origin IP and Express IP configured in your active API key using HMAC authentication.