Importing users with a user migration Lambda trigger - Amazon Cognito

Importing users with a user migration Lambda trigger

With this approach, you can seamlessly migrate users from your existing user directory to user pools when a user signs in for the first time with your app or requests a password reset. Add a Migrate user Lambda trigger function to your user pool and it receives metadata about users who try to sign in, and returns user profile information from an external identity source. For details and example code for this Lambda trigger, including request and response parameters, see Migrate user Lambda trigger parameters.

Before you start to migrate users, create a user migration Lambda function in your AWS account, and set the Lambda function as the user migration trigger in your user pool. Add an authorization policy to your Lambda function that permits only the Amazon Cognito service account principal, cognito-idp.amazonaws.com to invoke the Lambda function, and only in the context of your own user pool. For more information, see Using resource-based policies for AWS Lambda (Lambda function policies).

Sign-in process

  1. The user opens your app and signs in with the Amazon Cognito user pools API or through managed login. For more information about how to facilitate sign-in with Amazon Cognito APIs, see Integrating Amazon Cognito authentication and authorization with web and mobile apps.

  2. Your app sends the user name and password to Amazon Cognito. If your app has a custom sign-in UI that you built with an AWS SDK, your app must use InitiateAuth or AdminInitiateAuth with the USER_PASSWORD_AUTH or ADMIN_USER_PASSWORD_AUTH flow. When your app uses one of these flows, the SDK sends the password to the server.

    Note

    Before you add a user migration trigger, activate the USER_PASSWORD_AUTH or ADMIN_USER_PASSWORD_AUTH flow in the settings of your app client. You must use these flows instead of the default USER_SRP_AUTH flow. Amazon Cognito must send a password to your Lambda function so that it can verify your user's authentication in the other directory. An SRP obscures your user's password from your Lambda function.

  3. Amazon Cognito checks if the submitted user name matches a user name or alias in the user pool. You can set the user's email address, phone number, or preferred user name as an alias in your user pool. If the user doesn't exist, Amazon Cognito sends parameters, including the user name and password, to your Migrate user Lambda trigger function.

  4. Your Migrate user Lambda trigger function checks for or authenticates the user with your existing user directory or user database. The function returns user attributes that Amazon Cognito stores in the user's profile in the user pool. You can return a username parameter only if the submitted user name matches an alias attribute. If you want users to continue to use their existing passwords, your function sets the attribute finalUserStatus to CONFIRMED in the Lambda response. Your app must return all "response" parameters shown at Migrate user Lambda trigger parameters.

    Important

    Do not log the entire request event object in your user migration Lambda code. This request event object includes the user's password. If you don't sanitize the logs, passwords appear in CloudWatch Logs.

  5. Amazon Cognito creates the user profile in your user pool, and returns tokens to your app client.

  6. Your app performs token intake, accepts the user authentication, and proceeds to the requested content.

After you migrate your users, use USER_SRP_AUTH for sign-in. The Secure Remote Password (SRP) protocol doesn't send the password across the network, and provides security benefits over the USER_PASSWORD_AUTH flow that you use during migration.

In case of errors during migration, including client device or network issues, your app receives error responses from the Amazon Cognito user pools API. When this happens, Amazon Cognito might or might not create the user account in your user pool. The user should then attempt to sign in again. If sign-in fails repeatedly, attempt to reset the user's password with the forgot-password flow in your app.

The forgot-password flow also invokes your Migrate user Lambda trigger function with a UserMigration_ForgotPassword event source. Because the user doesn't submit a password when they request a password reset, Amazon Cognito doesn't include a password in the event that it sends to your Lambda function. Your function can only look up the user in your existing user directory and return attributes to add to the user profile in your user pool. After your function completes its invocation and returns its response to Amazon Cognito, your user pool sends a password reset code by email or SMS. In your app, prompt your user for their confirmation code and a new password, then send that information to Amazon Cognito in a ConfirmForgotPassword API request. You can also use the built-in pages for the forgot-password flow in managed login.

Additional resources