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 Auth.signUp().

import { Auth } from 'aws-amplify';

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

export async function signUp({
  username,
  password,
  email,
  phone_number
}: SignUpParameters) {
  try {
    const { user } = await Auth.signUp({
      username,
      password,
      attributes: {
        email, // optional
        phone_number // optional - E.164 number convention
        // other custom attributes
      },
      autoSignIn: {
        // optional - enables auto sign in after user is confirmed
        enabled: true
      }
    });
    console.log(user);
  } catch (error) {
    console.log('error signing up:', error);
  }
}

import { Auth } from 'aws-amplify';

async function signUp() {
  try {
    const { user } = await Auth.signUp({
      username,
      password,
      attributes: {
        email, // optional
        phone_number // optional - E.164 number convention
        // other custom attributes
      },
      autoSignIn: {
        // optional - enables auto sign in after user is confirmed
        enabled: true
      }
    });
    console.log(user);
  } catch (error) {
    console.log('error signing up:', error);
  }
}

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 { Auth } from 'aws-amplify';

type ConfirmSignUpParameters = {
  username: string;
  code: string;
};

export async function confirmSignUp({
  username,
  code
}: ConfirmSignUpParameters) {
  try {
    await Auth.confirmSignUp(username, code);
  } catch (error) {
    console.log('error confirming sign up', error);
  }
}

import { Auth } from 'aws-amplify';

async function confirmSignUp() {
  try {
    await Auth.confirmSignUp(username, code);
  } catch (error) {
    console.log('error confirming sign up', error);
  }
}

Auto sign-in after sign-up

If you enabled autoSignIn, the sign up function will dispatch the autoSignIn hub event after successful confirmation. If authentication was successful, the event will contain CognitoUser in the data object. If auto sign-in failed, it will dispatch the autoSignIn_failure event.

import { Hub } from 'aws-amplify';

function listenToAutoSignInEvent() {
  Hub.listen('auth', ({ payload }) => {
    const { event } = payload;
    if (event === 'autoSignIn') {
      const user = payload.data;
      // assign user
    } else if (event === 'autoSignIn_failure') {
      // redirect to sign in page
    }
  });
}

Sign-in

You pass the username and password to the signIn method of the Auth class to enable username and password sign-in.

import { Auth } from 'aws-amplify';

type SignInParameters = {
  username: string;
  password: string;
};

export async function signIn({ username, password }: SignInParameters) {
  try {
    const user = await Auth.signIn(username, password);
  } catch (error) {
    console.log('error signing in', error);
  }
}

import { Auth } from 'aws-amplify';

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

Sign-out

To set up local sign-out, you use the signOut method of the Auth class.

import { Auth } from 'aws-amplify';

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

import { Auth } from 'aws-amplify';

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

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

import { Auth } from 'aws-amplify';

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

import { Auth } from 'aws-amplify';

async function signOut() {
  try {
    await Auth.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