How to use HMAC with Mutations

What you’ll learn

In this article you’ll learn:

• What HMAC is and why we use it
• How to enable HMAC for your GraphQL mutations
• How to call a mutation with a valid HMAC signature

What is HMAC?

HMAC is a specific type of Message Authentication Code (MAC) involving a cryptographic hash function, a secret key and a range of “arbitrary bits”. In simple terms it works as depicted below:

HMAC relies upon:

• A Cryptographic Hash function. In this example we are using SHA-256
• A Secret Key. In the context of this article we (Marketplacer) provide this to you
  • Refer to the Enabling HMAC section below
• “Arbitrary bits”. In this case we are using the body of the mutation request as the “arbitrary bits” required by HMAC

What results from this is a Hash (or “signature”) that is guaranteed to be unique, it is this value that you will need to attach (as a header) to your mutation calls if you choose to configure HMAC.

Why are we using HMAC?

It should be noted that by default this option is not enabled as we believe the use of an API Key over HTTPS is sufficient in most cases to ensure that your API calls are secure.

We have additionally provided this option (HMAC signing) for those customers who wish to adopt that extra level of security. Enabling HMAC for mutations greatly restricts who can make mutation calls.

Enabling HMAC

To enable and use HMAC with your mutations:

• Login to the Operator Portal with Admin privileges
• Navigate to: Configuration -> Authentication Settings
• Check “Require HMAC signature for all GraphQL mutations”

What about GraphQL Queries?

As the name would suggest, this feature (HMAC for Mutations), is only enabled for GraphQL mutations (i.e. those operations that change data, so create, update and destroy operations). GraphQL queries (read operations) are not covered by this feature and will continue work as usual even if this feature is enabled.

Obtaining your HMAC Key

The next thing that you will need to obtain is the HMAC key required to generate the HMAC Signature or Hash. HMAC Keys are paired with API keys, so in order to use HMAC, you will need to proceed through the API Key generation process. To do so:

• Login to the Operator Portal with Admin privileges
• Navigate to: Configuration -> Marketplacer API Keys
• Fill out a Description, Organization and accept the API License terms

When complete, click “Create” and you will be presented with both your API Key and HMAC Key:

Some points to note about the HMAC Key:

• This key (as with the API Key) is not retrievable subsequent to creation
• The HMAC key is paired to the API Key. So you cannot use this HMAC Key with another API Key
• Following on from the above, you cannot create HMAC Keys independently (i.e outside the API Key generation process)

Store both keys in a secure location for further use.

Making a HMAC Signed Mutation Call

In this final section we are going to perform a simple mutation call and supply a HMAC signature as a header. If this step is not completed then any mutation calls made will fail with an appropriate error.

Step 1: Generate the HMAC Signature / Hash

The first step in making a successful mutation call is to generate the hash or HMAC signature that you will attach to your call. In this article we are going to use a free online tool to perform this function, but in production scenarios it would be the responsibility of the developer to write such a routine.

To generate a valid HMAC Signature you will need:

1. Your HMAC Key
2. The request body of your mutation
3. The SHA-256 Hash Function

1. HMAC Key

This was generated in the previous section, please refer back to this if you are unsure.

2. The Request Body

If we take the following mutation in the Insomnia tool as an example:

Copying the GraphQl mutation text from the above example is not sufficient, we need to work with whatever the exact resulting request body would be. In Insomnia, this can be found in the Timeline tab following the submission of the mutation, see below:

It is this text that we will use to produce our HMAC signature (along with the other components).

Taking these 2 inputs (the HMAC Key and request body) along with the use of the SHA-256 cryptographic function, we can generate the hash / HMAC signature required, (note the output format of the hash should be Base64). To put this in context, if we look at the following tool (javainuse.com/hmac), you’ll see how this fits together:

Step 2: Attach the HMAC Signature to the Mutation Call

The final step is to attach the hash / HMAC signature as a header to the mutation call. The name of the header key must be: Marketplacer-HMAC-256.

As shown below you have to provide both the API Key and the HMAC Key with your request:

Assuming all the required steps have been followed the mutation should continue to work as before. Note, if you choose to disable the HMAC for Mutations feature in the future, continuing to supply the HMAC signature has no effect and is somewhat redundant.