feat(iam): specify initial PolicyDocument for inline Policy

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

@@ -250,8 +250,16 @@ const policyDocument = {
   ]
 };
 
-const newPolicyDocument = PolicyDocument.fromJson(policyDocument);
+const customPolicyDocument = PolicyDocument.fromJson(policyDocument);
 
+// You can pass this document as an initial document to a ManagedPolicy
+// or inline Policy.
+const newManagedPolicy = new ManagedPolicy(stack, 'MyNewManagedPolicy', { 
+  document: customPolicyDocument
+});
+const newPolicy = new Policy(stack, 'MyNewPolicy', { 
+  document: customPolicyDocument
+});
 ```
 
 ### OpenID Connect Providers

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

@@ -83,6 +83,15 @@ export interface PolicyProps {
    * @default false
    */
   readonly force?: boolean;
+
+  /**
+   * Initial PolicyDocument to use for this Policy. If omited, any
+   * `PolicyStatement` provided in the `statements` property will be applied
+   * against the empty default `PolicyDocument`.
+   *
+   * @default - An empty policy.
+   */
+  readonly document?: PolicyDocument;
 }
 
 /**
@@ -138,6 +147,10 @@ export class Policy extends Resource implements IPolicy {
       }
     }
 
+    if (props.document) {
+      this.document = props.document;
+    }
+
     const resource = new CfnPolicyConditional(this, 'Resource', {
       policyDocument: this.document,
       policyName: this.physicalName,

packages/@aws-cdk/aws-iam/test/policy.test.ts

@@ -1,7 +1,7 @@
 import { ResourcePart } from '@aws-cdk/assert';
 import '@aws-cdk/assert/jest';
 import { App, CfnResource, Stack } from '@aws-cdk/core';
-import { AnyPrincipal, CfnPolicy, Group, Policy, PolicyStatement, Role, ServicePrincipal, User } from '../lib';
+import { AnyPrincipal, CfnPolicy, Group, Policy, PolicyDocument, PolicyStatement, Role, ServicePrincipal, User } from '../lib';
 
 /* eslint-disable quote-props */
 
@@ -52,6 +52,42 @@ describe('IAM policy', () => {
     });
   });
 
+  test('policy from policy document alone', () => {
+    const policy = new Policy(stack, 'MyPolicy', {
+      policyName: 'MyPolicyName',
+      document: PolicyDocument.fromJson({
+        Statement: [
+          {
+            Action: 'sqs:SendMessage',
+            Effect: 'Allow',
+            Resource: '*',
+          },
+        ],
+      }),
+    });
+
+    const group = new Group(stack, 'MyGroup');
+    group.attachInlinePolicy(policy);
+
+    expect(stack).toMatchTemplate({
+      Resources: {
+        MyPolicy39D66CF6: {
+          Type: 'AWS::IAM::Policy',
+          Properties: {
+            PolicyName: 'MyPolicyName',
+            Groups: [{ Ref: 'MyGroupCBA54B1B' }],
+            PolicyDocument: {
+              Statement: [
+                { Action: 'sqs:SendMessage', Effect: 'Allow', Resource: '*' },
+              ],
+              Version: '2012-10-17',
+            },
+          },
+        },
+        MyGroupCBA54B1B: { Type: 'AWS::IAM::Group' },
+      },
+    });
+  });
   test('policy name can be omitted, in which case the logical id will be used', () => {
     const policy = new Policy(stack, 'MyPolicy');
     policy.addStatements(new PolicyStatement({ resources: ['*'], actions: ['sqs:SendMessage'] }));