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
- Navigate to
Services - Lambda
. CreateclearbankFunction
Lambda function.
Note:
- When no execution role exists, select option
Create a new role with basic Lambda permissions
.
Create Function.
Upload the
.zip
fileclearbankFunction
.After uploading, you should find the following files in the Lambda function Code source:
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:
The public key needs to be uploaded in AWS in a file named publicKey.pem that is available to the forClearBank lambda function:
In this file you need to copy and paste the key you downloaded from ClearBank. It should look similar to this:
- Update the environment variables (should contain the MPO process details -
Webhook Listener [AWS]
(Secret key
,API login
andprocess ID
) andcompany_id
which will receive the webhooks and sign back theNonce
response). Click Save.
Notes:
- To get the values for
Secret key
,API login
andprocess ID
required for Lambda function create an API key for theWebhook 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 withi
- (e.g. https://[tenantName].[environment].mpo.mambu.com/editor/1/2/i000000000). - Open the
Webhook Listener [AWS]
process in MPO and click onStart
node. Select the previously created API key.
- 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 memory2048 MB
with a10 seconds
delay for the process.
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:
Afterwards, you need to create a new secret like this:
Please note that value1 and value2 from the screenshot above should match the authorizationTokenAWS
and secretKey
values from MPO ClearBank config!
In the end, you should have a new secret stored in AWS:
Digital Signature Lambda Functions
→Lambda Function for Digital Signature using AWS S3 and KMS solution
- Navigate to
Services - Lambda
. CreatedigitalSignature
Lambda function. - 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.: - Create Function.
- Upload the
.zip
filedigitalSignature
. - Add an environment variable to point to the AWS secret previously defined.
→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:
Create an additional environment variable to the Lambda function, that needs to point to the AWS secret created previously:
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.:
→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:
- Navigate to
Services - Lambda
. Createauthorizer
Lambda function. - 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)
- Create Function.
- Upload the
.zip
fileauthorizer
. - Add the SECRET_ID environment variable:
This should point to the secret created in the section AWS Secret Setup.
API Gateways
→API Gateway for Webhooks
- Navigate to
Services - API Gateway
and create the endpoint path (click onCreate API
button and select Rest API - Build). - Open your new API. Go to
Resources - Actions
and click on buttonCreate Resource
. - 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). - Select
Method Request
section from API Gateway (POST). Add Request Validator -Validate query string parameters and headers
underSettings
. - Select
Integration Request
section from API Gateway (POST). Add Mapping Templates -application/json
.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
}
}
- Select
Method Response
section from API Gateway (POST). Map success response message for ClearBank and addDigitalSignature
header.Map 401 response (Unauthorized) having Response body model Error.
- Select
Integration Response
section from API Gateway (POST). Map ClearBankDigitalSignature
header and success response message.
## 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:
{
"errorMessage" : "$input.path('$.errorMessage')"
}
Deploy API
from Actions menu.- Copy the
Invoke URL
(required for ClearBank webhooks linkage) available underStages
section.
→API Gateway for Digital Signature
- Navigate to
Services - API Gateway
and create the endpoint path (click onCreate API
button and select Rest API - Build). - Open your new API. Go to
Resources - Actions
and click on buttonCreate Resource
. - 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). - Link the
authorizer
lambda function to Digital Signature API Gateway fromAuthorizer
section. - Select
Method Request
section from API Gateway (POST). Add theAuthorization
as HTTP Request Header and the followingSettings
parameters:- Authorization - select the authorizer token created as a lambda function
authorizer
(e.g: AuthorizerSM). - Request Validator -
Validate query string parameters and headers
.
- Authorization - select the authorizer token created as a lambda function
- Select
Integration Request
section from API Gateway (POST). Add Mapping Templates -application/json
.
{
"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
}
}
- Select
Method Response
section from API Gateway (POST). Map ClearBank success response message and addDigitalSignature
header.For error messages, map Response Body model to Error:
- Select
Integration Response
section from API Gateway (POST). Map ClearBankDigitalSignature
header and success response message.
## 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:
{
"errorMessage" : "$input.path('$.errorMessage')"
}
Deploy API
from Actions menu.- Copy the
Invoke URL
(required for MPO setup) available underStages
section.
Certificate and Token
→Generate Certificate
- Navigate to
Services - Lambda
, search and selectDigitalSignature
function. - From function code rename
index
file (e.g: index_1). - From function code rename
generate CSR
file intoindex
. Click first onDeploy
then onTest
. - 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
. - 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
. - Rename the file
index
togenerate CSR
and theindex_1
file from Step 2 toindex
.
→Generate Token
- Navigate to
ClearBank UI - Certificates and Tokens
- Generate API Token. - Upload the
csr
file previously created (certificate that was created inCertificate and Token - Generate Certificate
section, Step 4). - Provide a
Token Name
and select theExpiration Date
. Generate. - Copy the API Token generated.
Key Management Service (KMS)
Note: this step can be skipped ifCloudHSM solution is used.
→KMS for Digital Signature Encryption
- Navigate to
Services - Key Management Service (KMS)
and create a new key (click onCreate a Key
as key typeSymmetric
). - Choose an alias for the key and, optionally description, tag key, tag value.
- Choose key administrators and select the IAM users and roles that can use the CMK in cryptographic operations.
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).
- Review Key policy and Finish.
→S3 Bucket
- Navigate to
Services - S3
. SelectBuckets
option and create a new bucket (click onCreate bucket
). - In the
Configure options
screen checkAutomatically encrypt objects when they are stored in S3
and choose the KMS key previously created. - In the
Set Permissions
screen, check optionBlock all public access
. - Review the configurations and check encryption.
- Upload the private key (file extension
.pem
) to the created bucket (key that was created inCertificate and Token - Generate Certificate
section, Step 5). - Set Read/Write permissions, select
Standard
class and set theAWS KMS master-key
asEncryption
type and choose the KMS key previously created. - 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
- Navigate to
Services - Lambda
, search and selectDigitalSignature
function. OpenPermissions
tab. - Check that
AmazonS3ReadOnlyAccess
policy is attached toDigitalSignature
Lambda function execution role. - Update the environment variables. Click Save.
Note:
If AmazonS3ReadOnlyAccess
policy is not attached to Lambda function execution role, it’s necessary that an Admin(AWS) performs these actions:
- Check that
DigitalSignature
Lambda execution role is attached to the KMS key. Navigate toServices - Key Management Service
and search for the KMS key.
→Update Digital Signature Lambda function
- Navigate to the Services > Lambda > DigitalSignature function.
- Add two environment variables: