Name:
interface
Value:
Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Page updated Apr 29, 2024

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.

This guide is for those who want to set up Amplify Auth with the Amplify Libraries. If you want to create a sign-in and registration experience for your app with a few lines of code, we recommend using the Authenticator component, which provides a customizable UI and complete authentication flows.

Before you begin, you should have finished the Set up and connect 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.

Learn more
Review the sign-up, sign-in, and sign-out workflow

Below is a high-level overview of the workflows for sign-up, sign-in, and sign-out with Amplify authentication:

Sign-up: The username and password setup will ask your user for a username (or email) and a password. This should also include any attributes you include in your sign-up form, such as address, birthdate, and phone. When your end user submits this information, it is then passed through the signUp() API to your Amazon Cognito User Pool, where a user is created. By default, the user will receive a confirmation message by email or SMS, depending on what you configured, but you also have the option to auto-confirm your users after they sign up. Users must then enter the confirmation code to complete the sign-up process. Once the user is verified, their user profile is officially confirmed and is active in the Cognito User Pool. The profile contains the username, password, and any other attributes collected during sign-up. This user profile can then be used to sign in and access your application.

Sign-in: The user enters the username and password they created on sign-up and submits the form in your application to sign in. The application will then call the signIn() API to sign in the user by passing the username and password to verify and establish a session with Amazon Cognito, which will then generate the needed tokens to grant access. Amazon Cognito issues temporary short-lived tokens on sign-in (default of 1 hour), but you can update these settings to keep your users signed in for longer (up to 24 hours).

Sign-out: Amplify uses the signOut() API to sign out the user by ending the current session and revoking the tokens with Amazon Cognito. This clears the user session in the browser and the application will then navigate the user to the sign-in screen.

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'

User attributes are not required by default. You can make user attributes required but it cannot be changed back to not required once configured.

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 setup.

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: