Production ready deployment on AWS

CDK script to deploy Juspay Hyperswitch Card Vault on AWS

This section covers the steps for deploying the Juspay Hyperswitch card vault as an individual component

If you're looking for a production grade deployment of the card vault to be used along with the Hyperswitch application, refer to the full-stack deployment guide of Juspay Hyperswitch which includes the card locker as well.

Standalone deployment of the Juspay Hyperswitch Card Vault

Pre-requisites

• git installed on your local machine

• node version 18

• An AWS user account with admin access (you can create an account here if you do not have one)

Step 1 - [Optional] - Create a new user with Admin access (if you do not have a non-root user)

• Create a new user in your AWS account from IAM -> Users (as shown below)

• While setting permissions, provide admin access to the user

Step 2 - Configure your AWS credentials in your terminal

For this step you would need the following from your AWS account

1. Preferred AWS region

2. Access key ID

3. Secret Access Key

4. Session Token (if you have MFA set up)

You can create or manage your access keys from IAM > Users inside your AWS Console. For more information, click here

Once you have the keys run the below command

export AWS_DEFAULT_REGION=<Your AWS_REGION> // e.g., export AWS_DEFAULT_REGION=us-east-2
export AWS_ACCESS_KEY_ID=<Your Access_Key_Id> // e.g., export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=<Your Secret_Access_Key> // e.g., export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN="<Your AWS_SESSION_TOKEN>" //optional

Step 3 - Deploy Card Vault

Run the below commands in the same terminal session

git clone https://github.com/juspay/hyperswitch-cdk.git
cd hyperswitch-cdk
sh install-locker.sh

Once the script is run you will have to provide the following as inputs

1. Provide the master-key when prompted (command to generate the master-key will be displayed on the terminal; also note down the two custodian keys to start the locker)

2. Provide the Locker DB password of your choice when prompted

3. If you want to deploy the card vault in an existing VPC of yours, provide the VPC ID when prompted.

Note: The VPC should have at least one private subnet with egress to deploy the card vault

1. If you don't have one or want to set up a new VPC leave the input blank and proceed

Unlocking the Card Vault

At this point your locker setup on the AWS account is complete. Please follow the steps below to unlock the locker to make it ready for use.

• Run the following command to generate the key for the jump-server

aws ssm get-parameter --name /ec2/keypair/$(aws ec2 describe-key-pairs --filters Name=key-name,Values=LockerJump-ec2-keypair --query "KeyPairs[*].KeyPairId" --output text) --with-decryption --query Parameter.Value --output text > locker-jump.pem

• Run the following command to update the permissions for your jump server key

chmod 400 locker-jump.pem

• Run the following command to SSH access your Card Vault instance through a jump server

ssh -i locker-jump.pem ec2-user@$JUMP_SERVER_ID

• Use the custodian keys to activate the locker (You can find the cURLs here) These cURLs are also displayed at the end of the script.

• The locker_public key and the tenant_private key to use the locker with your application (Juspay Hyperswitch or otherwise) would be generated and available in the Parameter Store. Use the commands provided to fetch them.

aws ssm get-parameter --name /locker/public_key:1 --query 'Parameter.Value' --output text
aws ssm get-parameter --name /tenant/private_key:1 --query 'Parameter.Value' --output text

Output

On successful deployment of the Card Vault you will receive the following

Output	What it is used for
Jump Locker SSH Key	This is used to Jump Locker SSH key to access the jump server
Jump Locker Public IP	The IP Address of the Jump Server where you can activate the Card Vault
Locker IP	The URL of the Card Vault service
Locker Public Key	The public key of the card vault that needs to be used to JWE encrypt the requests to the card vault
Tenant Private Key	The private key of the tenant application that needs to be used to JWE decrypt the response from the card vault

Make sure to save the keys and passwords you provide while running the script

Integrating it with your Application

To start using it with Juspay Hyperswitch update the following environment variables while deploying. You can use it with any other tenant application using the respective card vault URL and JWE keys.

ROUTER__LOCKER__HOST= # add the ip address of the ec2 instance created
ROUTER__JWEKEY__VAULT_ENCRYPTION_KEY= # add the JWE public key of locker generated above
ROUTER__JWEKEY__VAULT_PUBLIC_KEY= # add the JWE private key of tenant generated above

Next step:

Test a payment