How do I implement passwordless authentication in my Cognito user pool?

Short description

Amazon Cognito supports two passwordless authentication methods:

• Passwordless sign-in with one-time passwords (OTP)
• Passwordless sign-in with WebAuthn passkeys

Important:

• If you require multi-factor authentication (MFA) in your user pool, then you can't use Passwordless authentication.
• After a user initially authenticates, you can register up to 20 WebAuthn passkeys.
• Passwordless authentication is available only in the choice-based authentication AuthFlow of ALLOW_USER_AUTH.
• You must have the Essentials or Plus feature plan to use choice-based authentication.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

OTP authentication

Activate OTP authentication

Complete the following steps:

1. Open the Amazon Cognito console.
2. Select your user pool.
3. Under Authentication, choose the Sign-in tab.
4. For Options for choice-based sign-in, choose Edit.
5. Choose either Email message one-time password or SMS message one-time password.
6. Choose Save changes.
7. Choose App clients, and then select your app client. Or, create a new one.
8. Under App client information, choose Edit.
9. Choose Choice-based sign-in: ALLOW_USER_AUTH.
10. Choose Save changes.

Implement OTP authentication

Passwordless authentication works only with managed login. The classic hosted UI doesn't support built-in passwordless authentication flows. For more information, see Things to know about authentication with user pools.

To implement OTP, complete the following steps:

1. Set up managed login.
2. Configure your prefix domain to direct users to enter their username on the managed login page. To use a custom domain, see Using your own domain for managed login.

To use the AWS CLI, complete the following steps:

1. Run the initiate-auth command to start the authentication:

   aws cognito-idp initiate-auth --auth-flow USER_AUTH --auth-parameters USERNAME=example_username --client-id example_clientid

   Note: Replace all example values with your values. If you include a PREFERRED_CHALLENGE in the preceding command, then proceed to step 4.

2. The response includes the following available challenges:

   {
      "AvailableChallenges": [ 
         "EMAIL_OTP", 
         "SMS_OTP",
         "PASSWORD"
       ],
      "Session": "[Session ID]"
   }

   Note: Use the session ID from the preceding response in all subsequent authentication commands within the same authentication flow.

3. After users select their preferred authentication method, run the respond-to-auth-challenge command to submit their choice:

   aws cognito-idp respond-to-auth-challenge --challenge-name SELECT_CHALLENGE --challenge-responses USERNAME=example_username,ANSWER=EMAIL_OTP --client-id example_clientid --session "SESSION_ID_FROM_PREVIOUS_RESPONSE"

   Note: If the user is eligible for the selected challenge method, then Amazon Cognito sends a code to the user's email or phone number.

4. To start the authentication method with a specific PREFERRED_CHALLENGE, run the initiate-auth command:

   aws cognito-idp initiate-auth --auth-flow USER_AUTH --auth-parameters USERNAME=example_username,PREFERRED_CHALLENGE=EMAIL_OTP --client-id example_clientid

   Note: Replace EMAIL_OTP with SMS_OTP if you prefer SMS authentication. If the user is eligible for the PREFERRED_CHALLENGE method, then Amazon Cognito sends a code to the user's email or phone number.

5. Run the respond-to-auth-challenge command to return a response:

   aws cognito-idp admin-respond-to-auth-challenge --challenge-name EMAIL_OTP --challenge-responses USERNAME=example_username,EMAIL_OTP_CODE=OTP_EMAIL --client-id example_clientid --session "SESSION_ID_FROM_PREVIOUS_RESPONSE"

   Note: Replace EMAIL_OTP with SMS_OTP and EMAIL_OTP_CODE with SMS_OTP_CODE if you're using SMS authentication.

After OTP verification, your users receive the JSON web tokens (JWTs) that Amazon Cognito generated.

WebAuthn passkey authentication

Activate WebAuthn passkey authentication

Complete the following steps:

1. Open the Amazon Cognito console.
2. Select your user pool.
3. Under Authentication, choose the Sign-in tab.
4. For Options for choice-based sign-in, choose Edit, and then add Passkey to the available choices.
5. Choose Edit passkey, and then configure the following settings:
   Set User verification mode to Preferred or Required.
   Set the Relying Party ID to your user pool domain, custom domain, or third-party domain.
   Note: The Relying Party ID controls the domain that can use the passkey for registration and authentication.
6. Choose Save changes.
7. Choose App clients, and then select your app client. Or, create a new one.
8. Under App client information, choose Edit.
9. Choose Choice-based sign-in: ALLOW_USER_AUTH.
10. Choose Save changes.

Register WebAuthn passkey for a user in managed login

Complete the following steps:

1. Set up managed login on the app client.
   Note: Amazon Cognito automatically prompts for passkey setup for new user registration.

2. For current users who haven't registered a passkey, configure your application to redirect them to the following authentication endpoint:
   https://auth.example.com/oauth2/authorize/?client_id=1example23456789&response_type=code&scope=email+openid+phone&redirect_uri=https://www.example.com 

3. Exchange the authorization code for tokens.

4. Run the following list-web-authn-credentials command to check for registered passkeys:

   aws cognito-idp list-web-authn-credentials --access-token token-from-above-step

   Example output:

   {
       "Credentials": [
           {
               "CredentialId": "r8DCexamplecredentialsaWMQ",
               "FriendlyCredentialName": "Chrome on Mac",
               "RelyingPartyId": "<cognito-prefix>.auth.us-east-1.amazoncognito.com",
               "AuthenticatorAttachment": "platform",
               "AuthenticatorTransports": [
                   "internal"
               ],
               "CreatedAt": "2025-06-27T07:41:15.800000+00:00"
           }
       ]
   }

5. If the preceding command returns an empty list, then redirect users to the following managed login URL to begin the passkey registration process:
   https://cognito-managed-login-domain/passkeys/add?client_id=example_client_id&redirect_uri=https://www.example.com
   Note: Make sure that you have an active browser session from Cognito managed login. Also, add required OAuth parameters, such as response_type and scope.

On the passkeys/add URL page, the user adds a passkey. Amazon Cognito then redirects the user to the application page that you specified in the redirect_uri parameter. For subsequent logins on the managed login page, the user can sign in with their registered passkey.

Related information

Authorization models for API and SDK authentication

Authentication with Amazon Cognito user pools

Authentication flows