feat(cognito): user pool identity provider with support for Facebook & Amazon

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)
+  - [Identity Providers](#identity-providers)
   - [Domains](#domains)
 
 ## User Pools
@@ -417,6 +418,36 @@ pool.addClient('app-client', {
 });
 ```
 
+### Identity Providers
+
+Users that are part of a user pool can sign in either directly through a user pool, or federate through a third-party
+identity provider. Once configured, the Cognito backend will take care of integrating with the third-party provider.
+Read more about [Adding User Pool Sign-in Through a Third
+Party](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-identity-federation.html).
+
+The following third-party identity providers are currentlhy supported in the CDK -
+
+* [Login With Amazon](https://developer.amazon.com/apps-and-games/login-with-amazon)
+* [Facebook Login](https://developers.facebook.com/docs/facebook-login/)
+
+The following code configures a user pool to federate with the third party provider, 'Login with Amazon'. The identity
+provider needs to be configured with a set of credentials that the Cognito backend can use to federate with the
+third-party identity provider.
+
+```ts
+const userpool = new UserPool(stack, 'Pool');
+
+const provider = UserPoolIdentityProvider.amazon(stack, 'Amazon', {
+  clientId: 'amzn-client-id',
+  clientSecret: 'amzn-client-secret',
+  userPool: userpool,
+});
+```
+
+In order to allow users to sign in with a third-party identity provider, the app client that faces the user should be
+configured to use the identity provider. See [App Clients](#app-clients) section to know more about App Clients.
+The identity providers should be configured on `identityProviders` property available on the `UserPoolClient` construct.
+
 ### Domains
 
 After setting up an [app client](#app-clients), the address for the user pool's sign-up and sign-in webpages can be
@@ -446,7 +477,7 @@ pool.addDomain('CustomDomain', {
 
 Read more about [Using the Amazon Cognito
 Domain](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-assign-domain-prefix.html) and [Using Your Own
-Domain](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-add-custom-domain.html)
+Domain](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-add-custom-domain.html).
 
 The `signInUrl()` methods returns the fully qualified URL to the login page for the user pool. This page comes from the
 hosted UI configured with Cognito. Learn more at [Hosted UI with the Amazon Cognito
@@ -474,4 +505,4 @@ const domain = userpool.addDomain('Domain', {
 const signInUrl = domain.signInUrl(client, {
   redirectUrl: 'https://myapp.com/home', // must be a URL configured under 'callbackUrls' with the client
 })
-```
+```

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

@@ -3,4 +3,6 @@ export * from './cognito.generated';
 export * from './user-pool';
 export * from './user-pool-attr';
 export * from './user-pool-client';
-export * from './user-pool-domain';
+export * from './user-pool-domain';
+export * from './user-pool-idp';
+export * from './user-pool-idps';

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

@@ -1,6 +1,7 @@
 import { Construct, IResource, Resource } from '@aws-cdk/core';
 import { CfnUserPoolClient } from './cognito.generated';
 import { IUserPool } from './user-pool';
+import { IUserPoolIdentityProvider } from './user-pool-idp';
 
 /**
  * Types of authentication flow
@@ -182,6 +183,20 @@ export interface UserPoolClientOptions {
    * @default true for new stacks
    */
   readonly preventUserExistenceErrors?: boolean;
+
+  /**
+   * Whether users registered in the user pool should be able to sign in using this client.
+   * If this is set to `true` and `identityProviders` are set, the client will only allow sign in via
+   * third-party identity providers.
+   * @default true
+   */
+  readonly allowUserPoolIdentities?: boolean;
+
+  /**
+   * The list of federated identity providers that users should be able to use to sign in using this client.
+   * @default - no identity providers
+   */
+  readonly identityProviders?: IUserPoolIdentityProvider[];
 }
 
 /**
@@ -262,7 +277,7 @@ export class UserPoolClient extends Resource implements IUserPoolClient {
       callbackUrLs: callbackUrls && callbackUrls.length > 0 ? callbackUrls : undefined,
       allowedOAuthFlowsUserPoolClient: props.oAuth ? true : undefined,
       preventUserExistenceErrors: this.configurePreventUserExistenceErrors(props.preventUserExistenceErrors),
-      supportedIdentityProviders: [ 'COGNITO' ],
+      supportedIdentityProviders: this.configureIdentityProviders(props),
     });
 
     this.userPoolClientId = resource.ref;
@@ -326,4 +341,16 @@ export class UserPoolClient extends Resource implements IUserPoolClient {
     }
     return prevent ? 'ENABLED' : 'LEGACY';
   }
+
+  private configureIdentityProviders(props: UserPoolClientProps): string[] | undefined {
+    const providers: Set<string> = new Set();
+    if (props.allowUserPoolIdentities === undefined || props.allowUserPoolIdentities === true) {
+      providers.add('COGNITO');
+    }
+    if (props.identityProviders) {
+      props.identityProviders.forEach((p) => providers.add(p.providerName));
+    }
+    if (providers.size === 0) { return undefined; }
+    return Array.from(providers);
+  }
 }

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

@@ -0,0 +1,41 @@
+import { Construct, IResource } from '@aws-cdk/core';
+import {
+  UserPoolIdentityProviderAmazon,
+  UserPoolIdentityProviderAmazonProps,
+  UserPoolIdentityProviderFacebook,
+  UserPoolIdentityProviderFacebookProps,
+} from './user-pool-idps';
+
+/**
+ * Represents a UserPoolIdentityProvider
+ */
+export interface IUserPoolIdentityProvider extends IResource {
+  /**
+   * The primary identifier of this identity provider
+   * @attribute
+   */
+  readonly providerName: string;
+}
+
+/**
+ * Options to integrate with the various social identity providers.
+ */
+export class UserPoolIdentityProvider {
+  /**
+   * Federate with 'Facebook Login'
+   * @see https://developers.facebook.com/docs/facebook-login/
+   */
+  public static facebook(scope: Construct, id: string, options: UserPoolIdentityProviderFacebookProps) {
+    return new UserPoolIdentityProviderFacebook(scope, id, options);
+  }
+
+  /**
+   * Federate with 'Login with Amazon'
+   * @see https://developer.amazon.com/apps-and-games/login-with-amazon
+   */
+  public static amazon(scope: Construct, id: string, options: UserPoolIdentityProviderAmazonProps) {
+    return new UserPoolIdentityProviderAmazon(scope, id, options);
+  }
+
+  private constructor() {}
+}

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

@@ -0,0 +1,58 @@
+import { Construct, Resource } from '@aws-cdk/core';
+import { CfnUserPoolIdentityProvider } from '../cognito.generated';
+import { IUserPool } from '../user-pool';
+import { IUserPoolIdentityProvider } from '../user-pool-idp';
+
+/**
+ * Properties to initialize UserPoolAmazonIdentityProvider
+ */
+export interface UserPoolIdentityProviderAmazonProps {
+  /**
+   * The user pool to which this construct provides identities.
+   */
+  readonly userPool: IUserPool;
+
+  /**
+   * The client id recognized by 'Login with Amazon' APIs.
+   * @see https://developer.amazon.com/docs/login-with-amazon/security-profile.html#client-identifier
+   */
+  readonly clientId: string;
+  /**
+   * The client secret to be accompanied with clientId for 'Login with Amazon' APIs to authenticate the client.
+   * @see https://developer.amazon.com/docs/login-with-amazon/security-profile.html#client-identifier
+   */
+  readonly clientSecret: string;
+  /**
+   * The types of user profile data to obtain for the Amazon profile.
+   * @see https://developer.amazon.com/docs/login-with-amazon/customer-profile.html
+   * @default [ profile ]
+   */
+  readonly scopes?: string[];
+}
+
+/**
+ * Represents a identity provider that integrates with 'Login with Amazon'
+ * @resource AWS::Cognito::UserPoolIdentityProvider
+ */
+export class UserPoolIdentityProviderAmazon extends Resource implements IUserPoolIdentityProvider {
+  public readonly providerName: string;
+
+  constructor(scope: Construct, id: string, props: UserPoolIdentityProviderAmazonProps) {
+    super(scope, id);
+
+    const scopes = props.scopes ?? [ 'profile' ];
+
+    const resource = new CfnUserPoolIdentityProvider(this, 'Resource', {
+      userPoolId: props.userPool.userPoolId,
+      providerName: 'LoginWithAmazon', // must be 'LoginWithAmazon' when the type is 'LoginWithAmazon'
+      providerType: 'LoginWithAmazon',
+      providerDetails: {
+        client_id: props.clientId,
+        client_secret: props.clientSecret,
+        authorize_scopes: scopes.join(' '),
+      },
+    });
+
+    this.providerName = super.getResourceNameAttribute(resource.ref);
+  }
+}

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

@@ -0,0 +1,63 @@
+import { Construct, Resource } from '@aws-cdk/core';
+import { CfnUserPoolIdentityProvider } from '../cognito.generated';
+import { IUserPool } from '../user-pool';
+import { IUserPoolIdentityProvider } from '../user-pool-idp';
+
+/**
+ * Properties to initialize UserPoolFacebookIdentityProvider
+ */
+export interface UserPoolIdentityProviderFacebookProps {
+  /**
+   * The user pool to which this construct provides identities.
+   */
+  readonly userPool: IUserPool;
+
+  /**
+   * The client id recognized by Facebook APIs.
+   */
+  readonly clientId: string;
+  /**
+   * The client secret to be accompanied with clientUd for Facebook to authenticate the client.
+   * @see https://developers.facebook.com/docs/facebook-login/security#appsecret
+   */
+  readonly clientSecret: string;
+  /**
+   * The list of facebook permissions to obtain for getting access to the Facebook profile.
+   * @see https://developers.facebook.com/docs/facebook-login/permissions
+   * @default [ public_profile ]
+   */
+  readonly scopes?: string[];
+  /**
+   * The Facebook API version to use
+   * @default - to the oldest version supported by Facebook
+   */
+  readonly apiVersion?: string;
+}
+
+/**
+ * Represents a identity provider that integrates with 'Facebook Login'
+ * @resource AWS::Cognito::UserPoolIdentityProvider
+ */
+export class UserPoolIdentityProviderFacebook extends Resource implements IUserPoolIdentityProvider {
+  public readonly providerName: string;
+
+  constructor(scope: Construct, id: string, props: UserPoolIdentityProviderFacebookProps) {
+    super(scope, id);
+
+    const scopes = props.scopes ?? [ 'public_profile' ];
+
+    const resource = new CfnUserPoolIdentityProvider(this, 'Resource', {
+      userPoolId: props.userPool.userPoolId,
+      providerName: 'Facebook', // must be 'Facebook' when the type is 'Facebook'
+      providerType: 'Facebook',
+      providerDetails: {
+        client_id: props.clientId,
+        client_secret: props.clientSecret,
+        authorize_scopes: scopes.join(','),
+        api_version: props.apiVersion,
+      },
+    });
+
+    this.providerName = super.getResourceNameAttribute(resource.ref);
+  }
+}

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

@@ -0,0 +1,2 @@
+export * from './amazon';
+export * from './facebook';

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

@@ -96,7 +96,9 @@
     "exclude": [
       "attribute-tag:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientName",
       "resource-attribute:@aws-cdk/aws-cognito.UserPoolClient.userPoolClientClientSecret",
-      "props-physical-name:@aws-cdk/aws-cognito.UserPoolDomainProps"
+      "props-physical-name:@aws-cdk/aws-cognito.UserPoolDomainProps",
+      "props-physical-name:@aws-cdk/aws-cognito.UserPoolIdentityProviderFacebookProps",
+      "props-physical-name:@aws-cdk/aws-cognito.UserPoolIdentityProviderAmazonProps"
     ]
   },
   "stability": "experimental",