HMAC authentication with external system

DenisG · ‎01-19-2025

Hi,

I am trying to authenticate with ServiceNow using HMAC authentication, following the documentation: Link on Documentation. However, I couldn’t find any information on how to authenticate using an external system (Postman). Does anyone know how to set up request in Postman to authenticate with ServiceNow using HMAC?

Do I need to use a pre-request script in Postman for this? If yes, could you please provide an example.

Also, do I need to set up something from SN side too, if so could you please tell how?

Thanks in advance.

KeerthiFully · ‎03-18-2025

where you able to figure this . Having the same requirement

emaasalmi · ‎05-05-2025

Did you guys manage to get this working? I've configured everything following the steps in the docs, but can't figure out how to test if it's working or not. It would be nice for ServiceNow to provide an example how to test/use this.

_ukasz Rybicki · ‎05-05-2025

Solution Summary

To authenticate external clients (e.g., Postman) against ServiceNow using HMAC, you must first enable and configure ServiceNow’s API Key and HMAC Authentication plugin, create an HMAC Configuration, associate it with an Inbound Authentication Profile, and apply that profile in an API Access Policy for your targeted REST API. In Postman, store your HMAC secret in an environment variable, use a Pre-request Script to compute the HMAC-SHA256 signature (Base64-encoded) over the canonical string {Date}\n{Method}\n{Host}\n{Path}\n{Query} via CryptoJS.HmacSHA256, then include the resulting signature and timestamp headers in your request.

1. ServiceNow Side Configuration

1.1. Activate the API Key & HMAC Plugin

Navigate to System Applications > All Available Applications > All.
Find and Activate the API Key and HMAC Authentication plugin (com.glide.tokenbased_auth) (ServiceNow, ServiceNow).

1.2. Create an HMAC Configuration

Go to System Web Services > API Access Policies > HMAC Configuration.
Click New.
Define:
- Name (e.g. “External HMAC”)
- Hash Algorithm: HMAC SHA-256
- Secret Key: your shared secret
- Encoding: Base64
- Header Name: x-sn-hmac-signature-256 (default for SHA-256) (ServiceNow, ServiceNow).
Submit the record.

1.3. Create an Inbound Authentication Profile

Navigate to System Web Services > API Access Policies > Inbound Authentication Profile.
Click New → Create HMAC authentication profiles.
Give it a Name (e.g. “HMAC External Client”) and in Auth Parameter, select the Auth Header record for your HMAC configuration (it appears as x-sn-hmac-signature-256) (ServiceNow, ServiceNow).
Submit.

1.4. Apply an API Access Policy

Go to System Web Services > API Access Policies > REST API Access Policies.
Click New.
Enter a Name (e.g. “Incident API HMAC”) and select the Table API (or your custom API).
In the Authentication Profiles related list, add your “HMAC External Client” profile.
Submit. (ServiceNow)

2. Postman Setup

2.1. Define Environment Variables

sn_hmac_secret: your shared secret from the HMAC Configuration.
sn_date: to be set dynamically.
sn_signature: to hold the computed signature. (Gist)

2.2. Pre-request Script

In your Postman request’s Pre-request Script tab, paste:

const CryptoJS = require('crypto-js');             // Load CryptoJS library
const date   = new Date().toUTCString();           // RFC 1123 format
pm.environment.set('sn_date', date);               // Save for header

const method = pm.request.method;                  
const host   = pm.request.url.getHost();           
const path   = pm.request.url.getPath();           
const query  = pm.request.url.getQueryString() || '';

const secret    = pm.environment.get('sn_hmac_secret');
const rawString = `${date}\n${method}\n${host}\n${path}\n${query}`;

// Compute HMAC-SHA256 and encode as Base64
const signature = CryptoJS
  .HmacSHA256(rawString, secret)
  .toString(CryptoJS.enc.Base64);

pm.environment.set('sn_signature', signature);

(Gist)

2.3. Add Headers

Under Headers, add:

x-sn-date: {{sn_date}}
x-sn-hmac-signature-256: {{sn_signature}} (ServiceNow)

3. Testing the Integration

In Postman, set your method (e.g. GET) and URL:

https://<instance>.service-now.com/api/now/table/incident

Ensure your Environment is selected (with sn_hmac_secret defined).
Send the request; a 200 OK with JSON payload confirms successful HMAC authentication (ServiceNow).

References

Inbound REST API Keys (Chuck Tomasi, ServiceNow Community) – details enabling API Key & HMAC plugin and creating profiles (ServiceNow).
Configure HMAC – Token-based authentication (ServiceNow Docs) – steps to create HMAC Configuration (ServiceNow, ServiceNow).
API Key and HMAC Authentication for inbound REST APIs (ServiceNow Docs) – conceptual overview of HMAC token in API access policies (ServiceNow).
Using KMF for HMAC Verification (Cheng Chen Liu, ServiceNow Dev Blog) – alternative KMF-based HMAC verification in Scripted REST APIs (developer.servicenow.com).
Postman pre-request script to sign HTTP requests with a HMAC shared secret (asoorm Gist) – example Pre-request Script adapted for use (Gist).

Please review and mark this as the correct answer!

emaasalmi · ‎05-08-2025

Unfortunately, the AI hallucination copy+pasted by the previous poster is not the answer. I don't see much value for these replies as the commenter obviously didn't even test it before posting.

Instead, here's the correct answer found from the KB article KB1768197:

https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB1768197

And here it is as plain text in case the kb is not available in the future:

First, follow the instructions provided in docs for configuring the HMAC on ServiceNow end:

https://www.servicenow.com/docs/bundle/xanadu-platform-security/page/integrate/authentication/concep...

-- Notice that when creating the HMAC authentication profile, the docs example uses the "Query Parameter for HMAC 256", but here we are using "Header for HMAC 256".

Then, test with Postman by following this.

1) Create a new request, ensure it is a POST request to the Table API endpoint of your instance (https://instance.service-now.com/api/now/table/incident).

2) Under Authorization, set it to No Auth (HMAC is the authentication).

3) Under Headers, we will need to create a new key-value pair which contains our Key ID and Signature.
Note: Since we are using the OOB Auth Parameter "Header for HMAC 256", then the header parameter name is "x-sn-hmac-signature-256".

Key: x-sn-hmac-signature-256
Value: KEYID=PutTheKeyIDHere,SIGNATURE={{signature256}}

4) Under Pre-request Script, copy and paste the below script and be sure to replace HMAC_SECRET with your HMAC Shared Secret (refer to Create a HMAC secret).

var body = request.data;
pm.environment.set("signature256", CryptoJS.HmacSHA256(body,"HMAC_SECRET").toString(CryptoJS.enc.Base64));

5) Under Body, construct a payload to test (I selected raw and from the dropdown selected JSON).

{
    "short_description": "HMAC Test Incident",
    "description": "Testing HMAC Authentication"
}

6) Click Send. If everything is configured correctly, you should see a JSON response with information of the newly created incident.

Note: If you are seeing failures, try to clear the cookies in Postman and try again.

Troubleshooting

Create/Update the System Property "glide.auth.debug.enabled" and set value to true.

A successful HMAC Authentication log:

2025-01-08 15:41:05 (577) API_INT-thread-3 SYSTEM txid=92dadd201b8b AuthLog DEBUG: Auth: started authentication using auth profile a49b5c101bc3d2105a7c2f46b04bcb5c
2025-01-08 15:41:05 (584) API_INT-thread-3 SYSTEM txid=92dadd201b8b AuthLog DEBUG: Auth: started preAuth Policy check with profile ID a49b5c101bc3d2105a7c2f46b04bcb5c
2025-01-08 15:41:05 (584) API_INT-thread-3 SYSTEM txid=92dadd201b8b AuthLog DEBUG: Auth: preAuth Policy check completed successfully with profile ID a49b5c101bc3d2105a7c2f46b04bcb5c
2025-01-08 15:41:05 (639) API_INT-thread-3 SYSTEM txid=92dadd201b8b SSI_69c8f906433031103ff6b4202bb8f2e8 DEBUG: Auth: ServletInputStream in wrapper reset by Auth profile HMAC
2025-01-08 15:41:05 (668) API_INT-thread-3 SYSTEM txid=92dadd201b8b AuthLog DEBUG: Auth: started postAuth Policy check with profile ID a49b5c101bc3d2105a7c2f46b04bcb5c
2025-01-08 15:41:05 (670) API_INT-thread-3 SYSTEM txid=92dadd201b8b AuthLog DEBUG: Auth: postAuth Policy check completed successfully with profile ID a49b5c101bc3d2105a7c2f46b04bcb5c
2025-01-08 15:41:05 (673) API_INT-thread-3 SYSTEM txid=92dadd201b8b AuthLog DEBUG: Auth: request header used in authentication: x-sn-hmac-signature-256,len[73]
2025-01-08 15:41:05 (673) API_INT-thread-3 SYSTEM txid=92dadd201b8b HTTPAuthSessionSetup HTTP authorization validated user 'abel.tuter'
2025-01-08 15:41:05 (673) API_INT-thread-3 SYSTEM txid=92dadd201b8b Sessions Session user set to abel.tuter