feat(ecr): authorization token retrieval grants (#11783)

See README.md


----

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

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

@@ -37,6 +37,22 @@ repository.onImageScanCompleted('ImageScanComplete')
   .addTarget(...)
 ```
 
+### Authorization Token
+
+Besides the Amazon ECR APIs, ECR also allows the Docker CLI or a language-specific Docker library to push and pull
+images from an ECR repository. However, the Docker CLI does not support native IAM authentication methods and
+additional steps must be taken so that Amazon ECR can authenticate and authorize Docker push and pull requests.
+More information can be found at at [Registry Authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html#registry_auth).
+
+A Docker authorization token can be obtained using the `GetAuthorizationToken` ECR API. The following code snippets
+grants an IAM user access to call this API.
+
+```ts
+import * as iam from '@aws-cdk/aws-iam';
+
+const user = new iam.User(this, 'User', { ... });
+AuthorizationToken.grantRead(user);
+```
 
 ### Automatically clean up repositories
 

packages/@aws-cdk/aws-ecr/lib/auth-token.ts

@@ -0,0 +1,20 @@
+import * as iam from '@aws-cdk/aws-iam';
+
+/**
+ * Authorization token to access ECR repositories via Docker CLI.
+ */
+export class AuthorizationToken {
+  /**
+   * Grant access to retrieve an authorization token.
+   */
+  public static grantRead(grantee: iam.IGrantable) {
+    grantee.grantPrincipal.addToPrincipalPolicy(new iam.PolicyStatement({
+      actions: ['ecr:GetAuthorizationToken'],
+      // GetAuthorizationToken only allows '*'. See https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonelasticcontainerregistry.html#amazonelasticcontainerregistry-actions-as-permissions
+      resources: ['*'],
+    }));
+  }
+
+  private constructor() {
+  }
+}

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

@@ -3,3 +3,4 @@ export * from './ecr.generated';
 
 export * from './repository';
 export * from './lifecycle';
+export * from './auth-token';

packages/@aws-cdk/aws-ecr/test/test.auth-token.ts

@@ -0,0 +1,31 @@
+import { expect, haveResourceLike } from '@aws-cdk/assert';
+import * as iam from '@aws-cdk/aws-iam';
+import { Stack } from '@aws-cdk/core';
+import { Test } from 'nodeunit';
+import { AuthorizationToken } from '../lib';
+
+export = {
+  'grant()'(test: Test) {
+    // GIVEN
+    const stack = new Stack();
+    const user = new iam.User(stack, 'User');
+
+    // WHEN
+    AuthorizationToken.grantRead(user);
+
+    // THEN
+    expect(stack).to(haveResourceLike('AWS::IAM::Policy', {
+      PolicyDocument: {
+        Statement: [
+          {
+            Action: 'ecr:GetAuthorizationToken',
+            Effect: 'Allow',
+            Resource: '*',
+          },
+        ],
+      },
+    }));
+
+    test.done();
+  },
+};