Manage authentication methods in AWS SDKs

Users in Amazon Cognito user pools can sign in with a variety of initial sign-in options, or factors. For some factors, users can follow up with multi-factor authentication (MFA). These first factors include username and password, one-time password, passkey, and custom authentication. For more information, see Authentication flows. When your application has built-in UI components and imports an AWS SDK module, you must build application logic for authentication. You must choose one of two primary methods and from that method, the authentication mechanisms that you want to implement.

You can implement client-based authentication where your application, or client, declares the type of authentication up front. Your other option is choice-based authentication, where your app collects a username and requests the available authentication types for users. You can implement these models together in the same application or split between app clients, according to your requirements. Each method has features that are unique to it, for example custom authentication in client-based and passwordless authentication in choice-based.

In custom-built applications that perform authentication with AWS SDK implementation of the users pools API, you must structure your API requests to align with user pool configuration, app client configuration, and client-side preferences. An InitiateAuth session that begins with an AuthFlow of USER_AUTH begins choice-based authentication. Amazon Cognito responds to your API with a challenge of either a preferred authentication method or a list of choices. A session that begins with AuthFlow of CUSTOM_AUTH goes right into custom authentication with Lambda triggers.

Some authentication methods are fixed to one of the two flow types, and some methods are available in both.

Choice-based authentication

Your application can request the following authentication methods in choice-based authentication. Declare these options in the PREFERRED_CHALLENGE parameter of InitiateAuth or AdminInitiateAuth, or in the ChallengeName parameter of RespondToAuthChallenge or AdminRespondToAuthChallenge.

To review these options in their API context, see ChallengeName in RespondToAuthChallenge.

Choice-based sign-in issues a challenge in response to your initial request. This challenge either verifies that a requested option is available, or provides a list of available choices. Your application can display these choices to users, who then enter credentials for their preferred sign-in method and proceed with authentication in challenge responses.

You have the following choice-based options in your authentication flow. All requests of this type require that your app first collect a username or retrieve it from a cache.

To configure your app client for choice-based authentication, add ALLOW_USER_AUTH to the allowed authentication flows. You must also choose the choice-based factors that you want to permit in your user pool configuration. The following process illustrates how to choose choice-based authentication factors.

Amazon Cognito console

To configure choice-based authentication options in a user pool

1. Sign in to AWS and navigate to the Amazon Cognito user pools console. Choose a user pool or create a new one.

2. In your user pool configuration, select the Sign-in menu. Locate Options for choice-based sign-in and choose Edit.

3. The Password option is always available. This includes the PASSWORD and PASSWORD_SRP flows. Select the Additional choices that you want to add to your users' options. You can add Passkey for WEB_AUTHN, Email message one-time password for EMAIL_OTP, and SMS message one-time password for SMS_OTP.

4. Choose Save changes.

API/SDK

The following partial CreateUserPool or UpdateUserPool request body configures all available options for choice-based authentication.

"Policies": {
    "SignInPolicy": {
        "AllowedFirstAuthFactors": [
            "PASSWORD",
            "WEB_AUTHN",
            "EMAIL_OTP",
            "SMS_OTP"
        ]
    }
},

Client-based authentication

Client-based authentication supports the following authentication flows. Declare these options in the AuthFlow parameter of InitiateAuth or AdminInitiateAuth.

With client-based authentication, Amazon Cognito assumes that you have determined how your user wants to authenticate before they begin authentication flows. The logic of determining the sign-in factor that a user wants to provide must be determined with default settings or custom prompts, then declared in the first request to your user pool. The InitiateAuth request declares a sign-in AuthFlow that directly corresponds to one of the listed options, for example USER_SRP_AUTH. With this declaration, the request also includes the parameters to begin authentication, for example USERNAME, SECRET_HASH, and SRP_A. Amazon Cognito might follow up this request with additional challenges like PASSWORD_VERIFIER for SRP or SOFTWARE_TOKEN_MFA for password sign-in with TOTP MFA.

To configure your app client for client-based authentication, add any authentication flows other than ALLOW_USER_AUTH to the allowed authentication flows. Examples are ALLOW_USER_PASSWORD_AUTH, ALLOW_CUSTOM_AUTH, ALLOW_REFRESH_TOKEN_AUTH. To permit client-based authentication flows, no additional user pool configuration is required.

Step-up authentication with the USER_AUTH flow

You request step-up authentication in the existing USER_AUTH flow with the InitiateAuth and RespondToAuthChallenge operations. There are no new API operations. The corresponding server-side operations, AdminInitiateAuth and AdminRespondToAuthChallenge, support the same step-up parameters and behavior, and AdminInitiateAuth can also optionally take an access token. This flow works both when a user has an existing ID token and when a user authenticates toward a target level for the first time. For more information about the flow, see An example authentication session.

For more information about ACR levels and AMR values, see Authentication levels with ACR and AMR claims.

You pass the step-up parameters in the AuthParameters map of your InitiateAuth (or AdminInitiateAuth) request: the new TARGET_ACR_VALUES and MAX_AGE, together with the existing USERNAME, ACCESS_TOKEN, and PREFERRED_CHALLENGE. For the definition and constraints of each parameter, see InitiateAuth and AdminInitiateAuth in the Amazon Cognito user pools API Reference.

The following table describes how Amazon Cognito responds to combinations of these parameters.

Keep the following behavior in mind when you design a step-up authentication flow.

Requesting step-up authentication with TARGET_ACR_VALUES requires the Essentials or Plus feature plan. For more information, see Feature plan requirements.