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.
Topics
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.
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.