feat(iam): add arbitrary conditions to existing principals

allowed-breaking-changes.txt

@@ -41,3 +41,8 @@ change-return-type:@aws-cdk/aws-lambda-destinations.LambdaDestination.bind
 change-return-type:@aws-cdk/aws-lambda-destinations.SnsDestination.bind
 change-return-type:@aws-cdk/aws-lambda-destinations.SqsDestination.bind
 removed:@aws-cdk/cdk-assets-schema.DockerImageDestination.imageUri
+incompatible-argument:@aws-cdk/aws-iam.FederatedPrincipal.<initializer>
+incompatible-argument:@aws-cdk/aws-iam.PolicyStatement.addCondition
+incompatible-argument:@aws-cdk/aws-iam.PolicyStatement.addConditions
+incompatible-argument:@aws-cdk/aws-iam.PolicyStatement.addFederatedPrincipal
+incompatible-argument:@aws-cdk/aws-iam.PrincipalPolicyFragment.<initializer>

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

@@ -188,6 +188,16 @@ const role = new iam.Role(this, 'MyRole', {
 });
 ```
 
+The `PrincipalWithConditions` class can be used to add conditions to a
+principal, especially those that don't take a `conditions` parameter in their
+constructor. The `principal.withConditions()` method can be used to create a
+`PrincipalWithConditions` from an existing principal, for example:
+
+```ts
+const principal = new iam.AccountPrincipal('123456789000')
+  .withConditions({ StringEquals: { foo: "baz" } });
+```
+
 ### Parsing JSON Policy Documents
 
 The `PolicyDocument.fromJson` and `PolicyStatement.fromJson` static methods can be used to parse JSON objects. For example:

packages/@aws-cdk/aws-iam/lib/policy-statement.ts

@@ -145,7 +145,7 @@ export class PolicyStatement {
     this.addPrincipals(new ServicePrincipal(service, opts));
   }
 
-  public addFederatedPrincipal(federated: any, conditions: {[key: string]: any}) {
+  public addFederatedPrincipal(federated: any, conditions: Conditions) {
     this.addPrincipals(new FederatedPrincipal(federated, conditions));
   }
 
@@ -200,15 +200,15 @@ export class PolicyStatement {
   /**
    * Add a condition to the Policy
    */
-  public addCondition(key: string, value: any) {
+  public addCondition(key: string, value: Condition) {
     const existingValue = this.condition[key];
     this.condition[key] = existingValue ? { ...existingValue, ...value } : value;
   }
 
   /**
    * Add multiple conditions to the Policy
    */
-  public addConditions(conditions: {[key: string]: any}) {
+  public addConditions(conditions: Conditions) {
     Object.keys(conditions).map(key => {
       this.addCondition(key, conditions[key]);
     });
@@ -303,6 +303,24 @@ export enum Effect {
   DENY = 'Deny',
 }
 
+/**
+ * Condition for when an IAM policy is in effect. Maps from the keys in a request's context to
+ * a string value or array of string values. See the Conditions interface for more details.
+ */
+export type Condition = Record<string, any>;
+
+/**
+ * Conditions for when an IAM Policy is in effect, specified in the following structure:
+ *
+ * `{ "Operator": { "keyInRequestContext": "value" } }`
+ *
+ * The value can be either a single string value or an array of string values.
+ *
+ * For more information, including which operators are supported, see [the IAM
+ * documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
+ */
+export type Conditions = Record<string, Condition>;
+
 /**
  * Interface for creating a policy statement
  */
@@ -398,7 +416,7 @@ class JsonPrincipal extends PrincipalBase {
 
     this.policyFragment = {
       principalJson: json,
-      conditions: []
+      conditions: {}
     };
   }
 }

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

@@ -1,6 +1,6 @@
 import * as cdk from '@aws-cdk/core';
 import { Default, RegionInfo } from '@aws-cdk/region-info';
-import { PolicyStatement } from './policy-statement';
+import { Condition, Conditions, PolicyStatement } from './policy-statement';
 import { mergePrincipal } from './util';
 
 /**
@@ -78,10 +78,108 @@ export abstract class PrincipalBase implements IPrincipal {
     return JSON.stringify(this.policyFragment.principalJson);
   }
 
+  /**
+   * JSON-ify the principal
+   *
+   * Used when JSON.stringify() is called
+   */
+  public toJSON() {
+    // Have to implement toJSON() because the default will lead to infinite recursion.
+    return this.policyFragment.principalJson;
+  }
+
+  /**
+   * Returns a new PrincipalWithConditions using this principal as the base, with the
+   * passed conditions added.
+   *
+   * When there is a value for the same operator and key in both the principal and the
+   * conditions parameter, the value from the conditions parameter will be used.
+   *
+   * @returns a new PrincipalWithConditions object.
+   */
+  public withConditions(conditions: Conditions): IPrincipal {
+    return new PrincipalWithConditions(this, conditions);
+  }
+}
+
+/**
+ * An IAM principal with additional conditions specifying when the policy is in effect.
+ *
+ * For more information about conditions, see:
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html
+ */
+export class PrincipalWithConditions implements IPrincipal {
+  public readonly grantPrincipal: IPrincipal = this;
+  public readonly assumeRoleAction: string = this.principal.assumeRoleAction;
+  private additionalConditions: Conditions;
+
+  constructor(
+    private readonly principal: IPrincipal,
+    conditions: Conditions,
+  ) {
+    this.additionalConditions = conditions;
+  }
+
+  /**
+   * Add a condition to the principal
+   */
+  public addCondition(key: string, value: Condition) {
+    const existingValue = this.conditions[key];
+    this.conditions[key] = existingValue ? { ...existingValue, ...value } : value;
+  }
+
+  /**
+   * Adds multiple conditions to the principal
+   *
+   * Values from the conditions parameter will overwrite existing values with the same operator
+   * and key.
+   */
+  public addConditions(conditions: Conditions) {
+    Object.entries(conditions).forEach(([key, value]) => {
+      this.addCondition(key, value);
+    });
+  }
+
+  /**
+   * The conditions under which the policy is in effect.
+   * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
+   */
+  public get conditions() {
+    return this.mergeConditions(this.principal.policyFragment.conditions, this.additionalConditions);
+  }
+
+  public get policyFragment(): PrincipalPolicyFragment {
+    return new PrincipalPolicyFragment(this.principal.policyFragment.principalJson, this.conditions);
+  }
+
+  public addToPolicy(statement: PolicyStatement): boolean {
+    return this.principal.addToPolicy(statement);
+  }
+
+  public toString() {
+    return this.principal.toString();
+  }
+
+  /**
+   * JSON-ify the principal
+   *
+   * Used when JSON.stringify() is called
+   */
   public toJSON() {
     // Have to implement toJSON() because the default will lead to infinite recursion.
     return this.policyFragment.principalJson;
   }
+
+  private mergeConditions(principalConditions: Conditions, additionalConditions: Conditions): Conditions {
+    const mergedConditions: Conditions = {};
+    Object.entries(principalConditions).forEach(([operator, condition]) => {
+      mergedConditions[operator] = condition;
+    });
+    Object.entries(additionalConditions).forEach(([operator, condition]) => {
+      mergedConditions[operator] = { ...mergedConditions[operator], ...condition };
+    });
+    return mergedConditions;
+  }
 }
 
 /**
@@ -93,7 +191,11 @@ export abstract class PrincipalBase implements IPrincipal {
 export class PrincipalPolicyFragment {
   constructor(
     public readonly principalJson: { [key: string]: string[] },
-    public readonly conditions: { [key: string]: any } = { }) {
+    /**
+     * The conditions under which the policy is in effect.
+     * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
+     */
+    public readonly conditions: Conditions = {}) {
   }
 }
 
@@ -103,7 +205,7 @@ export class ArnPrincipal extends PrincipalBase {
   }
 
   public get policyFragment(): PrincipalPolicyFragment {
-    return new PrincipalPolicyFragment({ AWS: [ this.arn ] });
+    return new PrincipalPolicyFragment({ AWS: [this.arn] });
   }
 
   public toString() {
@@ -200,7 +302,7 @@ export class CanonicalUserPrincipal extends PrincipalBase {
   }
 
   public get policyFragment(): PrincipalPolicyFragment {
-    return new PrincipalPolicyFragment({ CanonicalUser: [ this.canonicalUserId ] });
+    return new PrincipalPolicyFragment({ CanonicalUser: [this.canonicalUserId] });
   }
 
   public toString() {
@@ -213,15 +315,19 @@ export class FederatedPrincipal extends PrincipalBase {
 
   constructor(
     public readonly federated: string,
-    public readonly conditions: {[key: string]: any},
+    /**
+     * The conditions under which the policy is in effect.
+     * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
+     */
+    public readonly conditions: Conditions,
     assumeRoleAction: string = 'sts:AssumeRole') {
     super();
 
     this.assumeRoleAction = assumeRoleAction;
   }
 
   public get policyFragment(): PrincipalPolicyFragment {
-    return new PrincipalPolicyFragment({ Federated: [ this.federated ] }, this.conditions);
+    return new PrincipalPolicyFragment({ Federated: [this.federated] }, this.conditions);
   }
 
   public toString() {
@@ -293,7 +399,7 @@ export class CompositePrincipal extends PrincipalBase {
   }
 
   public get policyFragment(): PrincipalPolicyFragment {
-    const principalJson: { [key: string]: string[] } = { };
+    const principalJson: { [key: string]: string[] } = {};
 
     for (const p of this.principals) {
       mergePrincipal(principalJson, p.policyFragment.principalJson);
@@ -324,6 +430,11 @@ class StackDependentToken implements cdk.IResolvable {
     return cdk.Token.asString(this);
   }
 
+  /**
+   * JSON-ify the token
+   *
+   * Used when JSON.stringify() is called
+   */
   public toJSON() {
     return `<unresolved-token>`;
   }
@@ -348,6 +459,11 @@ class ServicePrincipalToken implements cdk.IResolvable {
     });
   }
 
+  /**
+   * JSON-ify the token
+   *
+   * Used when JSON.stringify() is called
+   */
   public toJSON() {
     return `<${this.service}>`;
   }

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

@@ -124,7 +124,6 @@
       "docs-public-apis:@aws-cdk/aws-iam.CompositePrincipal",
       "docs-public-apis:@aws-cdk/aws-iam.CompositePrincipal.addPrincipals",
       "docs-public-apis:@aws-cdk/aws-iam.FederatedPrincipal",
-      "docs-public-apis:@aws-cdk/aws-iam.FederatedPrincipal.conditions",
       "docs-public-apis:@aws-cdk/aws-iam.FederatedPrincipal.federated",
       "docs-public-apis:@aws-cdk/aws-iam.Group",
       "docs-public-apis:@aws-cdk/aws-iam.LazyRole.roleId",
@@ -146,8 +145,6 @@
       "docs-public-apis:@aws-cdk/aws-iam.PolicyStatement.addResources",
       "docs-public-apis:@aws-cdk/aws-iam.PolicyStatement.toStatementJson",
       "docs-public-apis:@aws-cdk/aws-iam.PolicyStatement.toString",
-      "docs-public-apis:@aws-cdk/aws-iam.PrincipalBase.toJSON",
-      "docs-public-apis:@aws-cdk/aws-iam.PrincipalPolicyFragment.conditions",
       "docs-public-apis:@aws-cdk/aws-iam.PrincipalPolicyFragment.principalJson",
       "docs-public-apis:@aws-cdk/aws-iam.ServicePrincipal.service",
       "props-default-doc:@aws-cdk/aws-iam.GrantOnPrincipalOptions.scope",