feat(cli): add ability to specify an external id for the deploy-role

packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/artifact-schema.ts

@@ -42,6 +42,13 @@ export interface AwsCloudFormationStackProperties {
    */
   readonly assumeRoleArn?: string;
 
+  /**
+   * External ID to use when assuming role for cloudformation deployments
+   *
+   * @default - No external ID
+   */
+  readonly assumeRoleExternalId?: string;
+
   /**
    * The role that is passed to CloudFormation to execute the change set
    *
@@ -149,4 +156,4 @@ export interface NestedCloudAssemblyProperties {
 export type ArtifactProperties = AwsCloudFormationStackProperties
 | AssetManifestProperties
 | TreeArtifactProperties
-| NestedCloudAssemblyProperties;
+| NestedCloudAssemblyProperties;

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -299,6 +299,10 @@
                     "description": "The role that needs to be assumed to deploy the stack (Default - No role is assumed (current credentials are used))",
                     "type": "string"
                 },
+                "assumeRoleExternalId": {
+                    "description": "External ID to use when assuming role for cloudformation deployments (Default - No external ID)",
+                    "type": "string"
+                },
                 "cloudFormationExecutionRoleArn": {
                     "description": "The role that is passed to CloudFormation to execute the change set (Default - No role is passed (currently assumed role/credentials are used))",
                     "type": "string"

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.version.json

@@ -1 +1 @@
-{"version":"12.0.0"}
+{"version":"13.0.0"}

packages/@aws-cdk/core/lib/stack-synthesizers/default-synthesizer.ts

@@ -98,6 +98,13 @@ export interface DefaultStackSynthesizerProps {
    */
   readonly imageAssetPublishingExternalId?: string;
 
+  /**
+   * External ID to use when assuming role for cloudformation deployments
+   *
+   * @default - No external ID
+   */
+  readonly deployRoleExternalId?: string;
+
   /**
    * The role to assume to initiate a deployment in this environment
    *
@@ -424,6 +431,7 @@ export class DefaultStackSynthesizer extends StackSynthesizer {
     const artifactId = this.writeAssetManifest(session);
 
     this.emitStackArtifact(this.stack, session, {
+      assumeRoleExternalId: this.props.deployRoleExternalId,
       assumeRoleArn: this._deployRoleArn,
       cloudFormationExecutionRoleArn: this._cloudFormationExecutionRoleArn,
       stackTemplateAssetObjectUrl: templateManifestUrl,

packages/@aws-cdk/core/lib/stack-synthesizers/stack-synthesizer.ts

@@ -86,6 +86,13 @@ export interface SynthesizeStackArtifactOptions {
    */
   readonly assumeRoleArn?: string;
 
+  /**
+   * The externalID to use with the assumeRoleArn
+   *
+   * @default - No externalID is used
+   */
+  readonly assumeRoleExternalId?: string;
+
   /**
    * The role that is passed to CloudFormation to execute the change set
    *
@@ -121,4 +128,4 @@ export interface SynthesizeStackArtifactOptions {
    * @default - Bootstrap stack version number looked up
    */
   readonly bootstrapStackVersionSsmParameter?: string;
-}
+}

packages/@aws-cdk/core/test/stack-synthesis/new-style-synthesis.test.ts

@@ -273,6 +273,26 @@ nodeunitShim({
     test.done();
   },
 
+  'customize deploy role externalId'(test: Test) {
+    // GIVEN
+    const myapp = new App();
+
+    // WHEN
+    const mystack = new Stack(myapp, 'mystack', {
+      synthesizer: new DefaultStackSynthesizer({
+        deployRoleExternalId: 'deploy-external-id',
+      }),
+    });
+
+    // THEN
+    const asm = myapp.synth();
+
+    const stackArtifact = asm.getStack(mystack.stackName);
+    expect(stackArtifact.assumeRoleExternalId).toEqual('deploy-external-id');
+
+    test.done();
+  },
+
   'synthesis with bucketPrefix'(test: Test) {
     // GIVEN
     const myapp = new App();

packages/@aws-cdk/cx-api/lib/artifacts/cloudformation-artifact.ts

@@ -61,6 +61,13 @@ export class CloudFormationStackArtifact extends CloudArtifact {
    */
   public readonly assumeRoleArn?: string;
 
+  /**
+   * External ID to use when assuming role for cloudformation deployments
+   *
+   * @default - No external ID
+   */
+  readonly assumeRoleExternalId?: string;
+
   /**
    * The role that is passed to CloudFormation to execute the change set
    *
@@ -121,6 +128,7 @@ export class CloudFormationStackArtifact extends CloudArtifact {
     // from the stack metadata
     this.tags = properties.tags ?? this.tagsFromMetadata();
     this.assumeRoleArn = properties.assumeRoleArn;
+    this.assumeRoleExternalId = properties.assumeRoleExternalId;
     this.cloudFormationExecutionRoleArn = properties.cloudFormationExecutionRoleArn;
     this.stackTemplateAssetObjectUrl = properties.stackTemplateAssetObjectUrl;
     this.requiresBootstrapStackVersion = properties.requiresBootstrapStackVersion;
@@ -165,4 +173,4 @@ export class CloudFormationStackArtifact extends CloudArtifact {
     }
     return ret;
   }
-}
+}

packages/aws-cdk/lib/api/cloudformation-deployments.ts

@@ -251,6 +251,7 @@ export class CloudFormationDeployments {
 
     const stackSdk = await this.sdkProvider.forEnvironment(resolvedEnvironment, mode, {
       assumeRoleArn: arns.assumeRoleArn,
+      assumeRoleExternalId: stack.assumeRoleExternalId,
     });
 
     return {