feat(cognito): import an existing user pool client

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

@@ -40,6 +40,7 @@ This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aw
   - [Emails](#emails)
   - [Lambda Triggers](#lambda-triggers)
   - [Import](#importing-user-pools)
+  - [App Clients](#app-clients)
 
 ## User Pools
 
@@ -328,4 +329,25 @@ const awesomePool = UserPool.fromUserPoolId(stack, 'awesome-user-pool', 'us-east
 
 const otherAwesomePool = UserPool.fromUserPoolArn(stack, 'other-awesome-user-pool',
   'arn:aws:cognito-idp:eu-west-1:123456789012:userpool/us-east-1_mtRyYQ14D');
-```
+```
+
+### App Clients
+
+An app is an entity within a user pool that has permission to call unauthenticated APIs (APIs that do not have an
+authenticated user), such as APIs to register, sign in, and handle forgotten passwords. To call these APIs, you need an
+app client ID and an optional client secret. Read [Configuring a User Pool App
+Client](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) to learn more.
+
+The following code creates an app client and retrieves the client id -
+
+```ts
+const pool = new UserPool(this, 'Pool');
+
+const client = new UserPoolClient(stack, 'Client', {
+  userPool: pool
+});
+
+const clientId = client.userPoolClientId; 
+```
+
+Existing app clients can be imported into the CDK app using the `UserPoolClient.fromUserPoolClientId()` API.

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

@@ -1,4 +1,4 @@
-import { Construct, Resource } from '@aws-cdk/core';
+import { Construct, IResource, Resource } from '@aws-cdk/core';
 import { CfnUserPoolClient } from './cognito.generated';
 import { IUserPool } from './user-pool';
 
@@ -22,10 +22,13 @@ export enum AuthFlow {
   USER_PASSWORD = 'USER_PASSWORD_AUTH'
 }
 
+/**
+ * Properties for the UserPoolClient construct
+ */
 export interface UserPoolClientProps {
   /**
    * Name of the application client
-   * @default cloudformation generated name
+   * @default - cloudformation generated name
    */
   readonly userPoolClientName?: string;
 
@@ -42,44 +45,70 @@ export interface UserPoolClientProps {
 
   /**
    * List of enabled authentication flows
-   * @default no enabled flows
+   * @default - no enabled flows
    */
   readonly enabledAuthFlows?: AuthFlow[]
 }
 
 /**
- * Define a UserPool App Client
+ * Represents a Cognito user pool client.
  */
-export class UserPoolClient extends Resource {
+export interface IUserPoolClient extends IResource {
   /**
+   * Name of the application client
    * @attribute
    */
-  public readonly userPoolClientId: string;
+  readonly userPoolClientId: string;
+}
 
+/**
+ * Define a UserPool App Client
+ */
+export class UserPoolClient extends Resource implements IUserPoolClient {
   /**
-   * @attribute
+   * Import a user pool client given its id.
    */
-  public readonly userPoolClientName: string;
+  public static fromUserPoolClientId(scope: Construct, id: string, userPoolClientId: string): IUserPoolClient {
+    class Import extends Resource implements IUserPoolClient {
+      public readonly userPoolClientId = userPoolClientId;
+    }
 
-  /**
-   * @attribute
+    return new Import(scope, id);
+  }
+
+  public readonly userPoolClientId: string;
+  private readonly _userPoolClientName?: string;
+
+  /*
+   * Note to implementers: Two CloudFormation return values Name and ClientSecret are part of the spec.
+   * However, they have been explicity not implemented here. They are not documented in CloudFormation, and
+   * CloudFormation returns the following the string when these two attributes are 'GetAtt' - "attribute not supported
+   * at this time, please use the CLI or Console to retrieve this value".
+   * Awaiting updates from CloudFormation.
    */
-  public readonly userPoolClientClientSecret: string;
 
   constructor(scope: Construct, id: string, props: UserPoolClientProps) {
-    super(scope, id, {
-      physicalName: props.userPoolClientName,
-    });
+    super(scope, id);
 
     const resource = new CfnUserPoolClient(this, 'Resource', {
-      clientName: this.physicalName,
+      clientName: props.userPoolClientName,
       generateSecret: props.generateSecret,
       userPoolId: props.userPool.userPoolId,
       explicitAuthFlows: props.enabledAuthFlows
     });
 
     this.userPoolClientId = resource.ref;
-    this.userPoolClientClientSecret = resource.attrClientSecret;
-    this.userPoolClientName = resource.attrName;
+    this._userPoolClientName = props.userPoolClientName;
+  }
+
+  /**
+   * The client name that was specified via the `userPoolClientName` property during initialization,
+   * throws an error otherwise.
+   */
+  public get userPoolClientName(): string {
+    if (this._userPoolClientName === undefined) {
+      throw new Error('userPoolClientName is available only if specified on the UserPoolClient during initialization');
+    }
+    return this._userPoolClientName;
   }
 }

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

@@ -90,10 +90,8 @@
   },
   "awslint": {
     "exclude": [
-      "docs-public-apis:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientClientSecret",
-      "docs-public-apis:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientId",
-      "docs-public-apis:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientName",
-      "docs-public-apis:@aws-cdk/aws-cognito.UserPoolClientProps"
+      "attribute-tag:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientName",
+      "resource-attribute:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientClientSecret"
     ]
   },
   "stability": "experimental",

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

@@ -6,16 +6,46 @@ describe('User Pool Client', () => {
   test('default setup', () => {
     // GIVEN
     const stack = new Stack();
-    const pool = new UserPool(stack, 'Pool', { });
+    const pool = new UserPool(stack, 'Pool');
 
     // WHEN
     new UserPoolClient(stack, 'Client', {
       userPool: pool
     });
 
     // THEN
-    expect(stack).toHaveResourceLike('AWS::Cognito::UserPoolClient', {
-      UserPoolId: stack.resolve(pool.userPoolId)
+    expect(stack).toHaveResource('AWS::Cognito::UserPoolClient', {
+      UserPoolId: stack.resolve(pool.userPoolId),
     });
   });
+
+  test('client name', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = new UserPool(stack, 'Pool');
+
+    // WHEN
+    const client1 = new UserPoolClient(stack, 'Client1', {
+      userPool: pool,
+      userPoolClientName: 'myclient'
+    });
+    const client2 = new UserPoolClient(stack, 'Client2', {
+      userPool: pool,
+    });
+
+    // THEN
+    expect(client1.userPoolClientName).toEqual('myclient');
+    expect(() => client2.userPoolClientName).toThrow(/available only if specified on the UserPoolClient during initialization/);
+  });
+
+  test('import', () => {
+    // GIVEN
+    const stack = new Stack();
+
+    // WHEN
+    const client = UserPoolClient.fromUserPoolClientId(stack, 'Client', 'client-id-1');
+
+    // THEN
+    expect(client.userPoolClientId).toEqual('client-id-1');
+  });
 });