Secrets Manager cross-account replication has been available since November 13, 2026, and for me it is one of the most useful AWS releases of the week. If you work with several AWS accounts, you know the problem: an API key or a database password is maintained centrally, but five other accounts need it. Until now that meant a resource policy on the secret, a grant on the KMS key, and every Lambda reaching across account boundaries into the central account. It works, but it feels like running a garden hose through three neighbors’ yards.

With the new feature, each account gets its own copy that stays up to date automatically. In this article I build the whole setup once: two accounts, two KMS keys, one replication role and a Lambda that only reads locally. You get AWS CDK, TypeScript and every command you need.

In short

Secrets Manager can now replicate a secret into another AWS account in the same Region, including rotations. The consuming account then reads only its own copy and no longer needs access to the central account. The biggest pitfall is KMS permissions: without customer managed keys on both sides and a matching key policy, the replica gets stuck in “Failed”.

What you will learn in this article

  • How primary secret, replica and replication role work together
  • When a replica beats shared access through a resource policy
  • The complete setup with AWS CDK, the AWS CLI and a TypeScript Lambda
  • How to check the replication status and fix errors
  • How to stop a replica cleanly or turn it into a standalone secret

What is Secrets Manager cross-account replication?

AWS Secrets Manager is the vault for credentials in AWS: passwords, API keys, OAuth tokens. For a while now it has been able to copy a secret into other Regions. What is new is that this also works across account boundaries. There are two roles involved:

  • Primary secret in the primary account: the original. This is where the value is maintained and rotated.
  • Replica secret in the replica account: an independent resource with its own KMS key, its own resource policy and its own tags. It receives every value change of the primary automatically.

According to the documentation, the value with its versions, the description, the secret type and the staging labels such as AWSCURRENT and AWSPREVIOUS are replicated. Tags, resource policy and KMS key, on the other hand, are managed by each account itself. That is exactly right: who may read in the replica account is decided by the replica account.

You should know a few hard rules up front. Primary and replica must live in the same Region. You get one cross-account replica per primary secret, no more. In addition, the replica has to be encrypted with a customer managed KMS key, because the AWS managed key aws/secretsmanager cannot be used from another account. Replication also runs asynchronously, so the copy is “eventually the same”, not identical within the same millisecond.

Shared access or Secrets Manager cross-account replication?

Before we build anything, a closer comparison is worth it. The classic way of sharing a secret across accounts is not wrong. It does have properties that hurt in larger landscapes, though.

Comparison: Lambda reads a secret across accounts vs. a Secrets Manager cross-account replica in its own account

Left: the previous shared access, right: the new replica in your own account

Question Shared access (before) Replica (new)
Where does the Lambda read? In the central account, across accounts In its own account
Who needs permissions on the central KMS key? Every reading role from every account Only the replication role
What happens if the central account is compromised? All readers depend on it directly The replica can be detached and keeps working on its own
Rotation Visible to everyone immediately Follows asynchronously
Cost One secret One additional secret per replica plus KMS keys
Infrastructure as code Fully supported Replica and association currently via API/CLI

Shared access and replica compared

My rule of thumb: if only a single account reads along occasionally, shared access stays simpler. If many workloads in several accounts depend on one centrally maintained secret, or you need an emergency copy in an isolated recovery account, the replica is the cleaner architecture. The runtime dependency disappears; what remains is a dependency when the value changes.

How replication works

Every value change on the primary, for example a PutSecretValue or a rotation, triggers replication. To do this, Secrets Manager decrypts the data key with the KMS key of the primary account and re-encrypts it with the key of the replica account. For these two KMS calls the service needs an identity. You can choose:

  • Replication role (recommended): an IAM role in the primary account that Secrets Manager assumes. Only this role needs permissions on both keys.
  • Forward access session (FAS): Secrets Manager uses the permissions of whoever changed the value. Then every writing identity, including a rotation Lambda, needs encrypt permissions on the foreign key.

In this article I go with the role. With FAS, the cross-account KMS permissions spread across all writing roles, and that is exactly what we wanted to get rid of.

🎬 Cross-account replication flow – this animated diagram only runs on my site: watch it on sascha-ms.de

Prerequisites

  • Two AWS accounts in the same AWS Organization, in this example 111111111111 (platform, primary) and 222222222222 (booking, replica). Other organizations work too, see below.
  • Two CLI profiles, here platform and booking, and a current AWS CLI v2 that knows the new commands.
  • Node.js 22 or newer and an account prepared with cdk bootstrap on both sides.
  • For the role that creates the replica: secretsmanager:CreateSecret and secretsmanager:PutResourcePolicy, because Secrets Manager attaches a managed resource policy on creation.

The example is a fictional bike rental. The platform team maintains the API key of the payment provider. The booking service runs in its own account and needs this key for every payment.

Set up Secrets Manager cross-account replication step by step

One special point first: at the time of writing, CloudFormation does not offer a property for the replica yet, and it is also missing in aws-cdk-lib 2.277. That is why I build keys, role and Lambda with CDK, while the CLI creates and associates the replica. Because the key policy and the secret ARN depend on each other, each stack is deployed twice. Sounds tedious, but it is done in ten minutes.

Step 1: The CDK project

The app knows two stacks, one per account. The ARNs that only become known later are passed in as context parameters.

// bin/app.ts import { App } from 'aws-cdk-lib'; import { PrimaryAccountStack } from '../lib/primary-account-stack.js'; import { ReplicaAccountStack } from '../lib/replica-account-stack.js'; const app = new App(); // Account IDs and region come from cdk.json or via -c on the command line const region = app.node.tryGetContext('region') ?? 'eu-central-1'; const primaryAccount = app.node.tryGetContext('primaryAccount') ?? '111111111111'; const replicaAccount = app.node.tryGetContext('replicaAccount') ?? '222222222222'; // Only known after the replica secret has been created (step 4) const replicaSecretArn: string | undefined = app.node.tryGetContext('replicaSecretArn'); const replicaKeyArn: string | undefined = app.node.tryGetContext('replicaKeyArn'); new PrimaryAccountStack(app, 'BikeRentalSecretsPrimary', { env: { account: primaryAccount, region }, replicaSecretArn, replicaKeyArn, }); new ReplicaAccountStack(app, 'BikeRentalBookingReplica', { env: { account: replicaAccount, region }, primaryAccountId: primaryAccount, replicaSecretArn, }); 

Step 2: Primary account with key and primary secret

In the primary account you create a customer managed KMS key and the primary secret. The replication role is only added once the ARNs from the replica account are known. Its trust policy allows only Secrets Manager, and only for exactly this secret. This prevents the so-called confused deputy problem, where a service misuses the role on behalf of someone else.

// lib/primary-account-stack.ts import { CfnOutput, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib'; import * as iam from 'aws-cdk-lib/aws-iam'; import * as kms from 'aws-cdk-lib/aws-kms'; import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager'; import type { Construct } from 'constructs'; export interface PrimaryAccountStackProps extends StackProps { /** ARN of the replica secret in the other account (from step 5) */ readonly replicaSecretArn?: string; /** ARN of the KMS key in the replica account (from step 5) */ readonly replicaKeyArn?: string; } export class PrimaryAccountStack extends Stack { constructor(scope: Construct, id: string, props: PrimaryAccountStackProps) { super(scope, id, props); // Customer managed key: required when a replication role has to decrypt const primaryKey = new kms.Key(this, 'PrimaryKey', { alias: 'alias/bikerental-secrets-primary', description: 'Encrypts the centrally managed secrets of the bike rental', enableKeyRotation: true, removalPolicy: RemovalPolicy.RETAIN, }); // The primary secret. Set the real API key afterwards with put-secret-value. const paymentSecret = new secretsmanager.Secret(this, 'PaymentProviderApiKey', { secretName: 'bikerental/payment-provider-api-key', description: 'API key of the payment provider, maintained by the platform team', encryptionKey: primaryKey, generateSecretString: { passwordLength: 40, excludePunctuation: true }, removalPolicy: RemovalPolicy.RETAIN, }); new CfnOutput(this, 'PrimarySecretArn', { value: paymentSecret.secretArn }); // The role is only created once the replica secret and replica key are known if (!props.replicaSecretArn || !props.replicaKeyArn) { return; } const replicationRole = new iam.Role(this, 'ReplicationRole', { roleName: 'bikerental-secret-replication', description: 'Assumed by Secrets Manager for cross-account replication', // Protection against the confused deputy problem: only for exactly this secret assumedBy: new iam.ServicePrincipal('secretsmanager.amazonaws.com').withConditions({ StringEquals: { 'aws:SourceAccount': this.account }, ArnEquals: { 'aws:SourceArn': paymentSecret.secretArn }, }), }); // 1. Decrypt the data key of the primary secret replicationRole.addToPolicy( new iam.PolicyStatement({ sid: 'DecryptPrimary', actions: ['kms:Decrypt'], resources: [primaryKey.keyArn], conditions: { StringEquals: { 'kms:EncryptionContext:SecretARN': paymentSecret.secretArn }, }, }), ); // 2. Re-encrypt for the replica in the other account replicationRole.addToPolicy( new iam.PolicyStatement({ sid: 'EncryptReplica', actions: ['kms:Encrypt'], resources: [props.replicaKeyArn], conditions: { StringEquals: { 'kms:EncryptionContext:SecretARN': props.replicaSecretArn }, }, }), ); new CfnOutput(this, 'ReplicationRoleArn', { value: replicationRole.roleArn }); } } 

A note on the key policy: by default, CDK creates a policy that delegates permissions to IAM in its own account. That is why the identity policy of the role is enough here. If you use a stricter key policy without this delegation, you also have to add the role there for kms:Decrypt.

# In the primary account (profile "platform") npm install npx cdk deploy BikeRentalSecretsPrimary --profile platform \ -c primaryAccount=111111111111 -c replicaAccount=222222222222 

From the output, keep PrimarySecretArn as PRIMARY_SECRET_ARN.

Step 3: Create the key in the replica account

At first, the replica stack only creates the KMS key. As soon as the replica exists, the second deployment adds the grant for the primary account and the Lambda.

// lib/replica-account-stack.ts import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib'; import * as iam from 'aws-cdk-lib/aws-iam'; import * as kms from 'aws-cdk-lib/aws-kms'; import * as lambda from 'aws-cdk-lib/aws-lambda'; import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs'; import type { Construct } from 'constructs'; export interface ReplicaAccountStackProps extends StackProps { /** Account that owns the primary secret */ readonly primaryAccountId: string; /** ARN of the replica secret (from step 5) */ readonly replicaSecretArn?: string; } export class ReplicaAccountStack extends Stack { constructor(scope: Construct, id: string, props: ReplicaAccountStackProps) { super(scope, id, props); // The key belongs to the replica account, not to the platform team const replicaKey = new kms.Key(this, 'ReplicaKey', { alias: 'alias/bikerental-booking-replica', description: 'Encrypts the replica of the payment provider key', enableKeyRotation: true, removalPolicy: RemovalPolicy.RETAIN, }); new CfnOutput(this, 'ReplicaKeyArn', { value: replicaKey.keyArn }); if (!props.replicaSecretArn) { return; } // The primary account may use this key only to encrypt exactly this replica replicaKey.addToResourcePolicy( new iam.PolicyStatement({ sid: 'AllowCrossAccountReplication', principals: [new iam.AccountPrincipal(props.primaryAccountId)], actions: ['kms:Encrypt'], resources: ['*'], conditions: { StringEquals: { 'kms:EncryptionContext:SecretARN': props.replicaSecretArn }, }, }), ); // The booking Lambda only reads locally in its own account const bookingFn = new NodejsFunction(this, 'BookingFunction', { entry: 'src/booking-handler.ts', runtime: lambda.Runtime.NODEJS_24_X, architecture: lambda.Architecture.ARM_64, memorySize: 256, timeout: Duration.seconds(10), environment: { PAYMENT_SECRET_ARN: props.replicaSecretArn, SECRET_CACHE_SECONDS: '300', }, }); bookingFn.addToRolePolicy( new iam.PolicyStatement({ actions: ['secretsmanager:GetSecretValue'], resources: [props.replicaSecretArn], }), ); replicaKey.grantDecrypt(bookingFn); new CfnOutput(this, 'BookingFunctionName', { value: bookingFn.functionName }); } } 
# In the replica account (profile "booking") npx cdk deploy BikeRentalBookingReplica --profile booking \ -c primaryAccount=111111111111 -c replicaAccount=222222222222 

The output ReplicaKeyArn becomes REPLICA_KEY_ARN.

Step 4: Create the replica secret

Now the replica account creates an empty secret that points to the primary. Secrets Manager automatically attaches a managed resource policy named cross-account-replication, which allows the primary account to set up replication.

# In the replica account: create an empty replica that points to the primary secret aws secretsmanager create-secret --profile booking \ --name bikerental/payment-provider-replica \ --cross-account-primary-arn "$PRIMARY_SECRET_ARN" \ --kms-key-id "$REPLICA_KEY_ARN" 

The ARN in the response is your REPLICA_SECRET_ARN. Until the first synchronization, GetSecretValue on the replica returns ResourceNotFoundException, by the way. That is not an error, just an empty vault.

Step 5: Complete the permissions

With both ARNs in hand, you deploy both stacks a second time. In the replica account, the key policy then allows the primary account to call kms:Encrypt, but only with the encryption context of this one replica. In the primary account, the replication role is created.

# Replica account: add the key policy statement and the Lambda npx cdk deploy BikeRentalBookingReplica --profile booking \ -c primaryAccount=111111111111 -c replicaAccount=222222222222 \ -c replicaSecretArn="$REPLICA_SECRET_ARN" # Primary account: add the replication role npx cdk deploy BikeRentalSecretsPrimary --profile platform \ -c primaryAccount=111111111111 -c replicaAccount=222222222222 \ -c replicaSecretArn="$REPLICA_SECRET_ARN" -c replicaKeyArn="$REPLICA_KEY_ARN" 

You need the output ReplicationRoleArn as REPLICATION_ROLE_ARN and, later on, BookingFunctionName as BOOKING_FUNCTION_NAME.

Step 6: Associate the replica and check the status

The primary account takes the last step. associate-cross-account-replica first runs a dry-run check of the KMS permissions on both sides, links the secrets and starts the first copy. By default, SameOrg applies: the replica account has to be in the same organization. For an external account, you deliberately set --replica-restriction NoRestriction.

# In the primary account: associate the replica and start replication aws secretsmanager associate-cross-account-replica --profile platform \ --secret-id "$PRIMARY_SECRET_ARN" \ --cross-account-replica-arn "$REPLICA_SECRET_ARN" \ --replication-role-arn "$REPLICATION_ROLE_ARN" # Wait until the status reports InSync AWS_PROFILE=platform npx tsx scripts/wait-for-replication.ts "$PRIMARY_SECRET_ARN" 

This small script calls DescribeSecret every five seconds and stops with the error message on Failed. You can run it in a pipeline after the deployment just as well.

// scripts/wait-for-replication.ts import { DescribeSecretCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager'; const secretId = process.argv[2]; const maxAttempts = Number(process.argv[3] ?? '24'); const client = new SecretsManagerClient({}); if (!secretId) { console.error('Usage: npx tsx scripts/wait-for-replication.ts <primary-secret-arn> [attempts]'); process.exit(2); } const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); for (let attempt = 1; attempt <= maxAttempts; attempt++) { const secret = await client.send(new DescribeSecretCommand({ SecretId: secretId })); const replica = secret.CrossAccountReplicas?.[0]; if (!replica) { console.error('No cross-account replica associated.'); process.exit(1); } console.log(`Attempt ${attempt}: ${replica.ReplicationStatus} -> ${replica.ReplicaSecretARN}`); if (replica.ReplicationStatus === 'InSync') { process.exit(0); } if (replica.ReplicationStatus === 'Failed' || replica.ReplicationStatus === 'Detached') { console.error(`Aborting: ${replica.StatusMessage ?? 'no details'}`); process.exit(1); } await sleep(5000); } console.error('Time limit reached, replica is not InSync yet.'); process.exit(1); 

Expected result:

Attempt 1: InProgress -> arn:aws:secretsmanager:eu-central-1:222222222222:secret:bikerental/payment-provider-replica-AbCdEf Attempt 2: InSync -> arn:aws:secretsmanager:eu-central-1:222222222222:secret:bikerental/payment-provider-replica-AbCdEf 

Step 7: The Lambda only reads locally

Now the booking Lambda only needs two permissions in its own account: GetSecretValue on the replica and kms:Decrypt on its own key. It keeps the value in memory for five minutes, so not every invocation has to ask Secrets Manager.

// src/booking-handler.ts import { GetSecretValueCommand, ResourceNotFoundException, SecretsManagerClient, } from '@aws-sdk/client-secrets-manager'; const client = new SecretsManagerClient({}); const secretArn = process.env.PAYMENT_SECRET_ARN ?? ''; const cacheMs = Number(process.env.SECRET_CACHE_SECONDS ?? '300'Source:https://dev.to/sascha-ms/secrets-manager-cross-account-replication-setup-guide-6ah

Related posts