feat(cognito): grant() for user pool (#20285)

Add a `grant()` method in `UserPool`.


----

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/master/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/master/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/master/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: jogold

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

@@ -73,6 +73,17 @@ The default set up for the user pool is configured such that only administrators
 to create users. Features such as Multi-factor authentication (MFAs) and Lambda Triggers are not
 configured by default.
 
+Use the `grant()` method to add an IAM policy statement associated with the user pool to an
+IAM principal's policy.
+
+```ts
+const userPool = new cognito.UserPool(this, 'myuserpool');
+const role = new iam.Role(this, 'role', {
+  assumedBy: new iam.ServicePrincipal('foo'),
+});
+userPool.grant(role, 'cognito-idp:AdminCreateUser');
+```
+
 ### Sign Up
 
 Users can either be signed up by the app's administrators or can sign themselves up. Once a user has signed up, their
@@ -632,8 +643,8 @@ pool.addClient('app-client', {
 });
 ```
 
-If the identity provider and the app client are created in the same stack, specify the dependency between both constructs to 
-make sure that the identity provider already exists when the app client will be created. The app client cannot handle the 
+If the identity provider and the app client are created in the same stack, specify the dependency between both constructs to
+make sure that the identity provider already exists when the app client will be created. The app client cannot handle the
 dependency to the identity provider automatically because the client does not have access to the provider's construct.
 
 ```ts
@@ -668,11 +679,11 @@ pool.addClient('app-client', {
 });
 ```
 
-Clients can (and should) be allowed to read and write relevant user attributes only. Usually every client can be allowed to 
+Clients can (and should) be allowed to read and write relevant user attributes only. Usually every client can be allowed to
 read the `given_name` attribute but not every client should be allowed to set the `email_verified` attribute.
 The same criteria applies for both standard and custom attributes, more info is available at
 [Attribute Permissions and Scopes](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-attribute-permissions-and-scopes).
-The default behaviour is to allow read and write permissions on all attributes. The following code shows how this can be 
+The default behaviour is to allow read and write permissions on all attributes. The following code shows how this can be
 configured for a client.
 
 ```ts
@@ -703,7 +714,7 @@ pool.addClient('app-client', {
   // ...
   enableTokenRevocation: true,
 });
-``` 
+```
 
 ### Resource Servers
 

packages/@aws-cdk/aws-cognito/lib/user-pool.ts

@@ -1,4 +1,4 @@
-import { IRole, PolicyDocument, PolicyStatement, Role, ServicePrincipal } from '@aws-cdk/aws-iam';
+import { Grant, IGrantable, IRole, PolicyDocument, PolicyStatement, Role, ServicePrincipal } from '@aws-cdk/aws-iam';
 import { IKey } from '@aws-cdk/aws-kms';
 import * as lambda from '@aws-cdk/aws-lambda';
 import { ArnFormat, Duration, IResource, Lazy, Names, RemovalPolicy, Resource, Stack, Token } from '@aws-cdk/core';
@@ -734,6 +734,19 @@ abstract class UserPoolBase extends Resource implements IUserPool {
   public registerIdentityProvider(provider: IUserPoolIdentityProvider) {
     this.identityProviders.push(provider);
   }
+
+  /**
+   * Adds an IAM policy statement associated with this user pool to an
+   * IAM principal's policy.
+   */
+  public grant(grantee: IGrantable, ...actions: string[]): Grant {
+    return Grant.addToPrincipal({
+      grantee,
+      actions,
+      resourceArns: [this.userPoolArn],
+      scope: this,
+    });
+  }
 }
 
 /**

packages/@aws-cdk/aws-cognito/test/user-pool.test.ts

@@ -1821,6 +1821,45 @@ test('device tracking is configured correctly', () => {
   });
 });
 
+test('grant', () => {
+  // GIVEN
+  const stack = new Stack();
+  const role = new Role(stack, 'Role', {
+    assumedBy: new ServicePrincipal('lambda.amazonaws.com'),
+  });
+
+  // WHEN
+  const userPool = new UserPool(stack, 'Pool');
+  userPool.grant(role, 'cognito-idp:AdminCreateUser', 'cognito-idp:ListUsers');
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::IAM::Policy', {
+    PolicyDocument: {
+      Statement: [
+        {
+          Action: [
+            'cognito-idp:AdminCreateUser',
+            'cognito-idp:ListUsers',
+          ],
+          Effect: 'Allow',
+          Resource: {
+            'Fn::GetAtt': [
+              'PoolD3F588B8',
+              'Arn',
+            ],
+          },
+        },
+      ],
+      Version: '2012-10-17',
+    },
+    Roles: [
+      {
+        Ref: 'Role1ABCC5F0',
+      },
+    ],
+  });
+
+});
 
 function fooFunction(scope: Construct, name: string): lambda.IFunction {
   return new lambda.Function(scope, name, {