feat(cognito): user pool domain (#7224)

Support for user pool domains in the Cognito module.
Domains can be explicitly configured for either custom domain or Cognito
hosted prefix domains.

Added 'cloudFrontDomainName' property that gets the CloudFront domain
name by calling `DescribeUserPoolDomain` API via a custom resource.

closes #6787.

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

@@ -37,6 +37,7 @@ This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aw
   - [Lambda Triggers](#lambda-triggers)
   - [Import](#importing-user-pools)
   - [App Clients](#app-clients)
+  - [Domains](#domains)
 
 ## User Pools
 
@@ -398,3 +399,34 @@ pool.addClient('app-client', {
   }
 });
 ```
+
+### Domains
+
+After setting up an [app client](#app-clients), the address for the user pool's sign-up and sign-in webpages can be
+configured using domains. There are two ways to set up a domain - either the Amazon Cognito hosted domain can be chosen
+with an available domain prefix, or a custom domain name can be chosen. The custom domain must be one that is already
+owned, and whose certificate is registered in AWS Certificate Manager.
+
+The following code sets up a user pool domain in Amazon Cognito hosted domain with the prefix 'my-awesome-app' -
+
+```ts
+const pool = new UserPool(this, 'Pool');
+pool.addDomain('domain', {
+  domain: UserPoolDomainType.cognitoDomain({
+    domainPrefix: 'my-awesome-app',
+  }),
+});
+```
+
+On the other hand, the following code sets up a user pool domain and use your own custom domain -
+
+```ts
+const domainCert = new acm.Certificate.fromCertificateArn(this, 'domainCert', certificateArn);
+const pool = new UserPool(this, 'Pool');
+pool.addDomain('domain', {
+  domain: UserPoolDomainType.customDomain({
+    domainPrefix: 'my-awesome-app',
+    certificate: domainCert,
+  }),
+});
+```

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

@@ -2,4 +2,5 @@ export * from './cognito.generated';
 
 export * from './user-pool';
 export * from './user-pool-attr';
-export * from './user-pool-client';
+export * from './user-pool-client';
+export * from './user-pool-domain';

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

@@ -146,7 +146,7 @@ export class OAuthScope {
 }
 
 /**
- * Properties for the UserPoolClient construct
+ * Options to create a UserPoolClient
  */
 export interface UserPoolClientOptions {
   /**

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

@@ -0,0 +1,129 @@
+import { ICertificate } from '@aws-cdk/aws-certificatemanager';
+import { Construct, IResource, Resource } from '@aws-cdk/core';
+import { AwsCustomResource, AwsCustomResourcePolicy, AwsSdkCall, PhysicalResourceId } from '@aws-cdk/custom-resources';
+import { CfnUserPoolDomain } from './cognito.generated';
+import { IUserPool } from './user-pool';
+
+/**
+ * Represents a user pool domain.
+ */
+export interface IUserPoolDomain extends IResource {
+  /**
+   * The domain that was specified to be created.
+   * If `customDomain` was selected, this holds the full domain name that was specified.
+   * If the `cognitoDomain` was used, it contains the prefix to the Cognito hosted domain.
+   * @attribute
+   */
+  readonly domainName: string;
+}
+
+/**
+ * Options while specifying custom domain
+ * @see https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-add-custom-domain.html
+ */
+export interface CustomDomainOptions {
+  /**
+   * The custom domain name that you would like to associate with this User Pool.
+   */
+  readonly domainName: string;
+
+  /**
+   * The certificate to associate with this domain.
+   */
+  readonly certificate: ICertificate;
+}
+
+/**
+ * Options while specifying a cognito prefix domain.
+ * @see https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-assign-domain-prefix.html
+ */
+export interface CognitoDomainOptions {
+  /**
+   * The prefix to the Cognito hosted domain name that will be associated with the user pool.
+   */
+  readonly domainPrefix: string;
+}
+
+/**
+ * Options to create a UserPoolDomain
+ */
+export interface UserPoolDomainOptions {
+  /**
+   * Associate a custom domain with your user pool
+   * Either `customDomain` or `cognitoDomain` must be specified.
+   * @see https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-add-custom-domain.html
+   * @default - not set if `cognitoDomain` is specified, otherwise, throws an error.
+   */
+  readonly customDomain?: CustomDomainOptions;
+
+  /**
+   * Associate a cognito prefix domain with your user pool
+   * Either `customDomain` or `cognitoDomain` must be specified.
+   * @see https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-assign-domain-prefix.html
+   * @default - not set if `customDomain` is specified, otherwise, throws an error.
+   */
+  readonly cognitoDomain?: CognitoDomainOptions;
+}
+
+/**
+ * Props for UserPoolDomain construct
+ */
+export interface UserPoolDomainProps extends UserPoolDomainOptions {
+  /**
+   * The user pool to which this domain should be associated.
+   */
+  readonly userPool: IUserPool;
+}
+
+/**
+ * Define a user pool domain
+ */
+export class UserPoolDomain extends Resource implements IUserPoolDomain {
+  public readonly domainName: string;
+
+  constructor(scope: Construct, id: string, props: UserPoolDomainProps) {
+    super(scope, id);
+
+    if (!!props.customDomain === !!props.cognitoDomain) {
+      throw new Error('One of, and only one of, cognitoDomain or customDomain must be specified');
+    }
+
+    if (props.cognitoDomain?.domainPrefix && !/^[a-z0-9-]+$/.test(props.cognitoDomain.domainPrefix)) {
+      throw new Error('domainPrefix for cognitoDomain can contain only lowercase alphabets, numbers and hyphens');
+    }
+
+    const domainName = props.cognitoDomain?.domainPrefix || props.customDomain?.domainName!;
+    const resource = new CfnUserPoolDomain(this, 'Resource', {
+      userPoolId: props.userPool.userPoolId,
+      domain: domainName,
+      customDomainConfig: props.customDomain ? { certificateArn: props.customDomain.certificate.certificateArn } : undefined,
+    });
+
+    this.domainName = resource.ref;
+  }
+
+  /**
+   * The domain name of the CloudFront distribution associated with the user pool domain.
+   */
+  public get cloudFrontDomainName(): string {
+    const sdkCall: AwsSdkCall = {
+      service: 'CognitoIdentityServiceProvider',
+      action: 'describeUserPoolDomain',
+      parameters: {
+        Domain: this.domainName,
+      },
+      physicalResourceId: PhysicalResourceId.of(this.domainName),
+    };
+    const customResource = new AwsCustomResource(this, 'CloudFrontDomainName', {
+      resourceType: 'Custom::UserPoolCloudFrontDomainName',
+      onCreate: sdkCall,
+      onUpdate: sdkCall,
+      policy: AwsCustomResourcePolicy.fromSdkCalls({
+        // DescribeUserPoolDomain only supports access level '*'
+        // https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoncognitouserpools.html#amazoncognitouserpools-actions-as-permissions
+        resources: [ '*' ],
+      }),
+    });
+    return customResource.getResponseField('DomainDescription.CloudFrontDistribution');
+  }
+}

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

@@ -4,6 +4,7 @@ import { Construct, Duration, IResource, Lazy, Resource, Stack } from '@aws-cdk/
 import { CfnUserPool } from './cognito.generated';
 import { ICustomAttribute, RequiredAttributes } from './user-pool-attr';
 import { IUserPoolClient, UserPoolClient, UserPoolClientOptions } from './user-pool-client';
+import { UserPoolDomain, UserPoolDomainOptions } from './user-pool-domain';
 
 /**
  * The different ways in which users of this pool can sign up or sign in.
@@ -658,13 +659,28 @@ export class UserPool extends Resource implements IUserPool {
     (this.triggers as any)[operation.operationName] = fn.functionArn;
   }
 
+  /**
+   * Add a new app client to this user pool.
+   * @see https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html
+   */
   public addClient(id: string, options?: UserPoolClientOptions): IUserPoolClient {
     return new UserPoolClient(this, id, {
       userPool: this,
       ...options,
     });
   }
 
+  /**
+   * Associate a domain to this user pool.
+   * @see https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-assign-domain.html
+   */
+  public addDomain(id: string, options: UserPoolDomainOptions): UserPoolDomain {
+    return new UserPoolDomain(this, id, {
+      userPool: this,
+      ...options,
+    });
+  }
+
   private addLambdaPermission(fn: lambda.IFunction, name: string): void {
     const capitalize = name.charAt(0).toUpperCase() + name.slice(1);
     fn.addPermission(`${capitalize}Cognito`, {

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

@@ -72,16 +72,20 @@
     "pkglint": "0.0.0"
   },
   "dependencies": {
+    "@aws-cdk/aws-certificatemanager": "0.0.0",
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-lambda": "0.0.0",
     "@aws-cdk/core": "0.0.0",
+    "@aws-cdk/custom-resources": "0.0.0",
     "constructs": "^3.0.2"
   },
   "homepage": "https://github.com/aws/aws-cdk",
   "peerDependencies": {
+    "@aws-cdk/aws-certificatemanager": "0.0.0",
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-lambda": "0.0.0",
     "@aws-cdk/core": "0.0.0",
+    "@aws-cdk/custom-resources": "0.0.0",
     "constructs": "^3.0.2"
   },
   "jest": {},
@@ -91,7 +95,8 @@
   "awslint": {
     "exclude": [
       "attribute-tag:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientName",
-      "resource-attribute:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientClientSecret"
+      "resource-attribute:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientClientSecret",
+      "props-physical-name:@aws-cdk/aws-cognito.UserPoolDomainProps"
     ]
   },
   "stability": "experimental",