Enable sign-up, sign-in, and sign-out

In this guide, you will set up sign-up, sign-in, and sign-out using the Amplify Libraries and then test this functionality. This includes a review of sign-up methods provided by Amplify, the specific user attributes used by Amazon Cognito, how to confirm users after initial sign-up, and the differences between local and global sign-out. Once set up, you can connect this functionality to your frontend UI.

Before you begin, you should have finished the Set up backend resources section of the Set up Amplify Auth guide.

Decide before you build

Before you enable sign-up, sign-in, and sign-out, you will need to make a few decisions to complete the process.

Which Amazon Cognito attributes will you pass for sign-up?

User attributes (such as username and email) are used to identify your users. These are set up when you configure your Cognito User Pool and cannot be renamed or deleted after they are added. You can use the Amplify CLI to add user attributes or visit the Amazon Cognito console. To add user attributes with the CLI, you can run the command amplify add auth for a new project, or use amplify update auth if you already have existing resources set up. Then, you can select manual configuration when prompted by the Amplify CLI.

? amplify update auth
? What do you want to do?
  'Walkthrough all the auth configurations'
# Accept defaults for everything else

# Select the attributes you want users to read/write
? Specify read attributes:
  'Birthdate, Email, Given Name'
? Specify write attributes:
  'Locale, Given Name'

How will you verify users at sign-up?

Once the initial sign-up is done, the user will need to verify and confirm their contact information before their account is activated. This is done by sending a verification code by email or phone number that can be collected on initial sign-up. Email verification asks the user to click a link or enter a code sent to their email address provided during sign-up. Phone verification is done by asking the user to enter the code sent to them in an SMS text message. You can also enable auto-confirmation to skip this step and automatically confirm the user after sign-up. This is accomplished using the pre sign-up Lambda trigger, which is explained in the Amazon Cognito documentation.

Once you have these decisions in mind, you are ready to enable sign-up, sign-in, and sign-out.

Add the sign-up, sign-in, and sign-out capabilities

You can add the functionality to enable sign-up, sign-in, and sign-out with the Amplify Libraries. You can connect this to an existing UI or create your own.

For many apps, user sign-up and sign-in with a username and password is all that is required. Once authenticated, the app can talk to an API to access and mutate data.

We will use the username and password authentication flow to get started. Both third-party social provider federation and Multi-factor authentication can be added after this initial set up.

Sign-up

You can create a new user in your backend by passing a username, password, and other attributes to signUp().

import { signUp } from 'aws-amplify/auth';

type SignUpParameters = {
  username: string;
  password: string;
  email: string;
  phone_number: string;
};

async function handleSignUp({
  username,
  password,
  email,
  phone_number
}: SignUpParameters) {
  try {
    const { isSignUpComplete, userId, nextStep } = await signUp({
      username,
      password,
      options: {
        userAttributes: {
          email,
          phone_number // E.164 number convention
        },
        // optional
        autoSignIn: true // or SignInOptions e.g { authFlowType: "USER_SRP_AUTH" }
      }
    });

    console.log(userId);
  } catch (error) {
    console.log('error signing up:', error);
  }
}

import { signUp } from 'aws-amplify/auth';

async function handleSignUp({ username, password, email, phone_number }) {
  try {
    const { isSignUpComplete, userId, nextStep } = await signUp({
      username,
      password,
      options: {
        userAttributes: {
          email,
          phone_number // E.164 number convention
        },
        // optional
        autoSignIn: true // or SignInOptions e.g { authFlowType: "USER_SRP_AUTH" }
      }
    });

    console.log(userId);
  } catch (error) {
    console.log('error signing up:', error);
  }
}

The signUp API response will include a nextStep property, which can be used to determine if further action is required. It may return the following next steps:

• CONFIRM_SIGN_UP - The sign up needs to be confirmed by collecting a code from the user and calling confirmSignUp.
• DONE - The sign up process has been fully completed.
• COMPLETE_AUTO_SIGN_IN - The sign up process needs to complete by invoking the autoSignIn API.

Confirm sign-up

By default, each user that signs up remains in the unconfirmed status until they verify with a confirmation code that was sent to their email or phone number. You can confirm the sign-up after retrieving a confirmation code from the user as shown here.

import { confirmSignUp, type ConfirmSignUpInput } from 'aws-amplify/auth';

async function handleSignUpConfirmation({
  username,
  confirmationCode
}: ConfirmSignUpInput) {
  try {
    const { isSignUpComplete, nextStep } = await confirmSignUp({
      username,
      confirmationCode
    });
  } catch (error) {
    console.log('error confirming sign up', error);
  }
}

import { confirmSignUp } from 'aws-amplify/auth';

async function handleSignUpConfirmation({ username, confirmationCode }) {
  try {
    const { isSignUpComplete, nextStep } = await confirmSignUp({
      username,
      confirmationCode
    });
  } catch (error) {
    console.log('error confirming sign up', error);
  }
}

Auto sign-in

The autoSignIn API will automatically sign-in a user when it was previously enabled by the signUp API and after any of the following cases has completed:

• User confirmed their account with a verification code sent to their phone or email (default option).
• User confirmed their account with a verification link sent to their phone or email. In order to enable this option you need to go to the Amazon Cognito console, look for your userpool, then go to the Messaging tab and enable link mode inside the Verification message option. Finally you need to define the signUpVerificationMethod to link inside the Cognito option of your Auth config.

import { autoSignIn } from 'aws-amplify/auth';

async function handleAutoSignIn() {
  try {
    const signInOutput = await autoSignIn();
    // handle sign-in steps
  } catch (error) {
    console.log(error);
  }
}

Sign-in

You pass a username and password to the signIn API to sign-in your end-users.

import { signIn, type SignInInput } from 'aws-amplify/auth';

async function handleSignIn({ username, password }: SignInInput) {
  try {
    const { isSignedIn, nextStep } = await signIn({ username, password });
  } catch (error) {
    console.log('error signing in', error);
  }
}

import { signIn } from 'aws-amplify/auth';

async function signIn({ username, password }) {
  try {
    const { isSignedIn, nextStep } = await signIn({ username, password });
  } catch (error) {
    console.log('error signing in', error);
  }
}

The signIn API response will include a nextStep property, which can be used to determine if further action is required. It may return the following next steps:

• CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED - The user was created with a temporary password and must set a new one. Complete the process with confirmSignIn.
• CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE - The sign-in must be confirmed with a custom challenge response. Complete the process with confirmSignIn.
• CONFIRM_SIGN_IN_WITH_TOTP_CODE - The sign-in must be confirmed with a TOTP code from the user. Complete the process with confirmSignIn.
• CONTINUE_SIGN_IN_WITH_TOTP_SETUP - The TOTP setup process must be continued. Complete the process with confirmSignIn.
• CONFIRM_SIGN_IN_WITH_SMS_CODE - The sign-in must be confirmed with a SMS code from the user. Complete the process with confirmSignIn.
• CONTINUE_SIGN_IN_WITH_MFA_SELECTION - The user must select their mode of MFA verification before signing in. Complete the process with confirmSignIn.
• RESET_PASSWORD - The user must reset their password via resetPassword.
• CONFIRM_SIGN_UP - The user hasn't completed the sign-up flow fully and must be confirmed via confirmSignUp.
• DONE - The sign in process has been completed.

For more information on handling the TOTP & MFA steps that may be returned, please see 'Multi-factor authentication'.

Sign-out

To sign a user out of your application you can use the signOut API.

import { signOut } from 'aws-amplify/auth';

async function handleSignOut() {
  try {
    await signOut();
  } catch (error) {
    console.log('error signing out: ', error);
  }
}

import { signOut } from 'aws-amplify/auth';

async function handleSignOut() {
  try {
    await signOut();
  } catch (error) {
    console.log('error signing out: ', error);
  }
}

You can also sign out users from all devices by performing a global sign-out. This will also invalidate all refresh tokens issued to a user. The user's current access and ID tokens will remain valid on other devices until the refresh token expires (access and ID tokens expire one hour after they are issued).

import { signOut } from 'aws-amplify/auth';

async function handleSignOut() {
  try {
    await signOut({ global: true });
  } catch (error) {
    console.log('error signing out: ', error);
  }
}

import { signOut } from 'aws-amplify/auth';

async function handleSignOut() {
  try {
    await signOut({ global: true });
  } catch (error) {
    console.log('error signing out: ', error);
  }
}

Once you implement the Amplify Library methods within your application, you can test the sign-up, sign-in, and sign-out functionality.

View the created user in the AWS Console

After you test the sign-up, sign-in, and sign-out functionality, you can take a look at the created user in the Amazon Cognito console. To do so, you can use amplify console auth to open the console directly from the CLI, or take a look at the existing User Pools in the console. Note the users status should be CONFIRMED if you successfully verified the user; however, it can be in UNCONFIRMED if the user is not yet verified. You can also check to make sure any other required attributes are updating correctly.

You now have enabled sign-up, sign-in, and sign-out for your authentication and verified its functionality with a test user.

Conclusion

Congratulations! You finished the Enable sign-up, sign-in, sign-out guide and verified the functionality works as expected.

Next steps

Now that you completed setting up Amplify Auth with username and password, you may also want to add some additional features. We recommend:

• Add social provider sign-in
• Multi-factor authentication