Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

User pool authentication flow

To verify the identity of users, modern authentication flows incorporate new challenge types, in addition to passwords. Amazon Cognito authentication typically requires that you implement two API operations in the following order:

A user authenticates by answering successive challenges until authentication either fails or Amazon Cognito issues tokens to the user. You can repeat these steps with Amazon Cognito, in a process that includes different challenges, to support any custom authentication flow.

You can use Amazon Lambda triggers to customize the way users authenticate. These triggers issue and verify their own challenges as part of the authentication flow.

You can also use the admin authentication flow for secure backend servers. You can use the user migration authentication flow to make user migration possible without the requirement that your users to reset their passwords.

Client-side authentication flow

The following process works for user client-side apps that you create with the Amazon Mobile SDK for Android, Amazon Mobile SDK for iOS, or Amazon SDK for JavaScript:

Server-side authentication flow

If you don't have a user app, but instead you use a Java, Ruby, or Node.js secure backend or server-side app, you can use the authenticated server-side API for Amazon Cognito user pools.

For server-side apps, user pool authentication is similar to authentication for client-side apps, except for the following:

The AdminInitiateAuth and AdminRespondToAuthChallenge API operations can't accept username-and-password user credentials for admin sign-in, unless you explicitly enable them to do so in one of the following ways:

Custom authentication flow

Amazon Cognito user pools also make it possible to use custom authentication flows, which can help you create a challenge/response-based authentication model using Amazon Lambda triggers.

The custom authentication flow makes possible customized challenge and response cycles to meet different requirements. The flow starts with a call to the InitiateAuth API operation that indicates the type of authentication to use and provides any initial authentication parameters. Amazon Cognito responds to the InitiateAuth call with one of the following types of information:

If Amazon Cognito responds to the InitiateAuth call with a challenge, the app gathers more input and calls the RespondToAuthChallenge operation. This call provides the challenge responses and passes it back the session. Amazon Cognito responds to the RespondToAuthChallenge call similarly to the InitiateAuth call. If the user has signed in, Amazon Cognito provides tokens, or if the user isn't signed in, Amazon Cognito provides another challenge, or an error. If Amazon Cognito returns another challenge, the sequence repeats and the app calls RespondToAuthChallenge until the user successfully signs in or an error is returned. For more details about the InitiateAuth and RespondToAuthChallenge API operations, see the API documentation.

Built-in authentication flow and challenges

Amazon Cognito contains built-in AuthFlow and ChallengeName values so that a standard authentication flow can validate a user name and password through the Secure Remote Password (SRP) protocol. The Amazon SDKs have built-in support for these flows with Amazon Cognito.

The flow starts by sending USER_SRP_AUTH as the AuthFlow to InitiateAuth. You also send USERNAME and SRP_A values in AuthParameters. If the InitiateAuth call is successful, the response has included PASSWORD_VERIFIER as the ChallengeName and SRP_B in the challenge parameters. The app then calls RespondToAuthChallenge with the PASSWORD_VERIFIER ChallengeName and the necessary parameters in ChallengeResponses. If the call to RespondToAuthChallenge is successful and the user signs in, Amazon Cognito issues tokens. If you activated multi-factor authentication (MFA) for the user, Amazon Cognito returns the ChallengeName of SMS_MFA. The app can provide the necessary code through another call to RespondToAuthChallenge.

Custom authentication flow and challenges

An app can initiate a custom authentication flow by calling InitiateAuth with CUSTOM_AUTH as the Authflow. With a custom authentication flow, three Lambda triggers control challenges and verification of the responses.

A custom authentication flow can also use a combination of built-in challenges, such as SRP password verification and MFA through SMS. It can use custom challenges such as CAPTCHA or secret questions.

Use SRP password verification in custom authentication flow

If you want to include SRP in a custom authentication flow, you must begin with SRP.

For more information about the Lambda triggers, including sample code, see Customizing user pool workflows with Lambda triggers.

Admin authentication flow

Best practice for authentication is to use the API operations described in Custom authentication flow with SRP for password verification. The Amazon SDKs use that approach, and this approach helps them to use SRP. However, if you want to avoid SRP calculations, an alternative set of admin API operations is available for secure backend servers. For these backend admin implementations, use AdminInitiateAuth in place of InitiateAuth. Also, use AdminRespondToAuthChallenge in place of RespondToAuthChallenge. Because you can submit the password as plaintext, you do not have to do SRP calculations when you use these operations. . Here is an example:

AdminInitiateAuth Request {
    "AuthFlow":"ADMIN_USER_PASSWORD_AUTH",
    "AuthParameters":{
        "USERNAME":"<username>",
        "PASSWORD":"<password>"
        },
    "ClientId":"<clientId>",
    "UserPoolId":"<userPoolId>"
}

These admin authentication operations require developer credentials and use the Amazon Signature Version 4 (SigV4) signing process. These operations are available in standard Amazon SDKs, including Node.js, which is convenient for Lambda functions. To use these operations and have them accept passwords in plaintext, you must activate them for the app in the console. Alternatively, you can pass ADMIN_USER_PASSWORD_AUTH for the ExplicitAuthFlow parameter in calls to CreateUserPoolClient or UpdateUserPoolClient. The InitiateAuth and RespondToAuthChallenge operations do not accept the ADMIN_USER_PASSWORD_AUTH AuthFlow.

In the AdminInitiateAuth response ChallengeParameters, the USER_ID_FOR_SRP attribute, if present, contains the user's actual user name, not an alias (such as email address or phone number). In your call to AdminRespondToAuthChallenge, in the ChallengeResponses, you must pass this user name in the USERNAME parameter.

User migration authentication flow

A user migration Lambda trigger helps migrate users from a legacy user management system into your user pool. If you choose the USER_PASSWORD_AUTH authentication flow, users don't have to reset their passwords during user migration. This flow sends your users' passwords to the service over an encrypted SSL connection during authentication.

When you have migrated all your users, switch flows to the more secure SRP flow. The SRP flow doesn't send any passwords over the network.

To learn more about Lambda triggers, see Customizing user pool workflows with Lambda triggers.

For more information about migrating users with a Lambda trigger, see Importing users into user pools with a user migration Lambda trigger.