Consuming AWS REST APIs from webMethods

Knowledge base
, , , , , , ,
1

The webMethods package “AWSSignature” was implemented on webMethods Integration Server version: 10.5. However, the code should work on earlier and the latest releases.

Introduction

AWS provides REST APIs for programmatic access to the services (S3, SQS, EC2, Lambda, IAM, SNS etc…). To access AWS APIs from webMethods you will need to implement the signing process yourself using the instructions provided in the AWS Signature Version 4 Signing Process documentation. This webMethods package “AWSSignature” helps you in generating the same via webMethods.

Overview

Here is an overview of the steps involved in signing a request using Signature Version 4:

  1. Create a canonical request. A canonical request is a standardized representation of the request that you are going to sign. It includes the request method (e.g., GET), the URI, the query string parameters, the headers, and the payload (if any).
  2. Create a string to sign. The string to sign is a combination of several pieces of information, including the signing algorithm, the date and time of the request, the region and service for the request, and the canonical request.
  3. Calculate the signature. The signature is calculated by running the string to sign through a cryptographic hash function (e.g., SHA-256) and then using your secret access key to sign the resulting hash.
  4. Add the signature to the request . Finally, you need to add the signature to the request as an additional header. The header will include the algorithm used to sign the request, the date and time of the request, the region and service for the request, and the actual signature value.

Please refer to AWS public documentation for more details on this topic.

Prerequisite

AWS “Access Key ID” and “Secret Access Key”.

Description

To create an AWS Signature version 4 in webMethods, you need to install the attached package “AWSSignature” and follow the below steps:

  1. Create a canonical request by following these steps:
  • Start with the HTTP request method (e.g., GET, PUT, POST, etc.) in upper case, followed by a new line character.
  • Add the canonical URI, which is the URI-encoded version of the request path (e.g., /path/to/resource), followed by a new line character.
  • Add the canonical query string, which is the URI-encoded version of the request query string with any sort parameters and URL-encoded characters decoded, followed by a new line character.
  • Add the canonical headers, which is a list of all request headers sorted alphabetically by their lowercase name, with each header in the format {name}: {value}, followed by a new line character.
  • Add the signed headers, which is a list of all request headers included in the canonical headers, sorted alphabetically, and separated by semicolons, followed by a new line character.
  • Add the hexadecimal hash of the request payload (also known as the “body” or “entity” of the request), followed by a new line character.

Note: Use the below service to create canonical request in webMethods.

AWSSignature.Version4.Utils:createCanonicalRequest

  1. Create a string to sign by following these steps:
  • Start with the algorithm used to sign the request, followed by a new line character.
  • Add the request date in the format YYYYMMDD’T’HHMMSS’Z’, followed by a new line character.
  • Add the scope, which is the date in YYYYMMDD format, followed by a slash and the AWS region the request is being sent to, followed by a slash and the service being called, followed by a slash and the “aws4_request” string, followed by a new line character.
  • Add the hexadecimal hash of the canonical request created in step 1.

Note: Use the below service to create string to sign in webMethods. You need to pass date time in UTC.

AWSSignature.Version4.Utils:createStringToSign

  1. Create the signature by following these steps:
  • Create a signing key by taking the secret access key and concatenating the date from the scope (in YYYYMMDD format), followed by a slash and the AWS region the request is being sent to, followed by a slash and the service being called, followed by a slash and the “aws4_request” string.
  • Use the HMAC-SHA256 algorithm to create a hash of the string to sign using the signing key.
  • Hex-encode the resulting hash to create the signature.

Note: Use the below service to calculate signature in webMethods.

AWSSignature.Version4.Utils:calculateSignature

  1. Add the signature to the request by including it in the “Authorization” header in the following format:

Authorization: algorithm Credential=access key ID/scope, SignedHeaders=signed headers, Signature=signature

Where:

  1. algorithm is the signing algorithm used (e.g., “AWS4-HMAC-SHA256”)
  2. access key ID is the AWS access key ID used to sign the request
  3. scope is the date and AWS region the request is being sent to, formatted as described in step 2
  4. signed headers is the list of headers included in the canonical headers, as described in step 1
  5. signature is the hexadecimal hash of the string to sign, as created in step 3

Note: Use the below service to generate Authorization header.

AWSSignature.Version4.Utils:addSignatureToRequest

Please refer sample services under the folder AWSSignature.Version4.Services to understand the usage of the services. Also, refer AWS specific API references to know more about the required inputs for the AWS API.

Useful links | Relevant resources

AWS Documentation

Signing AWS API requests - AWS General Reference (amazon.com)

AWSSignature.zip (84.4 KB)

3 Likes