Manage authentication methods in AWS SDKs - Amazon Cognito
Choice-based authenticationClient-based authentication

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.

  1. EMAIL_OTP and SMS_OTP

    Passwordless sign-in with one-time passwords

  2. WEB_AUTHN

    Passkey sign-in

  3. PASSWORD

    Sign-in with persistent passwords

    Sign-in with persistent passwords and secure payload

    MFA after sign-in

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.

  1. Request options with AuthParameters of USERNAME only. Amazon Cognito returns a SELECT_CHALLENGE challenge. From there, your application can prompt the user to select a challenge and return this response to your user pool.

  2. Request a preferred challenge with AuthParameters of PREFERRED_CHALLENGE. If your user, user pool, and app client are all configured for the preferred challenge, Amazon Cognito responds with that challenge. If the preferred challenge isn't available, Amazon Cognito responds with SELECT_CHALLENGE and a list of available challenges.

  3. Sign users in first, then request their choice-based authentication options. A GetUserAuthFactors request with the access token of a signed-in user returns their available choice-based authentication factors and their MFA settings. With this option, a user can sign in with username and password first, then activate a different form of authentication. You can also use this operation to check additional options for a user who has signed in with a preferred challenge.

Client-based authentication

Client-based authentication supports the following authentication flows.

  1. USER_PASSWORD_AUTH and ADMIN_USER_PASSWORD_AUTH

    Sign-in with persistent passwords

    MFA after sign-in

  2. USER_SRP_AUTH

    Sign-in with persistent passwords and secure payload

    MFA after sign-in

  3. REFRESH_TOKEN_AUTH

    Refresh tokens

  4. CUSTOM_AUTH

    Custom authentication

Client-based authentication is an assumption that your application has determined how your user wants to authenticate before it begins an authentication flow. 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.