How to: Set Up HMAC (Hashed Key) Authentication

Overview

3rd-party APIs (application programming interfaces) might require you to pass a hashed value as part of the API call. These hashed values help to authenticate the API request. This type of authentication is called HMAC authentication, or hashed key authentication. In this article, you'll explore the basic configuration involved in using HMAC authentication. You'll start by learning how to set up an HMAC service. Then, you'll see how to use the Unqork internal service called Create Hash of Passed String. This internal service returns a hashed value, using the details provided in your HMAC authentication service.

This article covers the basic steps involved in using HMAC authentication. Configuration details vary depending on what API you're communicating with.

What You'll Learn

In this how-to guide, you’ll learn how to set up the HMAC Authentication service and create hashed strings in a module.

What You Need

For this module, you'll need:

• 1 Initializer component
• 2 Hidden components
• 1 Plug-In component

These instructions assume you have an open module saved with a title.

Preconfiguration

Set Up the HMAC Authentication Service

The first step is setting up the HMAC authentication service under Services Administration.

1.

At the top right of the Unqork Designer Platform, click the Settings drop-down.

2.

Click Administration.

3.

Under Integration, select Services Administration.

4.

In the Service Title field, enter a title for your service. For example, HMAC Authentication.

5.

In the Service Name field, enter a name for your service. For example, HMAC-authentication.

6.

From the Type of Authentication drop-down, select HMAC.

7.

In the HMAC Private Key (Armored) field, enter the HMAC key.

8.

Click Add Service.

9.

Click OK at the confirmation modal.

Enable Server-Side Execute Only

It's best practice to enable the Server Side Execution Only toggle for modules making API calls. So, let's start there.

This step is optional but can help secure modules that deal with sensitive data or logic.

1.

On the Module Builder header, click the elispsis (...) button. A modal displays.

2.

Click Settings. The Settings menu displays.

3.

Set the Server Side Execution Only toggle to ON.

4.

Click Save.

Configure the Authentication Module

Now you're ready to set up the module that creates the hashed value. Here's how the final configuration looks in the Module Builder:

Configure the Hidden Components

Set up the 2 Hidden components. The first Hidden component stores the value to pass during the Create Hash of Passed String API call. The second Hidden component stores the returned hashed value.

You'll notice this configuration doesn't include defining or passing a value to the valueToPass Hidden component. The value varies based on the API's requirements. Here, the valueToPass Hidden component acts as a placeholder. When applying these steps to your use case, remember to pass or define the string you want to use in the Create Hash of Passed String API call.

1.

Drag and drop 2 Hidden components onto your canvas.

2.

Complete the Property ID and Canvas Label Text fields as follows:

3.

Save each component as you add it.

Configure the Initializer Component

Here, you'll set up an Initializer to trigger the Plug-In component you'll create next. The Plug-In runs the Create Hash of Passed String API call.

If your module already has a component that can trigger the Plug-In, you can skip this step.

1.

Drag and drop an Initializer component onto your canvas.

2.

In the Property ID and Canvas Label Text fields, enter initPluginCreateHash.

3.

Select New Submission as the Trigger Type.

4.

Complete the Outputs table as follows:

5.

Click Save.

Configure the First Plug-In Component

This Plug-In creates your hashed value using the Create Hash of Passed String internal service. To complete the Plug-In's Inputs table, you'll need a few details:

• The Property ID of the component storing the string you want to pass. In this configuration, it's valueToPass. This value maps to the string parameter.
• The type of hash function the HMAC authentication uses. For example, supported algorithms are SHA-256 and SHA-512. The default algorithm is SHA-256. This value maps to the algo parameter.
• The type of encoding the returned hashed value uses. For example, supported values are Base64 or Hex. The default value is Hex. This value maps to the encoding parameter.
• The Service Name of your HMAC authentication service. Be sure to use the Service Name, not the Service Title. This value maps to the hmacServiceName parameter.

You might want to review the documentation for the Create Hash of Passed String endpoint. To do so, click the Learn More link below the Plug-In's Internal Services drop-down. The environment-specific API documentation opens in a new tab. For example: https://training.unqork.io/#/apidocs?hash=tag%2FEncryption%2Fpaths%2F~1system~1hashString%2Fpost.

1.

Drag and drop a Plug-In component onto the canvas.

2.

In the Property ID and Canvas Label Text fields, enter pluginCreateHash.

3.

From the Internal Services drop-down, select Create Hash of Passed String.

4.

Complete the Inputs table as follows:

5.

Complete the Outputs table as follows:

6.

Click Save.

Now you have a hashed value that you can pass in an API call, stored in the hashedValue Hidden component. The details of how you'll pass that value vary based on what API you're communicating with. For example, whether the value should be part of the Request Header or not, and even what the mapping should be. You can check the API's documentation for details. Now you're ready to use HMAC authentication in your application.

Resources

• Services Administration

• Server-Side Module Execution

• Security Best Practices for Sensitive Data