JavaScript (v3): Cognito - Complete functionality and README for AutoConfirm workflow.

Author: cpyle0819

.doc_gen/metadata/cognito-identity-provider_metadata.yaml

@@ -753,6 +753,14 @@ cognito-identity-provider_DeleteUser:
               snippet_tags:
                 - gov2.cognito-identity-provider.CognitoActions.struct
                 - gov2.cognito-identity-provider.DeleteUser
+    JavaScript:
+      versions:
+        - sdk_version: 3
+          github: javascriptv3/example_code/cross-services/wkflw-pools-triggers
+          excerpts:
+            - description:
+              snippet_tags:
+                - javascript.v3.cognito-idp.actions.DeleteUser
   services:
     cognito-identity-provider: {DeleteUser}
 cognito-identity-provider_CreateUserPool:
@@ -793,6 +801,15 @@ cognito-identity-provider_UpdateUserPool:
               snippet_tags:
                 - gov2.cognito-identity-provider.CognitoActions.struct
                 - gov2.cognito-identity-provider.UpdateUserPool
+    JavaScript:
+      versions:
+        - sdk_version: 3
+          github: javascriptv3/example_code/cross-services/wkflw-pools-triggers
+          sdkguide:
+          excerpts:
+            - description:
+              snippet_tags:
+                - javascript.v3.cognito-idp.actions.UpdateUserPool
   services:
     cognito-identity-provider: {UpdateUserPool}
 cognito-identity-provider_ForgotPassword:

.doc_gen/metadata/cross_metadata.yaml

@@ -822,6 +822,30 @@ cross_CognitoAutoConfirmUser:
             - description: Clean up resources.
               snippet_tags:
                 - gov2.cognito-identity-provider.Resources.complete
+    JavaScript:
+      versions:
+        - sdk_version: 3
+          github: javascriptv3/example_code/cross-services/wkflw-pools-triggers
+          sdk_guide:
+          excerpts:
+            - description: Run an interactive scenario at a command prompt.
+              snippet_tags:
+                - javascript.v3.wkflw.pools-triggers.index
+                - javascript.v3.wkflw.pools-triggers.AutoConfirm
+                - javascript.v3.wkflw.pools-triggers.common
+            - description: Handle the <code>PreSignUp</code> trigger with a &LAM; function.
+              snippet_tags:
+                - javascript.v3.wkflw.pools-triggers.handler.AutoConfirm
+            - description: &CWL; actions
+              snippet_files:
+                - javascriptv3/example_code/cross-services/wkflw-pools-triggers/actions/cloudwatch-logs-actions.js
+            - description: &COG; actions
+              snippet_files:
+                - javascriptv3/example_code/cross-services/wkflw-pools-triggers/actions/cognito-actions.js
+            - description: &DDB; actions
+              snippet_files:
+                - javascriptv3/example_code/cross-services/wkflw-pools-triggers/actions/dynamodb-actions.js
+
   services:
     cognito-identity-provider: {UpdateUserPool, SignUp, InitiateAuth, DeleteUser}
     lambda: {}

javascriptv3/example_code/cross-services/wkflw-pools-triggers/README.md

@@ -0,0 +1,99 @@
+# Customize Amazon Cognito authentication behavior with Lambda functions
+
+## Overview
+
+This example shows how to use AWS SDKs to customize Amazon Cognito authentication behavior. You can configure
+your Amazon Cognito user pool to automatically invoke AWS Lambda functions at various points in the authentication
+process, such as before sign-up, during sign-in, and after authentication.
+
+There are three workflows demonstrated by this example:
+
+* Automatically confirm and verify the email of known users by using a pre sign-up trigger.
+* [Not yet implemented] Automatically add known users at sign-in by using a migrate user trigger.
+* [Not yet implemented] Write custom information to an Amazon DynamoDB table after users are authenticated by using a post authentication trigger.
+
+These workflows are described in more detail in the main [README](../../../../workflows/user_pools_and_lambda_triggers/README.md) 
+for these examples.
+
+## Automatically confirm known users
+
+A [pre sign-up Lambda trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-sign-up.html)
+is invoked when a user starts the sign-up process and lets your Lambda function
+take action before Amazon Cognito adds the user to the user pool.
+
+## Automatically migrate known users
+
+A [migrate user Lambda trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-migrate-user.html)
+is invoked when a user doesn't exist in the user pool at sign-in with a password.
+After the Lambda function returns successfully, Amazon Cognito creates the user in the user pool.
+
+## Write custom activity after authentication
+
+A [post authentication Lambda trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-post-authentication.html)
+is invoked after signing in a user, so you can add custom logic after Amazon Cognito authenticates the user.
+
+## ⚠ Important
+
+* Running this code might result in charges to your AWS account.
+* Running the tests might result in charges to your AWS account.
+* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
+## Run the examples
+
+### Prerequisites
+
+For general prerequisites, see the [README](../../../README.md#prerequisites) in the `javascriptv3` folder.
+
+### Setup
+
+This example deploys several resources by using an AWS CloudFormation stack. This stack
+deploys the following resources:
+
+* An Amazon DynamoDB table named `doc-example-custom-users` that has a `UserEmail` primary key.
+  This table functions as an external user store.
+* An Amazon Cognito user pool that requires an email, sends an email with verification code
+  when a new user is added, does not require MFA, and allows account recovery with a verified email.
+* An Amazon Cognito client application. This is required for client calls to sign-up and
+  authentication users.
+* An AWS Identity and Access Management (IAM) role that can be assumed by Lambda.
+  This role grants permission to Lambda to read from and write to the DynamoDB table and
+  write to CloudWatch Logs.
+
+### Deploy AWS resources
+
+The AWS resources for this example are deployed by using the AWS Cloud Development Kit (AWS CDK).
+
+To install the AWS CDK, follow the instructions in the
+[Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html).
+
+Deploy resources at a command prompt from the [cdk](./cdk/) folder:
+
+```
+npm install
+cdk deploy
+```
+
+###  Instructions
+
+Run `./index --help` for instructions on running a scenario.
+
+### Cleanup
+
+Delete resources deployed for this example by deleting the stack.
+
+Delete the stack at a command prompt from the [cdk](./cdk/) folder:
+
+```
+cdk destroy
+```
+
+## Additional resources
+
+- [Amazon Cognito Identity Provider Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)
+- [Amazon Cognito Identity Provider API Reference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html)
+- [SDK for JavaScript V3 Amazon Cognito Identity Provider reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cognito-identity-provider/)
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

javascriptv3/example_code/cross-services/wkflw-pools-triggers/actions/cloudwatch-logs-actions.js

@@ -0,0 +1,69 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  CloudWatchLogsClient,
+  GetLogEventsCommand,
+  OrderBy,
+  paginateDescribeLogStreams,
+} from "@aws-sdk/client-cloudwatch-logs";
+
+/**
+ * Get the latest log stream for a Lambda function.
+ * @param {{ functionName: string, region: string }} config
+ * @returns {Promise<[import("@aws-sdk/client-cloudwatch-logs").LogStream | null, unknown]>}
+ */
+export const getLatestLogStreamForLambda = async ({ functionName, region }) => {
+  try {
+    const logGroupName = `/aws/lambda/${functionName}`;
+    const cwlClient = new CloudWatchLogsClient({ region });
+    const paginator = paginateDescribeLogStreams(
+      { client: cwlClient },
+      {
+        descending: true,
+        limit: 1,
+        orderBy: OrderBy.LastEventTime,
+        logGroupName,
+      },
+    );
+
+    for await (const page of paginator) {
+      return [page.logStreams[0], null];
+    }
+  } catch (err) {
+    return [null, err];
+  }
+};
+
+/**
+ * Get the log events for a Lambda function's log stream.
+ * @param {{
+ *   functionName: string,
+ *   logStreamName: string,
+ *   eventCount: number,
+ *   region: string
+ * }} config
+ * @returns {Promise<[import("@aws-sdk/client-cloudwatch-logs").OutputLogEvent[] | null, unknown]>}
+ */
+export const getLogEvents = async ({
+  functionName,
+  logStreamName,
+  eventCount,
+  region,
+}) => {
+  try {
+    const cwlClient = new CloudWatchLogsClient({ region });
+    const logGroupName = `/aws/lambda/${functionName}`;
+    const response = await cwlClient.send(
+      new GetLogEventsCommand({
+        logStreamName: logStreamName,
+        limit: eventCount,
+        logGroupName: logGroupName,
+      }),
+    );
+
+    return [response.events, null];
+  } catch (err) {
+    return [null, err];
+  }
+};

javascriptv3/example_code/cross-services/wkflw-pools-triggers/actions/cognito-actions.js

@@ -0,0 +1,140 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  AdminGetUserCommand,
+  CognitoIdentityProviderClient,
+  DeleteUserCommand,
+  InitiateAuthCommand,
+  SignUpCommand,
+  UpdateUserPoolCommand,
+} from "@aws-sdk/client-cognito-identity-provider";
+
+// snippet-start:[javascript.v3.cognito-idp.actions.UpdateUserPool]
+/**
+ * Connect a Lambda function to the PreSignUp trigger for a Cognito user pool
+ * @param {{ region: string, userPoolId: string, handlerArn: string }} config
+ * @returns {Promise<[import("@aws-sdk/client-cognito-identity-provider").UpdateUserPoolCommandOutput | null, unknown]>}
+ */
+export const addPreSignUpHandler = async ({
+  region,
+  userPoolId,
+  handlerArn,
+}) => {
+  try {
+    const cognitoClient = new CognitoIdentityProviderClient({
+      region,
+    });
+
+    const command = new UpdateUserPoolCommand({
+      UserPoolId: userPoolId,
+      LambdaConfig: {
+        PreSignUp: handlerArn,
+      },
+    });
+
+    const response = await cognitoClient.send(command);
+    return [response, null];
+  } catch (err) {
+    return [null, err];
+  }
+};
+// snippet-end:[javascript.v3.cognito-idp.actions.UpdateUserPool]
+
+/**
+ * Attempt to register a user to a user pool with a given username and password.
+ * @param {{
+ *   region: string,
+ *   userPoolClientId: string,
+ *   username: string,
+ *   email: string,
+ *   password: string
+ * }} config
+ * @returns {Promise<[import("@aws-sdk/client-cognito-identity-provider").SignUpCommandOutput | null, unknown]>}
+ */
+export const signUpUser = async ({
+  region,
+  userPoolClientId,
+  username,
+  email,
+  password,
+}) => {
+  try {
+    const cognitoClient = new CognitoIdentityProviderClient({
+      region,
+    });
+
+    const response = await cognitoClient.send(
+      new SignUpCommand({
+        ClientId: userPoolClientId,
+        Username: username,
+        Password: password,
+        UserAttributes: [{ Name: "email", Value: email }],
+      }),
+    );
+    return [response, null];
+  } catch (err) {
+    return [null, err];
+  }
+};
+
+/**
+ * Sign in a user to Amazon Cognito using a username and password authentication flow.
+ * @param {{ region: string, clientId: string, username: string, password: string }} config
+ * @returns {Promise<[import("@aws-sdk/client-cognito-identity-provider").InitiateAuthCommandOutput | null, unknown]>}
+ */
+export const signIn = async ({ region, clientId, username, password }) => {
+  try {
+    const cognitoClient = new CognitoIdentityProviderClient({ region });
+    const response = await cognitoClient.send(
+      new InitiateAuthCommand({
+        AuthFlow: "USER_PASSWORD_AUTH",
+        ClientId: clientId,
+        AuthParameters: { USERNAME: username, PASSWORD: password },
+      }),
+    );
+    return [response, null];
+  } catch (err) {
+    return [null, err];
+  }
+};
+
+/**
+ * Retrieve an existing user from a user pool.
+ * @param {{ region: string, userPoolId: string, username: string }} config
+ * @returns {Promise<[import("@aws-sdk/client-cognito-identity-provider").AdminGetUserCommandOutput | null, unknown]>}
+ */
+export const getUser = async ({ region, userPoolId, username }) => {
+  try {
+    const cognitoClient = new CognitoIdentityProviderClient({ region });
+    const response = await cognitoClient.send(
+      new AdminGetUserCommand({
+        UserPoolId: userPoolId,
+        Username: username,
+      }),
+    );
+    return [response, null];
+  } catch (err) {
+    return [null, err];
+  }
+};
+
+// snippet-start:[javascript.v3.cognito-idp.actions.DeleteUser]
+/**
+ * Delete the signed-in user. Useful for allowing a user to delete their
+ * own profile.
+ * @param {{ region: string, accessToken: string }} config
+ * @returns {Promise<[import("@aws-sdk/client-cognito-identity-provider").DeleteUserCommandOutput | null, unknown]>}
+ */
+export const deleteUser = async ({ region, accessToken }) => {
+  try {
+    const client = new CognitoIdentityProviderClient({ region });
+    const response = await client.send(
+      new DeleteUserCommand({ AccessToken: accessToken }),
+    );
+    return [response, null];
+  } catch (err) {
+    return [null, err];
+  }
+};
+// snippet-end:[javascript.v3.cognito-idp.actions.DeleteUser]