feat(aws-iam): grants support non-identity principals

packages/@aws-cdk/aws-cloudformation/test/test.pipeline-actions.ts

@@ -363,9 +363,10 @@ class RoleDouble extends iam.Role {
     super(scope, id, props);
   }
 
-  public addToPolicy(statement: iam.PolicyStatement) {
+  public addToPolicy(statement: iam.PolicyStatement): boolean {
     super.addToPolicy(statement);
     this.statements.push(statement);
+    return true;
   }
 }
 

packages/@aws-cdk/aws-cloudwatch/lib/metric.ts

@@ -85,14 +85,14 @@ export class Metric {
   /**
    * Grant permissions to the given identity to write metrics.
    *
-   * @param identity The IAM identity to give permissions to.
+   * @param principal The IAM identity to give permissions to.
    */
-  public static grantPutMetricData(identity?: iam.IPrincipal) {
-    if (!identity) { return; }
-
-    identity.addToPolicy(new iam.PolicyStatement()
-      .addAllResources()
-      .addAction("cloudwatch:PutMetricData"));
+  public static grantPutMetricData(principal?: iam.IPrincipal) {
+    if (principal) {
+      principal.addToPolicy(new iam.PolicyStatement()
+        .addAction('cloudwatch:PutMetricData')
+        .addAllResources());
+    }
   }
 
   public readonly dimensions?: DimensionHash;

packages/@aws-cdk/aws-codepipeline-api/lib/action.ts

@@ -62,14 +62,14 @@ export interface IPipeline extends cdk.IConstruct, events.IEventRuleTarget {
    *
    * @param identity the IAM Identity to grant the permissions to
    */
-  grantBucketRead(identity?: iam.IPrincipal): void;
+  grantBucketRead(identity?: iam.IPrincipal): iam.GrantResult;
 
   /**
    * Grants read & write permissions to the Pipeline's S3 Bucket to the given Identity.
    *
    * @param identity the IAM Identity to grant the permissions to
    */
-  grantBucketReadWrite(identity?: iam.IPrincipal): void;
+  grantBucketReadWrite(identity?: iam.IPrincipal): iam.GrantResult;
 }
 
 /**

packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts

@@ -292,12 +292,12 @@ export class Pipeline extends cdk.Construct implements cpapi.IPipeline {
     return this.stages.length;
   }
 
-  public grantBucketRead(identity?: iam.IPrincipal): void {
-    this.artifactBucket.grantRead(identity);
+  public grantBucketRead(identity?: iam.IPrincipal): iam.GrantResult {
+    return this.artifactBucket.grantRead(identity);
   }
 
-  public grantBucketReadWrite(identity?: iam.IPrincipal): void {
-    this.artifactBucket.grantReadWrite(identity);
+  public grantBucketReadWrite(identity?: iam.IPrincipal): iam.GrantResult {
+    return this.artifactBucket.grantReadWrite(identity);
   }
 
   /**

packages/@aws-cdk/aws-dynamodb/lib/table.ts

@@ -1,5 +1,6 @@
 import appscaling = require('@aws-cdk/aws-applicationautoscaling');
 import iam = require('@aws-cdk/aws-iam');
+import { PolicyStatement } from '@aws-cdk/aws-iam';
 import cdk = require('@aws-cdk/cdk');
 import { Construct, Token } from '@aws-cdk/cdk';
 import { CfnTable } from './dynamodb.generated';
@@ -180,11 +181,11 @@ export class Table extends Construct {
    */
   public static grantListStreams(principal?: iam.IPrincipal): void {
     if (principal) {
-      principal.addToPolicy(new iam.PolicyStatement()
+      principal.addToPolicy(new PolicyStatement()
         .addAction('dynamodb:ListStreams')
-        .addResource("*"));
+        .addAllResources());
     }
-  }
+ }
 
   public readonly tableArn: string;
   public readonly tableName: string;
@@ -407,13 +408,16 @@ export class Table extends Construct {
    * @param principal The principal (no-op if undefined)
    * @param actions The set of actions to allow (i.e. "dynamodb:PutItem", "dynamodb:GetItem", ...)
    */
-  public grant(principal?: iam.IPrincipal, ...actions: string[]) {
-    if (!principal) {
-      return;
-    }
-    principal.addToPolicy(new iam.PolicyStatement()
-      .addResources(this.tableArn, new cdk.Token(() => this.hasIndex ? `${this.tableArn}/index/*` : new cdk.Aws().noValue).toString())
-      .addActions(...actions));
+  public grant(principal?: iam.IPrincipal, ...actions: string[]): iam.GrantResult {
+    return iam.Permissions.grant({
+      principal,
+      actions,
+      resourceArns: [
+        this.tableArn,
+        new cdk.Token(() => this.hasIndex ? `${this.tableArn}/index/*` : new cdk.Aws().noValue).toString()
+      ],
+      scope: this,
+    });
   }
 
   /**
@@ -423,12 +427,12 @@ export class Table extends Construct {
    * @param actions The set of actions to allow (i.e. "dynamodb:DescribeStream", "dynamodb:GetRecords", ...)
    */
   public grantStream(principal?: iam.IPrincipal, ...actions: string[]) {
-    if (!principal) {
-      return;
-    }
-    principal.addToPolicy(new iam.PolicyStatement()
-      .addResource(this.tableStreamArn)
-      .addActions(...actions));
+    return iam.Permissions.grant({
+      principal,
+      actions,
+      resourceArns: [this.tableStreamArn],
+      scope: this,
+    });
   }
 
   /**
@@ -437,7 +441,7 @@ export class Table extends Construct {
    * @param principal The principal to grant access to
    */
   public grantReadData(principal?: iam.IPrincipal) {
-    this.grant(principal, ...READ_DATA_ACTIONS);
+    return this.grant(principal, ...READ_DATA_ACTIONS);
   }
 
   /**
@@ -447,7 +451,7 @@ export class Table extends Construct {
    * @param principal The principal to grant access to
    */
   public grantStreamRead(principal?: iam.IPrincipal) {
-    this.grantStream(principal, ...READ_STREAM_DATA_ACTIONS);
+    return this.grantStream(principal, ...READ_STREAM_DATA_ACTIONS);
   }
 
   /**
@@ -456,7 +460,7 @@ export class Table extends Construct {
    * @param principal The principal to grant access to
    */
   public grantWriteData(principal?: iam.IPrincipal) {
-    this.grant(principal, ...WRITE_DATA_ACTIONS);
+    return this.grant(principal, ...WRITE_DATA_ACTIONS);
   }
 
   /**
@@ -466,15 +470,15 @@ export class Table extends Construct {
    * @param principal The principal to grant access to
    */
   public grantReadWriteData(principal?: iam.IPrincipal) {
-    this.grant(principal, ...READ_DATA_ACTIONS, ...WRITE_DATA_ACTIONS);
+    return this.grant(principal, ...READ_DATA_ACTIONS, ...WRITE_DATA_ACTIONS);
   }
 
   /**
    * Permits all DynamoDB operations ("dynamodb:*") to an IAM principal.
    * @param principal The principal to grant access to
    */
   public grantFullAccess(principal?: iam.IPrincipal) {
-    this.grant(principal, 'dynamodb:*');
+    return this.grant(principal, 'dynamodb:*');
   }
 
   /**

packages/@aws-cdk/aws-ecr/lib/repository-ref.ts

@@ -51,17 +51,17 @@ export interface IRepository extends cdk.IConstruct {
   /**
    * Grant the given principal identity permissions to perform the actions on this repository
    */
-  grant(identity?: iam.IPrincipal, ...actions: string[]): void;
+  grant(identity?: iam.IPrincipal, ...actions: string[]): iam.GrantResult;
 
   /**
    * Grant the given identity permissions to pull images in this repository.
    */
-  grantPull(identity?: iam.IPrincipal): void;
+  grantPull(identity?: iam.IPrincipal): iam.GrantResult;
 
   /**
    * Grant the given identity permissions to pull and push images to this repository.
    */
-  grantPullPush(identity?: iam.IPrincipal): void;
+  grantPullPush(identity?: iam.IPrincipal): iam.GrantResult;
 
   /**
    * Defines an AWS CloudWatch event rule that can trigger a target when an image is pushed to this
@@ -206,38 +206,41 @@ export abstract class RepositoryBase extends cdk.Construct implements IRepositor
   /**
    * Grant the given principal identity permissions to perform the actions on this repository
    */
-  public grant(identity?: iam.IPrincipal, ...actions: string[]) {
-    if (!identity) {
-      return;
-    }
-    identity.addToPolicy(new iam.PolicyStatement()
-      .addResource(this.repositoryArn)
-      .addActions(...actions));
+  public grant(principal?: iam.IPrincipal, ...actions: string[]) {
+    return iam.Permissions.grant({
+      principal,
+      actions,
+      resourceArns: [this.repositoryArn],
+      resource: this,
+    });
   }
 
   /**
    * Grant the given identity permissions to use the images in this repository
    */
-  public grantPull(identity?: iam.IPrincipal) {
-    this.grant(identity, "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage");
+  public grantPull(principal?: iam.IPrincipal) {
+    const ret = this.grant(principal, "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage");
+
+    iam.Permissions.tryGrantOnIdentity({
+      principal,
+      actions: ["ecr:GetAuthorizationToken"],
+      resourceArns: ['*'],
+      scope: this,
+    });
 
-    if (identity) {
-      identity.addToPolicy(new iam.PolicyStatement()
-        .addActions("ecr:GetAuthorizationToken", "logs:CreateLogStream", "logs:PutLogEvents")
-        .addAllResources());
-    }
+    return ret;
   }
 
   /**
    * Grant the given identity permissions to pull and push images to this repository.
    */
   public grantPullPush(identity?: iam.IPrincipal) {
-      this.grantPull(identity);
-      this.grant(identity,
-        "ecr:PutImage",
-        "ecr:InitiateLayerUpload",
-        "ecr:UploadLayerPart",
-        "ecr:CompleteLayerUpload");
+    this.grantPull(identity);
+    return this.grant(identity,
+      "ecr:PutImage",
+      "ecr:InitiateLayerUpload",
+      "ecr:UploadLayerPart",
+      "ecr:CompleteLayerUpload");
   }
 }
 

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

@@ -22,6 +22,14 @@ an `ExternalId` works like this:
 
 [supplying an external ID](test/example.external-id.lit.ts)
 
+### Principals vs Identities
+
+When we say *Principal*, we mean an entity you grant permissions to. This
+entity can be an AWS Service, a Role, or something more abstract such as "all
+users in this account" or even "all users in this organization". An
+*Identity* is an IAM representing a single IAM entity that can have
+a policy attached, one of `Role`, `User`, or `Group`.
+
 ### IAM Principals
 
 When defining policy statements as part of an AssumeRole policy or as part of a