feat(s3): add grantReplicationPermission for IAM Role permissions (#34138)

### Issue # (if applicable)

Closes #34119

### Reason for this change

This change introduces a new method, grantReplicationPermission, to the aws-cdk-lib.aws_s3.Bucket construct. The purpose of this addition is to provide a more convenient and programmatic way for AWS CDK users to grant the necessary IAM permissions to a user-provided IAM Role that will be used for S3 bucket replication.

### Description of changes



This pull request includes the following code changes:

- Added a new public method `grantReplicationPermission` to the Bucket class.
- The implementation of this method programmatically attaches the necessary IAM permissions for S3 bucket replication to the provided identity. This change refactors the `renderReplicationConfiguration` method by extracting the IAM permission granting functionality into a dedicated `grantReplicationPermission` method.
- unit and integ test
- The README was updated to show that users can now grant replication rights to custom IAM roles.


### Describe any new or updated permissions being added

No new IAM permissions are being added at the CDK level. The permissions granted by the `grantReplicationPermission` method are the same as those already handled internally by the existing replication configuration logic. This change simply exposes that functionality through a dedicated method.


### Description of how you validated changes

- Added unit tests to verify the functionality of the `grantReplicationPermission` method, ensuring that the correct IAM policies are attached to the provided role. Notably, the unit tests specifically cover scenarios where an explicit `replicationRole` is provided.
- Existing integration tests were run to confirm that no regressions were introduced by this change. In addition, the existing test scenario `integ.bucket-replication-use-custom-role.ts` was refactored to use the new `grantReplicationPermission` method instead of manually attaching the required permissions to the IAM role, and its behavior was verified to remain equivalent.

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: hassaku63

packages/@aws-cdk-testing/framework-integ/test/aws-dynamodb/test/integ.import-source.js.snapshot/asset.530055f7515b3f0a47900f5df37e729ba40ca977b2d07b952bdefa2b8f883f42.bundle/index.js

@@ -304,25 +304,25 @@
        }
       },
       {
-       "Action": "kms:Decrypt",
+       "Action": [
+        "kms:Encrypt",
+        "kms:GenerateDataKey*",
+        "kms:ReEncrypt*"
+       ],
        "Effect": "Allow",
        "Resource": {
         "Fn::GetAtt": [
-         "SourceKmsKeyFE472F1C",
+         "DestinationKmsKey0D94AA3C",
          "Arn"
         ]
        }
       },
       {
-       "Action": [
-        "kms:Encrypt",
-        "kms:GenerateDataKey*",
-        "kms:ReEncrypt*"
-       ],
+       "Action": "kms:Decrypt",
        "Effect": "Allow",
        "Resource": {
         "Fn::GetAtt": [
-         "DestinationKmsKey0D94AA3C",
+         "SourceKmsKeyFE472F1C",
          "Arn"
         ]
        }

packages/@aws-cdk-testing/framework-integ/test/aws-s3/test/integ.bucket-replication-use-custom-role.js.snapshot/BucketReplicationTestStack.assets.json

@@ -47,23 +47,12 @@ class TestStack extends Stack {
       ],
     });
 
-    this.replicationRole.addToPrincipalPolicy(new iam.PolicyStatement({
-      actions: ['s3:GetReplicationConfiguration', 's3:ListBucket'],
-      resources: [this.sourceBucket.bucketArn],
-      effect: iam.Effect.ALLOW,
-    }));
-    this.replicationRole.addToPrincipalPolicy(new iam.PolicyStatement({
-      actions: ['s3:GetObjectVersionForReplication', 's3:GetObjectVersionAcl', 's3:GetObjectVersionTagging'],
-      resources: [this.sourceBucket.arnForObjects('*')],
-      effect: iam.Effect.ALLOW,
-    }));
-    this.replicationRole.addToPrincipalPolicy(new iam.PolicyStatement({
-      actions: ['s3:ReplicateObject', 's3:ReplicateDelete', 's3:ReplicateTags', 's3:ObjectOwnerOverrideToBucketOwner'],
-      resources: [this.destinationBucket.arnForObjects('*')],
-      effect: iam.Effect.ALLOW,
-    }));
-    sourceKmsKey.grantDecrypt(this.replicationRole);
-    destinationKmsKey.grantEncrypt(this.replicationRole);
+    this.sourceBucket.grantReplicationPermission(this.replicationRole, {
+      sourceDecryptionKey: sourceKmsKey,
+      destinations: [
+        { encryptionKey: destinationKmsKey, bucket: this.destinationBucket },
+      ],
+    });
   }
 }
 

packages/@aws-cdk-testing/framework-integ/test/aws-s3/test/integ.bucket-replication-use-custom-role.js.snapshot/BucketReplicationTestStack.template.json

@@ -941,11 +941,14 @@ To replicate objects to a destination bucket, you can specify the `replicationRu
 declare const destinationBucket1: s3.IBucket;
 declare const destinationBucket2: s3.IBucket;
 declare const replicationRole: iam.IRole;
-declare const kmsKey: kms.IKey;
+declare const encryptionKey: kms.IKey;
+declare const destinationEncryptionKey: kms.IKey;
 
 const sourceBucket = new s3.Bucket(this, 'SourceBucket', {
   // Versioning must be enabled on both the source and destination bucket
   versioned: true,
+  // Optional. Specify the KMS key to use for encrypts objects in the source bucket.
+  encryptionKey,
   // Optional. If not specified, a new role will be created.
   replicationRole,
   replicationRules: [
@@ -970,7 +973,7 @@ const sourceBucket = new s3.Bucket(this, 'SourceBucket', {
       // If set, metrics will be output to indicate whether replication by S3 RTC took longer than the configured time.
       metrics: s3.ReplicationTimeValue.FIFTEEN_MINUTES,
       // The kms key to use for the destination bucket.
-      kmsKey,
+      kmsKey: destinationEncryptionKey,
       // The storage class to use for the destination bucket.
       storageClass: s3.StorageClass.INFREQUENT_ACCESS,
       // Whether to replicate objects with SSE-KMS encryption.
@@ -997,6 +1000,20 @@ const sourceBucket = new s3.Bucket(this, 'SourceBucket', {
     },
   ],
 });
+
+// Grant permissions to the replication role.
+// This method is not required if you choose to use an auto-generated replication role or manually grant permissions.
+sourceBucket.grantReplicationPermission(replicationRole, {
+  // Optional. Specify the KMS key to use for decrypting objects in the source bucket.
+  sourceDecryptionKey: encryptionKey,
+  destinations: [
+    { bucket: destinationBucket1 },
+    { bucket: destinationBucket2, encryptionKey: destinationEncryptionKey },
+  ],
+  // The 'encryptionKey' property within the 'destinations' array is optional.
+  // If not specified for a destination bucket, this method assumes that
+  // given destination bucket is not encrypted.
+});
 ```
 
 ### Cross Account Replication

packages/@aws-cdk-testing/framework-integ/test/aws-s3/test/integ.bucket-replication-use-custom-role.js.snapshot/ReplicationIntegDefaultTestDeployAssert2C07A074.assets.json

@@ -266,6 +266,18 @@ export interface IBucket extends IResource {
    */
   grantReadWrite(identity: iam.IGrantable, objectsKeyPattern?: any): iam.Grant;
 
+  /**
+   * Allows permissions for replication operation to bucket replication role.
+   *
+   * If an encryption key is used, permission to use the key for
+   * encrypt/decrypt will also be granted.
+   *
+   * @param identity The principal
+   * @param props The properties of the replication source and destination buckets.
+   * @returns The `iam.Grant` object, which represents the grant of permissions.
+   */
+  grantReplicationPermission(identity: iam.IGrantable, props: GrantReplicationPermissionProps): iam.Grant;
+
   /**
    * Allows unrestricted access to objects from this bucket.
    *
@@ -497,6 +509,45 @@ export interface BucketAttributes {
   readonly notificationsHandlerRole?: iam.IRole;
 }
 
+/**
+ * The properties for the destination bucket for granting replication permission.
+ */
+export interface GrantReplicationPermissionDestinationProps {
+  /**
+   * The destination bucket
+   */
+  readonly bucket: IBucket;
+
+  /**
+   * The KMS key to use for encryption if a destination bucket needs to be encrypted with a customer-managed KMS key.
+   *
+   * @default - no KMS key is used for replication.
+   */
+  readonly encryptionKey?: kms.IKey;
+}
+
+/**
+ * The properties for the destination bucket for granting replication permission.
+ */
+export interface GrantReplicationPermissionProps {
+  /**
+   * The KMS key used to decrypt objects in the source bucket for replication.
+   * **Required if** the source bucket is encrypted with a customer-managed KMS key.
+   *
+   * @default - it's assumed the source bucket is not encrypted with a customer-managed KMS key.
+   */
+  readonly sourceDecryptionKey?: kms.IKey;
+
+  /**
+   * The destination buckets for replication.
+   * Specify the KMS key to use for encryption if a destination bucket needs to be encrypted with a customer-managed KMS key.
+   * One or more destination buckets are required if replication configuration is enabled (i.e., `replicationRole` is specified).
+   *
+   * @default - empty array (valid only if the `replicationRole` property is NOT specified)
+   */
+  readonly destinations: GrantReplicationPermissionDestinationProps[];
+}
+
 /**
  * Represents an S3 Bucket.
  *
@@ -846,6 +897,60 @@ export abstract class BucketBase extends Resource implements IBucket {
       this.arnForObjects(objectsKeyPattern));
   }
 
+  /**
+   * Grant replication permission to a principal.
+   * This method allows the principal to perform replication operations on this bucket.
+   *
+   * Note that when calling this function for source or destination buckets that support KMS encryption,
+   * you need to specify the KMS key for encryption and the KMS key for decryption, respectively.
+   *
+   * @param identity The principal to grant replication permission to.
+   * @param props The properties of the replication source and destination buckets.
+   */
+  public grantReplicationPermission(identity: iam.IGrantable, props: GrantReplicationPermissionProps): iam.Grant {
+    if (props.destinations.length === 0) {
+      throw new ValidationError('At least one destination bucket must be specified in the destinations array', this);
+    }
+
+    // add permissions to the role
+    // @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/setting-repl-config-perm-overview.html
+    let result = this.grant(identity, ['s3:GetReplicationConfiguration', 's3:ListBucket'], [], Lazy.string({ produce: () => this.bucketArn }));
+
+    const g1 = this.grant(
+      identity,
+      ['s3:GetObjectVersionForReplication', 's3:GetObjectVersionAcl', 's3:GetObjectVersionTagging'],
+      [],
+      Lazy.string({ produce: () => this.arnForObjects('*') }),
+    );
+    result = result.combine(g1);
+
+    const destinationBuckets = props.destinations.map(destination => destination.bucket);
+    if (destinationBuckets.length > 0) {
+      const g2 = iam.Grant.addToPrincipalOrResource({
+        grantee: identity,
+        actions: ['s3:ReplicateObject', 's3:ReplicateDelete', 's3:ReplicateTags', 's3:ObjectOwnerOverrideToBucketOwner'],
+        resourceArns: destinationBuckets.map(bucket => Lazy.string({ produce: () => bucket.arnForObjects('*') })),
+        resource: this,
+      });
+      result = result.combine(g2);
+    }
+
+    props.destinations.forEach(destination => {
+      const g = destination.encryptionKey?.grantEncrypt(identity);
+      if (g !== undefined) {
+        result = result.combine(g);
+      }
+    });
+
+    // If KMS key encryption is enabled on the source bucket, configure the decrypt permissions.
+    const g3 = this.encryptionKey?.grantDecrypt(identity);
+    if (g3 !== undefined) {
+      result = result.combine(g3);
+    }
+
+    return result;
+  }
+
   /**
    * Allows unrestricted access to objects from this bucket.
    *
@@ -2841,42 +2946,20 @@ export class Bucket extends BucketBase {
       }
     });
 
-    const destinationBuckets = props.replicationRules.map(rule => rule.destination);
-    const kmsKeys = props.replicationRules.map(rule => rule.kmsKey).filter(kmsKey => kmsKey !== undefined) as kms.IKey[];
-
     let replicationRole: iam.IRole;
     if (!props.replicationRole) {
       replicationRole = new iam.Role(this, 'ReplicationRole', {
         assumedBy: new iam.ServicePrincipal('s3.amazonaws.com'),
         roleName: FeatureFlags.of(this).isEnabled(cxapi.SET_UNIQUE_REPLICATION_ROLE_NAME) ? PhysicalName.GENERATE_IF_NEEDED : 'CDKReplicationRole',
       });
 
-      // add permissions to the role
-      // @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/setting-repl-config-perm-overview.html
-      replicationRole.addToPrincipalPolicy(new iam.PolicyStatement({
-        actions: ['s3:GetReplicationConfiguration', 's3:ListBucket'],
-        resources: [Lazy.string({ produce: () => this.bucketArn })],
-        effect: iam.Effect.ALLOW,
-      }));
-      replicationRole.addToPrincipalPolicy(new iam.PolicyStatement({
-        actions: ['s3:GetObjectVersionForReplication', 's3:GetObjectVersionAcl', 's3:GetObjectVersionTagging'],
-        resources: [Lazy.string({ produce: () => this.arnForObjects('*') })],
-        effect: iam.Effect.ALLOW,
-      }));
-      if (destinationBuckets.length > 0) {
-        replicationRole.addToPrincipalPolicy(new iam.PolicyStatement({
-          actions: ['s3:ReplicateObject', 's3:ReplicateDelete', 's3:ReplicateTags', 's3:ObjectOwnerOverrideToBucketOwner'],
-          resources: destinationBuckets.map(bucket => bucket.arnForObjects('*')),
-          effect: iam.Effect.ALLOW,
-        }));
-      }
-
-      kmsKeys.forEach(kmsKey => {
-        kmsKey.grantEncrypt(replicationRole);
+      this.grantReplicationPermission(replicationRole, {
+        sourceDecryptionKey: props.encryptionKey,
+        destinations: props.replicationRules.map(rule => ({
+          encryptionKey: rule.kmsKey,
+          bucket: rule.destination,
+        })),
       });
-
-      // If KMS key encryption is enabled on the source bucket, configure the decrypt permissions.
-      this.encryptionKey?.grantDecrypt(replicationRole);
     } else {
       replicationRole = props.replicationRole;
     }