Migrate User Lambda Trigger - Amazon Cognito
Migrate User Lambda Trigger SourcesMigrate User Lambda Trigger ParametersExample: Migrate a User with an Existing Password
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

Migrate User Lambda Trigger

Amazon Cognito invokes this trigger when a user does not exist in the user pool at the time of sign-in with a password, or in the forgot-password flow. After the Lambda function returns successfully, Amazon Cognito creates the user in the user pool. For details on the authentication flow with the user migration Lambda trigger see Importing Users into User Pools With a User Migration Lambda Trigger.

You can migrate users from your existing user directory into Amazon Cognito user pools at the time of sign-in, or during the forgot-password flow with this Lambda trigger.

Migrate User Lambda Trigger Sources

triggerSource value Triggering event
UserMigration_Authentication User migration at the time of sign in.
UserMigration_ForgotPassword User migration during forgot-password flow.

Migrate User Lambda Trigger Parameters

These are the parameters required by this Lambda function in addition to the common parameters.

JSON
{
    "userName": "string",
    "request": {
        "password": "string",
        "validationData": {
            "string": "string",
            . . .
        },
        "clientMetadata": {
      	"string": "string",
      	. . .
        }
    },
    "response": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "finalUserStatus": "string",
        "messageAction": "string",
        "desiredDeliveryMediums": [ "string", . . .],
        "forceAliasCreation": boolean
    }
}

Migrate User Request Parameters

userName

The username entered by the user.

password

The password entered by the user for sign-in. It is not set in the forgot-password flow.

validationData

One or more key-value pairs containing the validation data in the user's sign-in request. You can pass this data to your Lambda function by using the ClientMetadata parameter in the InitiateAuth and AdminInitiateAuth API actions.

clientMetadata

One or more key-value pairs that you can provide as custom input to the Lambda function that you specify for the migrate user trigger. You can pass this data to your Lambda function by using the ClientMetadata parameter in the AdminRespondToAuthChallenge and ForgotPassword API actions.

Migrate User Response Parameters

userAttributes

This field is required.

It must contain one or more name-value pairs representing user attributes to be stored in the user profile in your user pool. You can include both standard and custom user attributes. Custom attributes require the custom: prefix to distinguish them from standard attributes. For more information see Custom attributes.

Note

In order for users to reset their passwords in the forgot-password flow, they must have either a verified email or a verified phone number. Amazon Cognito sends a message containing a reset password code to the email or phone number in the user attributes.

Attributes Requirement
Any attributes marked as required when you created your user pool If any required attributes are missing during the migration, default values will be used.
username

Required if you have configured your user pool with email and/or preferred_username aliases in addition to username for sign-in, and the user has entered an email or phone number to sign-in.

Otherwise, it is optional and will be used as the username instead of the username entered by the user.

Note

username must be unique in the user pool.

finalUserStatus

During sign-in, this attribute can be set to CONFIRMED, or not set, to auto-confirm your users and allow them to sign-in with their previous passwords. This is the simplest experience for the user.

If this attribute is set to RESET_REQUIRED, the user is required to change his or her password immediately after migration at the time of sign-in, and your client app needs to handle the PasswordResetRequiredException during the authentication flow.

Note

The password policy for the new user pool should not be stronger than the password policy from your existing user directory.

messageAction

This attribute can be set to "SUPPRESS" to suppress the welcome message usually sent by Amazon Cognito to new users. If this attribute is not returned, the welcome message will be sent.

desiredDeliveryMediums

This attribute can be set to "EMAIL" to send the welcome message by email, or "SMS" to send the welcome message by SMS. If this attribute is not returned, the welcome message will be sent by SMS.

forceAliasCreation

If this parameter is set to "true" and the phone number or email address specified in the UserAttributes parameter already exists as an alias with a different user, the API call will migrate the alias from the previous user to the newly created user. The previous user will no longer be able to log in using that alias.

If this attribute is set to "false" and the alias exists, the user will not be migrated, and an error is returned to the client app.

If this attribute is not returned, it is assumed to be "false".

Example: Migrate a User with an Existing Password

This example Lambda function migrates the user with an existing password and suppresses the welcome message from Amazon Cognito.

Node.js
exports.handler = (event, context, callback) => {

    var user;

    if ( event.triggerSource == "UserMigration_Authentication" ) {

        // authenticate the user with your existing user directory service
        user = authenticateUser(event.userName, event.request.password);
        if ( user ) {
            event.response.userAttributes = {
                "email": user.emailAddress,
                "email_verified": "true"
            };
            event.response.finalUserStatus = "CONFIRMED";
            event.response.messageAction = "SUPPRESS";
            context.succeed(event);
        }
        else {
            // Return error to Amazon Cognito
            callback("Bad password");
        }
    }
    else if ( event.triggerSource == "UserMigration_ForgotPassword" ) {

        // Lookup the user in your existing user directory service
        user = lookupUser(event.userName);
        if ( user ) {
            event.response.userAttributes = {
                "email": user.emailAddress,
                // required to enable password-reset code to be sent to user
                "email_verified": "true"  
            };
            event.response.messageAction = "SUPPRESS";
            context.succeed(event);
        }
        else {
            // Return error to Amazon Cognito
            callback("Bad password");
        }
    }
    else { 
        // Return error to Amazon Cognito
        callback("Bad triggerSource " + event.triggerSource);
    }
};