Configure an AWS DMS endpoint to access cross-account secrets from AWS Secrets Manager

AWS Database Migration Service (AWS DMS) provides integration with AWS Secrets Manager for storing the database credentials. This integration allows you to store, rotate, and retrieve credentials used in the AWS DMS endpoints.

As a security best practice, customers use this integration for enhanced security control and also at times maintain a central account or respective line of business accounts that contain all database secrets created in related accounts. When migrating databases to the AWS Cloud or using Amazon Relational Database Service (Amazon RDS) with AWS DMS for cross-account database or data lake migrations, you can encounter scenarios where the AWS DMS replication instance, task, and endpoints are located in the migration account and database secrets are stored in a secured account.

In this post, we provide guidance on how to configure your AWS DMS endpoints and run migration tasks that can fetch secrets stored in a cross-account Secrets Manager. If you prefer to test a similar solution using AWS CloudFormation refer to Create an AWS DMS endpoint to a trusted third-party account via AWS Secrets Manager integration.

Solution overview

We utilize cross-account AWS Identity and Access Management (AWS IAM) roles and policies for an AWS DMS instance residing in an account to securely connect to another account where Amazon RDS database secrets and an AWS Key Management Service (AWS KMS) key are located.

In this example, we refer to two AWS accounts, A and B. Account A contains an RDS database instance, KMS key, and a secret that stores the hostname, port, user name, and password in Secrets Manager for that cluster. Account B contains the AWS DMS replication instance and endpoints.

The following diagram illustrates the solution architecture.

Prerequisites

You’ll need the following prerequisites if you plan to follow along:

• An Amazon RDS instance, as an endpoint.
• A network configured for cross-account Amazon Virtual Private Cloud (Amazon VPC) communication. In this example, we have preconfigured VPC peering for cross-account communication.
• A cross-account security group to allow access from the AWS DMS replication instance to the RDS instance.
• A VPC endpoint for Secrets Manager in the account containing AWS DMS resources.

The following configuration steps provide guidance on how you can configure resources to set up this pattern.

Configure Account A

To configure Account A, complete the following steps:

1. Create a KMS key for encrypting the secret if one doesn’t exist already. The ARN for the key is arn:aws:kms:<Region>:<AccountID A>:key/xxxxxx.
2. Create a Secret Manager secret using the KMS key. For this post, we name the secret secret_name. The ARN for the new secret is arn:aws:secretsmanager:<Region>:<AccountID A>:secret:secret_name.

If you already have an AWS DMS role created called DMSCrossAccountSecretAccessRole in Account B to fetch cross-account secrets, continue with the following steps. Otherwise, first create the role by name DMSCrossAccountSecretAccessRole for AWS DMS by following the steps in the next section, then return to Step 3 in this section.

3. Assign resource permissions to the secret:

   {
   "Version" : "2012-10-17",
   "Statement" : [{
   "Effect" : "Allow",
   "Principal" : {
   "AWS" : "arn:aws:iam::<AccountID B>:role/DMSCrossAccountSecretAccessRole"
   },
   "Action" : ["secretsmanager:GetSecretValue","secretsmanager:DescribeSecret"],
   "Resource" : " arn:aws:secretsmanager:<Region>:<AccountID A>:secret:secret_name "
   } ]
   }

4. Add the following section to the existing KMS key policy:

   {
   "Effect": "Allow",
   "Principal": {
   "AWS": "arn:aws:iam::<AccountID B>:role/DMSCrossAccountSecretAccessRole"
   },
   "Action": "kms:Decrypt",
   "Resource": " arn:aws:kms:<Region>:<AccountID A>:key/xxxxxx ",
   "Condition": {
   "StringEquals": {
   "kms:ViaService": "secretsmanager.<Region>.amazonaws.com"
   },
   "StringLike": {
   "kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:<Region>:<AccountID A>:secret:secret_name"
   }
   }
   }

In the next step, we move to account B.

Configure Account B

Complete the following steps to configure Account B:

1. Create an IAM service role called DMSCrossAccountSecretAccessRole for AWS DMS to access the cross-account secrets with the following trust policy:

   {
   "Version": "2012-10-17",
   "Statement": [
   {
   "Sid": "",
   "Effect": "Allow",
   "Principal": {
   "Service": "dms.<Region>.amazonaws.com"
   },
   "Action": "sts:AssumeRole"
   }
   }

2. Create an IAM policy called DMSCrossAccountSecretAccess for AWS DMS to allow access to the cross-account secret from Secrets Manager:

   {
   "Version": "2012-10-17",
   "Statement": [
   {
   "Action": [
   "secretsmanager:GetSecretValue"
   ],
   "Resource": "arn:aws:secretsmanager:<Region>:<AccountID A>:secret:secret_name",
   "Effect": "Allow"
   },
   {
   "Action": ["kms:Decrypt",
   "kms:DescribeKey"],
   "Resource": "arn:aws:kms:<Region>:<AccountID A>:key/xxxxxx",
   "Effect": "Allow"
   }
   ]
   }

3. Assign the policy DMSCrossAccountSecretAccess to the role DMSCrossAccountSecretAccessRole.
4. Return to Step 3 in the Configuration from Account A section if you haven’t already completed those steps.

Create an AWS DMS endpoint in Account B

Create an AWS DMS endpoint using the Secrets Manager configuration:

• For the secret ID, provide the complete secret ARN from Account A.
• For the IAM role, provide the ARN of the IAM role DMSCrossAccountSecretAccessRole.

Test the AWS DMS endpoint

Create a DMS replication instance and test the endpoint from the AWS DMS console to ensure connectivity is established and AWS DMS is able to fetch the secrets for the database.

Endpoint settings showing configuration with IAM Role and Secrets

Successful test for endpoint connection.

Clean up

After you test and cut over the database to the target, delete the AWS DMS replication instance and endpoint resources you created to avoid additional costs post-migration.

Summary

In this post, you learned how to centrally manage your AWS DMS replication instance in your migration account and fetch credentials from another secured account that hosts the database and secrets stored in Secrets Manager.

Reach out with questions or requests in the comments. Happy migrating!

About the authors

Shivam Gulati is a Senior Data Architect at Amazon Web Services. He works with customers to design and build highly available and scalable database and data analytics solutions in the AWS Cloud. Outside of work, he enjoys traveling, photography and exploring new places with friends and family.

Sushant Deshmukh is a Database Consultant with AWS Professional Services. He provides technical design and implementation expertise in running databases on AWS, also helping customers migrate and modernize their databases. Outside of work, he enjoys exploring new places, food and spending time with family and friends.