feat(servicecatalogappregistry): add sharing of applications and attribute groups

packages/@aws-cdk/aws-ram/package.json

@@ -99,7 +99,7 @@
   "engines": {
     "node": ">= 14.15.0"
   },
-  "stability": "experimental",
+  "stability": "stable",
   "maturity": "cfn-only",
   "awscdkio": {
     "announce": false

packages/@aws-cdk/aws-servicecatalogappregistry/README.md

@@ -124,3 +124,57 @@ const myStack = new Stack(app, 'MyStack');
 declare const application: appreg.Application;
 application.associateStack(myStack);
 ```
+
+## Sharing
+
+You can share your AppRegistry applications and attribute groups with AWS Organizations, Organizational Units (OUs), AWS accounts within an organization, as well as IAM roles and users. AppRegistry requires that AWS Organizations is enabled in an account before deploying a share of an application or attribute group.
+
+### Sharing an application
+
+```ts
+import * as iam from '@aws-cdk/aws-iam';
+declare const application: appreg.Application;
+declare const myRole: iam.IRole;
+declare const myUser: iam.IUser;
+application.shareResource({
+  accounts: ['123456789012'],
+  organizations: ['arn:aws:organizations::123456789012:organization/o-my-org-id'],
+  roles: [myRole],
+  users: [myUser]
+});
+```
+
+E.g., sharing an application with multiple accounts:
+
+```ts
+import * as iam from '@aws-cdk/aws-iam';
+declare const application: appreg.Application;
+application.shareResource({
+  accounts: ['123456789012', '234567890123'],
+});
+```
+
+### Sharing an attribute group
+
+```ts
+import * as iam from '@aws-cdk/aws-iam';
+declare const attributeGroup: appreg.AttributeGroup;
+declare const myRole: iam.IRole;
+declare const myUser: iam.IUser;
+attributeGroup.shareResource({
+  accounts: ['123456789012'],
+  organizations: ['arn:aws:organizations::123456789012:organization/o-my-org-id'],
+  roles: [myRole],
+  users: [myUser]
+});
+```
+
+E.g., sharing an attribute group with multiple accounts:
+
+```ts
+import * as iam from '@aws-cdk/aws-iam';
+declare const attributeGroup: appreg.AttributeGroup;
+attributeGroup.shareResource({
+  accounts: ['123456789012', '234567890123'],
+});
+```

packages/@aws-cdk/aws-servicecatalogappregistry/lib/application.ts

@@ -1,7 +1,9 @@
-import * as crypto from 'crypto';
+import { CfnResourceShare } from '@aws-cdk/aws-ram';
 import * as cdk from '@aws-cdk/core';
+import { Names } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { IAttributeGroup } from './attribute-group';
+import { getPrincipalsforSharing, hashValues, ShareOptions } from './common';
 import { InputValidator } from './private/validation';
 import { CfnApplication, CfnAttributeGroupAssociation, CfnResourceAssociation } from './servicecatalogappregistry.generated';
 
@@ -32,6 +34,12 @@ export interface IApplication extends cdk.IResource {
    * @param stack a CFN stack
    */
   associateStack(stack: cdk.Stack): void;
+
+  /**
+   * Share this resource with other IAM entities, accounts, or OUs.
+   * @param shareOptions The options for the share.
+   */
+  shareResource(shareOptions: ShareOptions): void;
 }
 
 /**
@@ -88,6 +96,22 @@ abstract class ApplicationBase extends cdk.Resource implements IApplication {
     }
   }
 
+  /**
+   * Share application resource with target accounts.
+   * The application will become available to end users within targets.
+   * @param shareOptions The options for the share.
+   */
+  public shareResource(shareOptions: ShareOptions): void {
+    const principals = getPrincipalsforSharing(shareOptions);
+    const shareName = `RAMShare${Names.uniqueResourceName(this, {})}`;
+    new CfnResourceShare(this, shareName, {
+      name: shareName,
+      allowExternalPrincipals: shareOptions.allowExternalPrincipals ?? true,
+      principals: principals,
+      resourceArns: [this.applicationArn],
+    });
+  }
+
   /**
    * Create a unique id
    */
@@ -156,12 +180,3 @@ export class Application extends ApplicationBase {
     InputValidator.validateLength(this.node.path, 'application description', 0, 1024, props.description);
   }
 }
-
-/**
- * Generates a unique hash identfifer using SHA256 encryption algorithm
- */
-function hashValues(...values: string[]): string {
-  const sha256 = crypto.createHash('sha256');
-  values.forEach(val => sha256.update(val));
-  return sha256.digest('hex').slice(0, 12);
-}

packages/@aws-cdk/aws-servicecatalogappregistry/lib/attribute-group.ts

@@ -1,7 +1,10 @@
+import { CfnResourceShare } from '@aws-cdk/aws-ram';
 import * as cdk from '@aws-cdk/core';
+import { getPrincipalsforSharing, ShareOptions } from './common';
 import { Construct } from 'constructs';
 import { InputValidator } from './private/validation';
 import { CfnAttributeGroup } from './servicecatalogappregistry.generated';
+import { Names } from '@aws-cdk/core';
 
 /**
  * A Service Catalog AppRegistry Attribute Group.
@@ -18,6 +21,12 @@ export interface IAttributeGroup extends cdk.IResource {
    * @attribute
    */
   readonly attributeGroupId: string;
+
+  /**
+   * Share the attribute group resource with other IAM entities, accounts, or OUs.
+   * @param shareOptions The options for the share.
+   */
+  shareResource(shareOptions: ShareOptions): void;
 }
 
 /**
@@ -45,6 +54,17 @@ export interface AttributeGroupProps {
 abstract class AttributeGroupBase extends cdk.Resource implements IAttributeGroup {
   public abstract readonly attributeGroupArn: string;
   public abstract readonly attributeGroupId: string;
+
+  public shareResource(shareOptions: ShareOptions): void {
+    const principals = getPrincipalsforSharing(shareOptions);
+    const shareName = `RAMShare${Names.uniqueResourceName(this, {})}`;
+    new CfnResourceShare(this, shareName, {
+      name: shareName,
+      allowExternalPrincipals: shareOptions.allowExternalPrincipals ?? true,
+      principals: principals,
+      resourceArns: [this.attributeGroupArn],
+    });
+  }
 }
 
 /**

packages/@aws-cdk/aws-servicecatalogappregistry/lib/common.ts

@@ -0,0 +1,73 @@
+import * as crypto from 'crypto';
+import * as iam from '@aws-cdk/aws-iam';
+
+/**
+ * The options that are passed into a share of an Application or Attribute Group.
+ */
+export interface ShareOptions {
+  /**
+   * When set to true, this allows sharing of applications and attribute groups
+   * with accounts outside of your AWS Organization. When set to false, sharing
+   * is restricted to only accounts and principals which belong to the organization.
+   *
+   * @default true
+   */
+  readonly allowExternalPrincipals?: boolean;
+
+  /**
+   * A list of AWS accounts that the application will be shared with.
+   *
+   * @default - No accounts specified for share
+   */
+  readonly accounts?: string[];
+
+  /**
+   * A list of AWS Organization or Organizational Units (OUs) ARNs that the application will be shared with.
+   *
+   * @default - No AWS Organizations or OUs specified for share
+   */
+  readonly organizations?: string[];
+
+  /**
+   * A list of AWS IAM roles that the application will be shared with.
+   *
+   * @default - No IAM roles specified for share
+   */
+  readonly roles?: iam.IRole[];
+
+  /**
+   * A list of AWS IAM users that the application will be shared with.
+   *
+   * @default - No IAM Users specified for share
+   */
+  readonly users?: iam.IUser[];
+}
+
+/**
+ * Generates a unique hash identfifer using SHA256 encryption algorithm.
+ */
+export function hashValues(...values: string[]): string {
+  const sha256 = crypto.createHash('sha256');
+  values.forEach(val => sha256.update(val));
+  return sha256.digest('hex').slice(0, 12);
+}
+
+/**
+ * Reformats share targets into a collapsed list necessary for handler.
+ * @param options The share target options
+ * @returns flat list of target ARNs
+ */
+export function getPrincipalsforSharing(options: ShareOptions): string[] {
+  const principals = [
+    ...options.accounts ?? [],
+    ...options.organizations ?? [],
+    ...options.users ? options.users.map(user => user.userArn) : [],
+    ...options.roles ? options.roles.map(role => role.roleArn) : [],
+  ];
+
+  if (principals.length == 0) {
+    throw new Error('An entity must be provided for the share');
+  }
+
+  return principals;
+}

packages/@aws-cdk/aws-servicecatalogappregistry/lib/index.ts

@@ -1,5 +1,6 @@
 export * from './application';
 export * from './attribute-group';
+export * from './common';
 
 // AWS::ServiceCatalogAppRegistry CloudFormation Resources:
 export * from './servicecatalogappregistry.generated';

packages/@aws-cdk/aws-servicecatalogappregistry/package.json

@@ -92,10 +92,14 @@
   },
   "dependencies": {
     "@aws-cdk/core": "0.0.0",
+    "@aws-cdk/aws-iam": "0.0.0",
+    "@aws-cdk/aws-ram": "0.0.0",
     "constructs": "^10.0.0"
   },
   "peerDependencies": {
     "@aws-cdk/core": "0.0.0",
+    "@aws-cdk/aws-iam": "0.0.0",
+    "@aws-cdk/aws-ram": "0.0.0",
     "constructs": "^10.0.0"
   },
   "engines": {

packages/@aws-cdk/aws-servicecatalogappregistry/test/application.integ.snapshot/cdk.out

@@ -1 +1 @@
-{"version":"17.0.0"}
+{"version":"20.0.0"}

packages/@aws-cdk/aws-servicecatalogappregistry/test/application.integ.snapshot/integ-servicecatalogappregistry-application.assets.json

@@ -1,15 +1,15 @@
 {
-  "version": "17.0.0",
+  "version": "20.0.0",
   "files": {
-    "d561cf6d9aa2d98689712d70accb1c3f56f2a54d6cbb1268d35bd72e05675791": {
+    "d38cefd07b083dfb1814889c0bbb741d1a53333b08007b245296279d3e3510a2": {
       "source": {
         "path": "integ-servicecatalogappregistry-application.template.json",
         "packaging": "file"
       },
       "destinations": {
         "current_account-current_region": {
           "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
-          "objectKey": "d561cf6d9aa2d98689712d70accb1c3f56f2a54d6cbb1268d35bd72e05675791.json",
+          "objectKey": "d38cefd07b083dfb1814889c0bbb741d1a53333b08007b245296279d3e3510a2.json",
           "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
         }
       }

packages/@aws-cdk/aws-servicecatalogappregistry/test/application.integ.snapshot/integ-servicecatalogappregistry-application.template.json

@@ -39,6 +39,29 @@
     }
    }
   },
+  "TestApplicationRAMShareintegservicecatalogappregistryapplicationTestApplicationF7821DB233482C38": {
+   "Type": "AWS::RAM::ResourceShare",
+   "Properties": {
+    "Name": "RAMShareintegservicecatalogappregistryapplicationTestApplicationF7821DB2",
+    "AllowExternalPrincipals": true,
+    "Principals": [
+     {
+      "Fn::GetAtt": [
+       "MyRoleF48FFE04",
+       "Arn"
+      ]
+     }
+    ],
+    "ResourceArns": [
+     {
+      "Fn::GetAtt": [
+       "TestApplication2FBC585F",
+       "Arn"
+      ]
+     }
+    ]
+   }
+  },
   "TestAttributeGroupB1CB284F": {
    "Type": "AWS::ServiceCatalogAppRegistry::AttributeGroup",
    "Properties": {
@@ -61,6 +84,38 @@
     "Name": "myAttributeGroupTest",
     "Description": "my attribute group description"
    }
+  },
+  "MyRoleF48FFE04": {
+   "Type": "AWS::IAM::Role",
+   "Properties": {
+    "AssumeRolePolicyDocument": {
+     "Statement": [
+      {
+       "Action": "sts:AssumeRole",
+       "Effect": "Allow",
+       "Principal": {
+        "AWS": {
+         "Fn::Join": [
+          "",
+          [
+           "arn:",
+           {
+            "Ref": "AWS::Partition"
+           },
+           ":iam::",
+           {
+            "Ref": "AWS::AccountId"
+           },
+           ":root"
+          ]
+         ]
+        }
+       }
+      }
+     ],
+     "Version": "2012-10-17"
+    }
+   }
   }
  }
 }

packages/@aws-cdk/aws-servicecatalogappregistry/test/application.integ.snapshot/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "17.0.0",
+  "version": "20.0.0",
   "artifacts": {
     "Tree": {
       "type": "cdk:tree",
@@ -33,11 +33,32 @@
             "data": "TestApplicationAttributeGroupAssociation4ba7f5842818B8EE1C6F"
           }
         ],
+        "/integ-servicecatalogappregistry-application/TestApplication/RAMShareintegservicecatalogappregistryapplicationTestApplicationF7821DB2": [
+          {
+            "type": "aws:cdk:logicalId",
+            "data": "TestApplicationRAMShareintegservicecatalogappregistryapplicationTestApplicationF7821DB233482C38"
+          }
+        ],
         "/integ-servicecatalogappregistry-application/TestAttributeGroup/Resource": [
           {
             "type": "aws:cdk:logicalId",
             "data": "TestAttributeGroupB1CB284F"
           }
+        ],
+        "/integ-servicecatalogappregistry-application/MyRole/Resource": [
+          {
+            "type": "aws:cdk:logicalId",
+            "data": "MyRoleF48FFE04"
+          }
+        ],
+        "TestApplicationRAMShareb83647b4f06a5A88B554": [
+          {
+            "type": "aws:cdk:logicalId",
+            "data": "TestApplicationRAMShareb83647b4f06a5A88B554",
+            "trace": [
+              "!!DESTRUCTIVE_CHANGES: WILL_DESTROY"
+            ]
+          }
         ]
       },
       "displayName": "integ-servicecatalogappregistry-application"