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

Modern authentication flows incorporate new challenge types, in addition to a password, to verify the identity of users. We generalize authentication into two common steps, which are implemented through two API operations: InitiateAuth and RespondToAuthChallenge.

A user authenticates by answering successive challenges until authentication either fails or the user is issued tokens. With these two steps, which can be repeated to include different challenges, we can support any custom authentication flow.

You can customize your authentication flow with Amazon Lambda triggers. These triggers issue and verify their own challenges as part of the authentication flow.

You can also use admin authentication flow for use on secure backend servers. You can use the user migration authentication flow to allow user migration without requiring your users to reset their passwords.

Client-Side Authentication Flow

Here's how user pool authentication works for end-user client-side apps created 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 an end-user app, but instead you're using 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 that for client-side apps, except for the following:

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

Custom Authentication Flow

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

The custom authentication flow is designed to allow for a series of challenge and response cycles that can be customized to meet different requirements. The flow starts with a call to the InitiateAuth API operation that indicates the type of authentication that will be used and provides any initial authentication parameters. Amazon Cognito will respond to the InitiateAuth call with one of the following:

If Amazon Cognito responds to the InitiateAuth call with a challenge, the app gathers more input and calls the RespondToAuthChallenge operation, providing the challenge responses and passing back the session. Amazon Cognito responds to the RespondToAuthChallenge call similarly to the InitiateAuth call, providing tokens if the user is signed in, another challenge, or an error. If another challenge is returned, the sequence repeats with the app calling RespondToAuthChallenge until the user is signed in or an error is returned. More details are provided in the API documentation for the InitiateAuth and RespondToAuthChallenge API operations.

Built-in Authentication Flow and Challenges

Amazon Cognito has some built-in AuthFlow and ChallengeName values for a standard authentication flow to validate user name and password through the Secure Remote Password (SRP) protocol. This flow is built into the iOS, Android, and JavaScript SDKs for Amazon Cognito. At a high level, the flow starts by sending USER_SRP_AUTH as the AuthFlow to InitiateAuth along with USERNAME and SRP_A values in AuthParameters. If the InitiateAuth call is successful, the response 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 is signed in, the tokens are returned. If multi-factor authentication (MFA) is enabled for the user, a ChallengeName of SMS_MFA is returned, and 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, the challenges and verification of the responses are controlled through three Amazon Lambda triggers.

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 need to start with it.

For more information about the Lambda triggers, including sample code, see Customizing User Pool Workflows with Lambda Triggers.

Admin authentication flow

The API operations described Custom Authentication Flow with the use of SRP for password verification is the recommended approach for authentication. The iOS, Android, and JavaScript SDKs are based on that approach and make it easy to use SRP. However, there is an alternative set of admin API operations designed for use on secure backend servers if you want to avoid the SRP calculations. For these backend admin implementations, AdminInitiateAuth is used in place of InitiateAuth, and AdminRespondToAuthChallenge is used in place of RespondToAuthChallenge. When using these operations, the password can be submitted as plaintext so the SRP calculations are not needed. 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 use in Lambda functions. In order to use these operations and have them accept passwords in plaintext, you must enable 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 ADMIN_USER_PASSWORD_AUTH AuthFlow is not accepted for the InitiateAuth and RespondToAuthChallenge operations.

In the AdminInitiateAuth response ChallengeParameters, the USER_ID_FOR_SRP attribute, if present, will contain 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 allows easy migration of users from a legacy user management system into your user pool. To avoid making your users reset their passwords during user migration, choose the USER_PASSWORD_AUTH authentication flow. This flow sends your users' passwords to the service over an encrypted SSL connection during authentication.

When you have completed migrating all your users, we recommend switching flows to the more secure SRP flow. The SRP flow does not 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.