AWS Setup

The configuration in AWS can be one of two ways, depending on where you choose to store the private key used for the Digital Signature:

  • AWS S3 + KMS
  • AWS CloudHSM

Lambda Function for Webhooks

  1. Navigate to Services - Lambda. Create clearbankFunction Lambda function.
    Create Lambda Function

Note:

  • When no execution role exists, select option Create a new role with basic Lambda permissions.
  1. Create Function.

  2. Upload the .zip file clearbankFunction.
    Upload Lambda Function Save Upload Lambda Function After uploading, you should find the following files in the Lambda function Code source:
    Lambda Function File Structure

  3. In order to verify the webhooks from ClearBank, it is necessary to have the public key from ClearBank institution. You can get it from Webhook Management: ClearBank Download Public Key

The public key needs to be uploaded in AWS in a file named publicKey.pem that is available to the forClearBank lambda function:
Lambda Function New File
In this file you need to copy and paste the key you downloaded from ClearBank. It should look similar to this:
Lambda Function CB Public Key

  1. Update the environment variables (should contain the MPO process details - Webhook Listener [AWS] (Secret key, API login and process ID) and company_id which will receive the webhooks and sign back the Nonce response). Click Save.
    Environment Variables

Notes:

  • To get the values for Secret key, API login and process ID required for Lambda function create an API key for the Webhook Listener [AWS] process.
  • The value for company_id can be taken from the URL regardless of the MPO process opened. It is always the last value in the endpoint that starts with i - (e.g. https://[tenantName].[environment].mpo.mambu.com/editor/1/2/i000000000). MPO. Company Id
  • Open the Webhook Listener [AWS] process in MPO and click on Start node. Select the previously created API key.
    MPO. Api key
  1. Update the allocated memory from Lambda function (e.g: clearBankFunction) - Basic Settings - Memory (MB). If you expect many requests to be sent, then allocate the default memory 2048 MB with a 10 seconds delay for the process.
    Basic Settings

AWS Secret setup

The AWS secret should be defined in order to store the authorization token and the secret key used to authenticate requests coming from MPO to AWS.

Firstly, you need to access the AWS Secrets Manager service: AWS Secrets Manager Afterwards, you need to create a new secret like this: New AWS Secret configuration - step 1 New AWS Secret configuration - step 2

Please note that value1 and value2 from the screenshot above should match the authorizationTokenAWS and secretKey values from MPO ClearBank config!

New AWS Secret configuration - step 3 New AWS Secret configuration - step 4 New AWS Secret configuration - step 5

In the end, you should have a new secret stored in AWS:

New AWS Secret configuration - step 6

Digital Signature Lambda Functions

Lambda Function for Digital Signature using AWS S3 and KMS solution

  1. Navigate to Services - Lambda. Create digitalSignature Lambda function.
  2. When no execution role exists, create a new execution role by selecting the option Create a new role with basic Lambda permissions. In addition, Lambda function also needs to have permissions to read the Secret value for the AWS secret, i.e.: View Lambda Function role document - 1 View Lambda Function role document - 2
  3. Create Function.
  4. Upload the .zip file digitalSignature.
    Upload Lambda Function
  5. Add an environment variable to point to the AWS secret previously defined. Edit Environment Variables Add MPO Secret Id Environment Variables

Lambda Function for Digital Signature using AWS CloudHSM solution

In case you use the Digital Signature based on AWS CloudHSM private key, you need to follow the steps documented at https://docs.google.com/document/d/1H6CZiU0YZHuU1JMsTdg0MSIHyM12OB7AmPEYq6K8mFc/edit#heading=h.e0ewvaxju46u.

After setting the Lambda function according to the above documentation, there are 2 more steps in order to interact with the AWS secret:

  1. Create an additional environment variable to the Lambda function, that needs to point to the AWS secret created previously: Edit Environment Variables Add MPO Secret Id Environment Variables

  2. Verify the permissions of the Lambda function role - Lambda function needs to have permissions to read the Secret value for the AWS secret, i.e.: View Lambda Function role document - 1 View Lambda Function role document - 2

Lambda Function for Authorization Token

This Lambda function is required to authenticate the requests coming to the API Gateway for Digital Signature (ensuring that they come from MPO). To create and configure this function, you need to follow these steps:

  1. Navigate to Services - Lambda. Create authorizer Lambda function.
  2. Choose a role that gives the Lambda function access to AWS Secret Manager (see step 2 of Lambda Function for Digital Signature using CloudHSM solution)
  3. Create Function.
  4. Upload the .zip file authorizer.
    Upload Lambda Function Basic Settings
  5. Add the SECRET_ID environment variable: Edit Environment Variables Add SECRET_ID Environment Variable This should point to the secret created in the section AWS Secret Setup.

API Gateways

API Gateway for Webhooks

  1. Navigate to Services - API Gateway and create the endpoint path (click on Create API button and select Rest API - Build).
    Create REST API Create API
  2. Open your new API. Go to Resources - Actions and click on button Create Resource.
    Create Resource
  3. Create synchronous endpoint by selecting the previous resource created (e.g: /gateway). Click on Actions - Create Method - POST. Select the POST method and add the lambda function (e.g: forClearBank).
    Create POST Method Request
  4. Select Method Request section from API Gateway (POST). Add Request Validator - Validate query string parameters and headers under Settings. Method Request
  5. Select Integration Request section from API Gateway (POST). Add Mapping Templates - application/json.
    Integration Request Mapping Template The following code needs to be placed at the mapping templates:
{
    "body":"$util.escapeJavaScript($input.body).replaceAll("\\'","'").replaceAll("\'","'")",
    "headers":{
        #foreach($param in $input.params().header.keySet())
        "$param": "$util.escapeJavaScript($input.params().header.get($param))"
        #if($foreach.hasNext),#end
        #end
    }
}
  1. Select Method Response section from API Gateway (POST). Map success response message for ClearBank and add DigitalSignature header.
    Method Response Map 401 response (Unauthorized) having Response body model Error. Method Response
  2. Select Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature header and success response message.
    Integration Response
##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
## WARNING: Every character matters in this form (including spaces)! Do not change a bit!
#set($inputRoot = $input.json('$.Nonce')){"Nonce":$inputRoot}

Response codes:

Accepted -> 200 response code
Rejected -> 401 response code

Map 401 response code having the “AUTHORIZATION ERROR” Lambda error regex and the mapping template below: Integration Response

{
  "errorMessage" : "$input.path('$.errorMessage')"
}
  1. Deploy API from Actions menu.
    Deploy API Deploy API Stage
  2. Copy the Invoke URL (required for ClearBank webhooks linkage) available under Stages section.
    Invoke URL

API Gateway for Digital Signature

  1. Navigate to Services - API Gateway and create the endpoint path (click on Create API button and select Rest API - Build).
  2. Open your new API. Go to Resources - Actions and click on button Create Resource.
  3. Create synchronous endpoint by selecting the previous resource created (e.g: /gateway). Click on Actions - Create Method - POST. Select the POST method and add the lambda function (e.g: digitalSignature).
  4. Link the authorizer lambda function to Digital Signature API Gateway from Authorizer section.
    Create Authorizer
    Authorizer
  5. Select Method Request section from API Gateway (POST). Add the Authorization as HTTP Request Header and the following Settings parameters:
    • Authorization - select the authorizer token created as a lambda function authorizer (e.g: AuthorizerSM).
    • Request Validator - Validate query string parameters and headers.
      Method Request Method Request Header
  6. Select Integration Request section from API Gateway (POST). Add Mapping Templates - application/json.
    Integration Request Mapping Template
{
    "body":$input.json("$"),
    "queryparams":{
        #foreach($param in $input.params().querystring.keySet())
        "$param": "$util.escapeJavaScript($input.params().querystring.get($param))"
        #if($foreach.hasNext),#end
        #end
    },
    "headers":{
        #foreach($param in $input.params().header.keySet())
        "$param": "$util.escapeJavaScript($input.params().header.get($param))"
        #if($foreach.hasNext),#end
        #end
    }
}
  1. Select Method Response section from API Gateway (POST). Map ClearBank success response message and add DigitalSignature header.
    Method Response For error messages, map Response Body model to Error: Method Response Method Response
  2. Select Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature header and success response message.
    Integration Response
##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
#set($inputRoot = $input.json('$'))
$inputRoot

For method response status 400, map ERROR response message like below: Integration Response

{
  "errorMessage" : "$input.path('$.errorMessage')"
}
  1. Deploy API from Actions menu.
    Deploy API Deploy API Stage
  2. Copy the Invoke URL (required for MPO setup) available under Stages section.
    Invoke URL - Digital Signature

Certificate and Token

Generate Certificate

  1. Navigate to Services - Lambda, search and select DigitalSignature function.
  2. From function code rename index file (e.g: index_1). Generate Certificate & Token
  3. From function code rename generate CSR file into index. Click first on Deploy then on Test. Generate Certificate & Token
  4. From the reponse create the .csr file. Copy the certificate which starts from -----BEGIN CERTIFICATE REQUEST----- and ends in -----END CERTIFICATE REQUEST----- (without single quotas). Save the file with extension .csr.
  5. From the reponse create the .pem file. Copy the Private Key which starts from -----BEGIN PRIVATE KEY----- and ends in -----END PRIVATE KEY----- (without single quotas). Save the file with extension .pem.
  6. Rename the file index to generate CSR and the index_1 file from Step 2 to index.

Generate Token

  1. Navigate to ClearBank UI - Certificates and Tokens- Generate API Token.
  2. Upload the csr file previously created (certificate that was created in Certificate and Token - Generate Certificate section, Step 4).
  3. Provide a Token Name and select the Expiration Date. Generate.
    Generate API Token
  4. Copy the API Token generated.

Key Management Service (KMS)

Note: this step can be skipped ifCloudHSM solution is used.

KMS for Digital Signature Encryption

  1. Navigate to Services - Key Management Service (KMS) and create a new key (click on Create a Key as key type Symmetric). KMS Key
  2. Choose an alias for the key and, optionally description, tag key, tag value.
    KMS Alias
  3. Choose key administrators and select the IAM users and roles that can use the CMK in cryptographic operations.
    KMS Key Administrators KMS Key Usage

Note: Multiple selections can be done, important is to add the Role under the digitalSignature Lambda function is executed and the User (the key administrator).

  1. Review Key policy and Finish.
    KMS Key Policy

S3 Bucket

  1. Navigate to Services - S3. Select Buckets option and create a new bucket (click on Create bucket).
    S3 Create Bucket
  2. In the Configure options screen check Automatically encrypt objects when they are stored in S3 and choose the KMS key previously created.
    S3 Default Encryption
  3. In the Set Permissions screen, check option Block all public access.
    S3 Blocking Access
  4. Review the configurations and check encryption.
    S3 Review Encryption S3 Encryption S3 Default Encryption KMS
  5. Upload the private key (file extension .pem) to the created bucket (key that was created in Certificate and Token - Generate Certificate section, Step 5).
    S3 Upload
  6. Set Read/Write permissions, select Standard class and set the AWS KMS master-key as Encryption type and choose the KMS key previously created.
    S3 Set Permissions S3 Set Properties S3 Set Properties Encryption
  7. Review settings and upload the file.

Note: ClearBank .pem private key should have been generated previously, as described at Generate Certificate section

Grant access of Digital Signature Lambda function to the encrypted AWS S3

  1. Navigate to Services - Lambda, search and select DigitalSignature function. Open Permissions tab.
    DigitalSignature Permissions
  2. Check that AmazonS3ReadOnlyAccess policy is attached to DigitalSignature Lambda function execution role.
    DigitalSignature Roles
  3. Update the environment variables. Click Save.
    Environment Variables Basic Settings

Note: If AmazonS3ReadOnlyAccess policy is not attached to Lambda function execution role, it’s necessary that an Admin(AWS) performs these actions:
Attach Policy Attach Policy Attach Policy

  1. Check that DigitalSignature Lambda execution role is attached to the KMS key. Navigate to Services - Key Management Service and search for the KMS key.
    KMS Key KMS Role

Update Digital Signature Lambda function

  1. Navigate to the Services > Lambda > DigitalSignature function.
  2. Add two environment variables:
  • CB_BUCKET -> AWS encrypted bucket (as defined in the S3 Bucket section)
  • CB_KEY_FILE -> the file name where the key is store in the bucket (as defined in the S3 Bucket section - .pem file) DSH Environment Variables