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-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;
@@ -408,12 +409,15 @@ export class Table extends Construct {
    * @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));
+    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));
+    iam.Permissions.grant({
+      principal,
+      actions,
+      resourceArns: [this.tableStreamArn],
+      scope: this,
+    });
   }
 
   /**

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

@@ -206,38 +206,40 @@ 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[]) {
+    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");
-
-    if (identity) {
-      identity.addToPolicy(new iam.PolicyStatement()
-        .addActions("ecr:GetAuthorizationToken", "logs:CreateLogStream", "logs:PutLogEvents")
-        .addAllResources());
-    }
+  public grantPull(principal?: iam.IPrincipal) {
+    this.grant(principal, "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage");
+
+    iam.Permissions.grant({
+      principal,
+      actions: ["ecr:GetAuthorizationToken", "logs:CreateLogStream", "logs:PutLogEvents"],
+      resourceArns: ['*'],
+      skipResourcePolicy: true,
+      scope: this,
+    });
   }
 
   /**
    * 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);
+    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

packages/@aws-cdk/aws-iam/lib/grant.ts

@@ -0,0 +1,129 @@
+import cdk = require('@aws-cdk/cdk');
+import { PolicyStatement } from "./policy-document";
+import { IPrincipal } from "./principals";
+
+/**
+ * Properties for a grant operation
+ */
+export interface GrantOptions {
+  /**
+   * The principal to grant to
+   *
+   * @default No work is done
+   */
+  principal: IPrincipal | undefined;
+
+  /**
+   * The actions to grant
+   */
+  actions: string[];
+
+  /**
+   * The resource ARNs to grant to
+   */
+  resourceArns: string[];
+
+  /**
+   * Adder to the resource policy
+   *
+   * Either 'scope' or 'resource' must be supplied.
+   *
+   * An error will be thrown if the policy could not be added to the principal,
+   * no resource is supplied given and `skipResourcePolicy` is false.
+   */
+  resource?: IResourceWithPolicy;
+
+  /**
+   * When referring to the resource in a resource policy, use this as ARN.
+   *
+   * (Depending on the resource type, this needs to be '*' in a resource policy).
+   *
+   * @default Same as regular resource ARNs
+   */
+  resourceSelfArns?: string[];
+
+  /**
+   * If we wanted to add to the resource policy but there is no resource, ignore the error.
+   *
+   * @default false
+   */
+  skipResourcePolicy?: boolean;
+
+  /**
+   * Construct to report warnings on in case grant could not be registered
+   *
+   * @default resource
+   */
+  scope?: cdk.IConstruct;
+}
+
+export class Permissions {
+  /**
+   * Helper function to implement grants.
+   *
+   * The pattern is the same every time. We try to add to the principal
+   * first, then add to the resource afterwards.
+   */
+  public static grant(options: GrantOptions): GrantResult {
+    let addedToPrincipal = false;
+    let addedToResource = false;
+
+    const scope = options.scope || options.resource;
+    if (!scope) {
+      throw new Error(`Either 'scope' or 'resource' must be supplied.`);
+    }
+
+    // One-iteration loop to be able to skip to end of function easily
+    do {
+      if (!options.principal) {
+        // tslint:disable-next-line:max-line-length
+        scope.node.addWarning(`Could not add grant for '${options.actions}' on '${options.resourceArns}' because the principal was not available. Add the permissions by hand.`);
+        break;
+      }
+
+      addedToPrincipal = options.principal.addToPolicy(new PolicyStatement()
+        .addActions(...options.actions)
+        .addResources(...options.resourceArns));
+
+      if (addedToPrincipal || options.skipResourcePolicy) { break; }
+
+      if (!options.resource) {
+        throw new Error('Could not add permissions to Principal without policy, and resource does not have policy either. Grant to a Role instead.');
+      }
+
+      options.resource.addToResourcePolicy(new PolicyStatement()
+        .addActions(...options.actions)
+        .addResources(...(options.resourceSelfArns || options.resourceArns))
+        .addPrincipal(options.principal));
+      addedToResource = true;
+
+    } while (false);
+
+    return { addedToPrincipal, addedToResource };
+  }
+}
+
+/**
+ * The result of the grant() operation
+ */
+export interface GrantResult {
+  /**
+   * The grant was added to the principal's policy
+   */
+  addedToPrincipal: boolean;
+
+  /**
+   * The grant was added to the resource policy
+   */
+  addedToResource: boolean;
+}
+
+/**
+ * A resource with a resource policy that can be added to
+ */
+export interface IResourceWithPolicy extends cdk.IConstruct {
+  /**
+   * Add a statement to the resource's resource policy
+   */
+  addToResourcePolicy(statement: PolicyStatement): void;
+}

packages/@aws-cdk/aws-iam/lib/group.ts

@@ -1,7 +1,8 @@
 import { Construct } from '@aws-cdk/cdk';
 import { CfnGroup } from './iam.generated';
-import { IPrincipal, Policy } from './policy';
-import { ArnPrincipal, PolicyPrincipal, PolicyStatement } from './policy-document';
+import { IIdentity } from './identity-base';
+import { Policy } from './policy';
+import { ArnPrincipal, PolicyStatement, PrincipalPolicyFragment } from './policy-document';
 import { User } from './user';
 import { AttachedPolicies, undefinedIfEmpty } from './util';
 
@@ -34,7 +35,8 @@ export interface GroupProps {
   path?: string;
 }
 
-export class Group extends Construct implements IPrincipal {
+export class Group extends Construct implements IIdentity {
+  public readonly assumeRoleAction: string = 'sts:AssumeRole';
   /**
    * The runtime name of this group.
    */
@@ -45,10 +47,7 @@ export class Group extends Construct implements IPrincipal {
    */
   public readonly groupArn: string;
 
-  /**
-   * An "AWS" policy principal that represents this group.
-   */
-  public readonly principal: PolicyPrincipal;
+  public readonly policyFragment: PrincipalPolicyFragment;
 
   private readonly managedPolicies: any[];
   private readonly attachedPolicies = new AttachedPolicies();
@@ -67,7 +66,7 @@ export class Group extends Construct implements IPrincipal {
 
     this.groupName = group.groupName;
     this.groupArn = group.groupArn;
-    this.principal = new ArnPrincipal(this.groupArn);
+    this.policyFragment = new ArnPrincipal(this.groupArn).policyFragment;
   }
 
   /**
@@ -97,12 +96,13 @@ export class Group extends Construct implements IPrincipal {
   /**
    * Adds an IAM statement to the default policy.
    */
-  public addToPolicy(statement: PolicyStatement) {
+  public addToPolicy(statement: PolicyStatement): boolean {
     if (!this.defaultPolicy) {
       this.defaultPolicy = new Policy(this, 'DefaultPolicy');
       this.defaultPolicy.attachToGroup(this);
     }
 
     this.defaultPolicy.addStatement(statement);
+    return true;
   }
 }

packages/@aws-cdk/aws-iam/lib/identity-base.ts

@@ -0,0 +1,20 @@
+import { Policy } from "./policy";
+import { IPrincipal } from "./principals";
+
+/**
+ * A construct that represents an IAM principal, such as a user, group or role.
+ */
+export interface IIdentity extends IPrincipal {
+  /**
+   * Attaches an inline policy to this principal.
+   * This is the same as calling `policy.addToXxx(principal)`.
+   * @param policy The policy resource to attach to this principal.
+   */
+  attachInlinePolicy(policy: Policy): void;
+
+  /**
+   * Attaches a managed policy to this principal.
+   * @param arn The ARN of the managed policy
+   */
+  attachManagedPolicy(arn: string): void;
+}

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

@@ -5,6 +5,9 @@ export * from './policy';
 export * from './user';
 export * from './group';
 export * from './lazy-role';
+export * from './principals';
+export * from './identity-base';
+export * from './grant';
 
 // AWS::IAM CloudFormation Resources:
 export * from './iam.generated';