Menu
Amazon Cognito
Developer Guide (Version Last Updated: 08/26/2017)

Signing Up and Confirming User Accounts

User accounts are added to your user pool in one of the following ways:

Users who sign themselves up need to be confirmed before they can sign in. Imported and created users are already confirmed, but they need to create their password the first time they sign in. The following sections explain the confirmation process and email and phone verification.

Overview of User Account Confirmation

The following diagram illustrates the confirmation process:


          When users enter the confirmation code, they automatically verify email or
            phone.

A user account can be in any of the following states:

Registered (Unconfirmed)

The user has successfully signed up, but cannot sign in until the user account is confirmed. The user is enabled but not confirmed in this state.

New users who sign themselves up start in this state.

Confirmed

The user account is confirmed and the user can sign in. If the user confirmed the user account by entering a confirmation code that was received via email or phone (SMS)—or, in the case of email, by clicking a confirmation link—that email or phone number is automatically verified. If the user account was confirmed by the administrator or a Pre Sign-up Lambda trigger, there might not be a verified email or phone number associated with the account.

Password Reset Required

The user account is confirmed, but the user must request a code and reset his or her password before he or she can sign in.

User accounts that are imported by an administrator or developer start in this state.

Force Change Password

The user account is confirmed and the user can sign in using a temporary password, but on first sign-in, the user must change his or her password to a new value before doing anything else.

User accounts that are created by an administrator or developer start in this state.

Disabled

Before a user account can be deleted, it must be disabled.

Allowing Users to Sign Up and Confirm Themselves and Verify Email or Phone

  1. A user signs up in your app by entering a username, phone number and/or email address, and possibly other attributes.

  2. The Amazon Cognito service receives the sign-up request from the app. After verifying that the request contains all attributes required for sign-up, the service completes the sign-up process and sends a confirmation code to the user's phone (via SMS) or email.

    Note

    If a user signs up with both a phone number and an email address, and your user pool settings require verification of both attributes, a verification code is sent via SMS to the phone. The email address is not verified. Your app can call GetUser to see if an email address is awaiting verification. If it is, the app should call GetUserAttributeVerificationCode to initiate the email verification flow and then submit the verification code by calling VerifyUserAttribute.

  3. The service returns to the app that sign-up is complete and that the user account is pending confirmation. The response contains information about where the confirmation code was sent. At this point the user's account is in an unconfirmed state, and the user's email address and phone number are unverified.

  4. The app can now prompt the user to enter the confirmation code. It is not necessary for the user to enter the code immediately. However, the user will not be able to sign in until after they enter the confirmation code.

  5. The user enters the confirmation code in the app.

  6. The app calls ConfirmSignUp to send the code to the Amazon Cognito service, which verifies the code and, if the code is correct, sets the user's account to the confirmed state. After successfully confirming the user account, the Amazon Cognito service automatically marks the attribute that was used to confirm (email or phone number) as verified. Unless the value of this attribute is changed, the user will not have to verify it again.

  7. At this point the user's account is in a confirmed state, and the user can sign in.

Allowing Users to Sign Up in Your App but Confirming Them as Administrator

  1. A user signs up in your app by entering a username, phone number and/or email address, and possibly other attributes.

  2. The Amazon Cognito service receives the sign-up request from the app. After verifying that the request contains all attributes required for sign-up, the service completes the sign-up process and returns to the app that sign-up is complete, pending confirmation. At this point the user's account is in an unconfirmed state. The user cannot sign in until the account is confirmed.

  3. The administrator confirms the user's account, either in the Amazon Cognito console (by finding the user account in the Users tab and choosing the Confirm button) or in the CLI (by using the admin-confirm-sign-up command). Both the Confirm button and the admin-confirm-sign-up command use the AdminConfirmSignUp API to perform the confirmation.

  4. At this point the user's account is in a confirmed state, and the user can sign in.

Computing SecretHash Values

The following Amazon Cognito User Pools APIs have a SecretHash parameter:

The SecretHash value is a Base 64-encoded keyed-hash message authentication code (HMAC) calculated using the secret key of a user pool client and username plus the client ID in the message. The following pseudocode shows how this value is calculated. In this pseudocode, + indicates concatenation, HMAC_SHA256 represents a function that produces an HMAC value using HmacSHA256, and Base64 represents a function that produces Base-64-encoded version of the hash output.

Copy
Base64 ( HMAC_SHA256 ( "Client Secret Key", "Username" + "Client Id" ) )

Alternatively, you can use the following code example in your server-side Java application code:

Copy
import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public static String calculateSecretHash(String userPoolClientId, String userPoolClientSecret, String userName) { final String HMAC_SHA256_ALGORITHM = "HmacSHA256"; SecretKeySpec signingKey = new SecretKeySpec( userPoolClientSecret.getBytes(StandardCharsets.UTF_8), HMAC_SHA256_ALGORITHM); try { Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM); mac.init(signingKey); mac.update(userName.getBytes(StandardCharsets.UTF_8)); byte[] rawHmac = mac.doFinal(userPoolClientId.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(rawHmac); } catch (Exception e) { throw new RuntimeException("Error while calculating "); } }

Confirming User Accounts Without Verifying Email or Phone Number

The Pre-Sign Up Lambda trigger can be used to auto-confirm user accounts at sign-up time, without requiring a confirmation code or verifying email or phone number. Users who are confirmed this way can immediately sign in without having to receive a code.

You can also mark a user's email or phone number verified through this trigger.

Note

While this approach is convenient for users when they're getting started, we recommend auto-verifying at least one of email or phone number. Otherwise the user can be left unable to recover if they forget their password.

If you don't require the user to receive and enter a confirmation code at sign-up and you don't auto-verify email and phone number in the Pre-Sign Up Lambda trigger, you risk not having a verified email address or phone number for that user account. The user can verify the email address or phone number at a later time. However, if the user forgets his or her password and doesn't have a verified email address or phone number, the user is locked out of the account, because the Forgot Password flow requires a verified email or phone number in order to send a verification code to the user.

Verifying When Users Change Their Email or Phone Number

When a user changes his or her email address or phone number in your app, that attribute is marked as unverified. If auto-verification was enabled for the attribute being updated, the service immediately sends the user a message containing a verification code, which the user should enter to verify the change. You can use a Custom Message Lambda trigger to customize this message. For more information, see Customizing User Pool Workflows by Using AWS Lambda Triggers. Whenever the user's email address or phone number is unverified, your app should display the unverified status and provide a button or link for users to verify their new email or phone number.

Confirmation and Verification Processes for User Accounts Created by Administrators or Developers

User accounts that are created by an administrator or developer are already in the confirmed state, so users aren't required to enter a confirmation code. The invitation message that the Amazon Cognito service sends to these users includes the username and a temporary password. The user is required to change the password before signing in. For more information, see the Message Customizations Tab in Creating User Accounts as Administrator in the AWS Management Console and with the Amazon Cognito User Pools API and the Custom Message trigger in Customizing User Pool Workflows by Using AWS Lambda Triggers.

Confirmation and Verification Processes for Imported User Accounts

User accounts that are created by using the user import feature in the AWS Management Console, CLI, or API (see Importing Users into User Pools) are already in the confirmed state, so users aren't required to enter a confirmation code. No invitation message is sent. However, imported user accounts require users to first request a code by calling the ForgotPassword API and then create a password using the delivered code by calling ConfirmForgotPassword API before they sign in. For more information, see Requiring Imported Users to Reset Their Passwords.

Either the user's email or phone number must be marked as verified when the user account is imported, so no verification is required when the user signs in.