Set up Amplify Auth

In this guide, you will learn how to set up authentication in your Amplify (Gen 2) app. This includes setting up and connecting your backend resources and enabling sign-up, sign-in, and sign-out with the Authenticator UI component. We will also provide more context on how resources are managed and created with Amplify to help you make decisions and understand any long-term impact of those decisions.

If you have not yet created an Amplify (Gen 2) app, visit the quickstart.

Building your auth backend

Configure auth resource

To configure your auth backend, edit the amplify/auth/resource.ts file. You can set up sign-in mechanisms that work with either an email/phone and password combination, or through integration with social provider sign-in options.

Learn more

Understanding Auth high-level concepts

Amplify helps you secure your application while providing an easy sign-in experience for your users. This experience is influenced by your security strategy. This security strategy includes the authentication method, security credentials, and enabling additional verification when needed.

Authentication is a process to validate who you are (abbreviated as AuthN). The system that does this validation is referred to as an Identity Provider or IdP. This can be your own self-hosted IdP or a cloud service. Oftentimes, this IdP is a social provider such as Facebook, Google, or Amazon.
Authorization is the process of validating what you can access (abbreviated as AuthZ). This is sometimes done by looking at tokens with custom logic, predefined rules, or signed requests with policies.

Common authentication methods and associated risks include:

Social provider federation which enables easier access for your users but shares data with third parties.

You can improve security credentials and verification for these authentication methods by:

Modifying the default password policy to ensure your users create stronger passwords.
Requiring additional contact information from users before they can reset passwords.
Enabling multi-factor authentication (MFA) which adds a layer of security at sign-in but may also add friction for your users.

At a minimum, you will need to pass a loginWith value to set up how your users sign in to your app. Signing in with email and password is configured by default if you do not provide any value.

1// amplify/auth/resource.ts
2import { defineAuth } from '@aws-amplify/backend';
3
4/**
5 * Define and configure your auth resource
6 * When used alongside data, it is automatically configured as an auth provider for data
7 * @see https://docs.amplify.aws/gen2/build-a-backend/auth
8 */
9export const auth = defineAuth({
10  loginWith: {
11    email: true,
12    // add social providers
13    externalProviders: {
14      /**
15       * First, create your secrets using `amplify sandbox secret`
16       * Then, import `secret` from `@aws-amplify/backend`
17       * @see https://docs.amplify.aws/gen2/deploy-and-host/sandbox-environments/features/#setting-secrets
18       */
19      // loginWithAmazon: {
20      //   clientId: secret('LOGINWITHAMAZON_CLIENT_ID'),
21      //   clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET'),
22      // }
23    }
24  },
25  /**
26   * Enable multifactor authentication
27   * @see https://docs.amplify.aws/gen2/build-a-backend/auth/manage-mfa
28   */
29  // multifactor: {
30  //   mode: 'OPTIONAL',
31  //   sms: {
32  //     smsMessage: (code) => `Your verification code is ${code}`,
33  //   },
34  // },
35  userAttributes: {
36    /** Request additional attributes for your app's users */
37    // profilePicture: {
38    //   mutable: true,
39    //   required: false,
40    // },
41  }
42});

Amplify uses Amazon Cognito as the main authentication provider. Amazon Cognito is a robust user directory service that handles user registration, authentication, account recovery, and other operations. If you have not worked with Amazon Cognito before, we recommend taking a closer look at Amazon Cognito configuration options before you continue, since some of them are irreversible after your resources are created.

Learn more

Review Amazon Cognito configuration options

Amazon Cognito can be customized based on your security strategy for authentication. However, some initial configuration options cannot be changed after the backend resources are configured:

User attributes that are used to identify your individual users (such as username and email) cannot be renamed or deleted.
Sign-in methods (including username, email, and phone) cannot be added or changed after the initial configuration. This includes both defining which attributes are used to sign in and which attributes are required. Required attributes must have a value for all users once set.
Verification methods (including username and email) are the same as required attributes and cannot be removed once configured.
The sub attribute is a unique identifier within each user pool that cannot be modified and can be used to index and search users.
If MFA is set to required for all users, you will need to include MFA setup when users sign up.

See the Amazon Cognito documentation for more details on these settings, including User pool attributes and Adding MFA to a user pool.

Deploy auth resource

After you have chosen and set up your authentication resource, run the following command to create your first authentication resource in your personal cloud sandbox.

1npx amplify sandbox

After a successful deployment, this command also generates a configuration file (amplifyconfiguration.json) to enable your frontend app to connect to your backend resources. The values you configure in your backend authentication resource are set in the generated configuration file to automatically configure the frontend Authenticator connected component.

Connect your application code to the auth backend

Creating and correctly implementing the sign-in flow can be challenging and time-consuming. Amplify's Authenticator UI component streamlines this by enabling you to rapidly build the entire authentication flow for your app. The component works seamlessly with configuration in amplify/auth/resource.ts to automatically connect with your backend resources.

Amplify has pre-built UI components for React, Vue, Angular, React Native, Swift, Android, and Flutter. In this guide, we are focusing on those for web applications.

First, install the @aws-amplify/ui-react library:

1npm add @aws-amplify/ui-react

Next, open pages/_app.ts and add the withAuthenticator component.

withAuthenticator

A higher-order component (HOC) is a function that takes a component and returns an enhanced component. The withAuthenticator HOC is an example of this pattern. It wraps the Authenticator component and enhances it by passing along additional authentication-related data like user info and the signOut function.

Usage

1// pages/_app.tsx
2import { withAuthenticator } from '@aws-amplify/ui-react';
3import { Amplify } from 'aws-amplify';
4import config from '@/amplifyconfiguration.json';
5import '@aws-amplify/ui-react/styles.css';
6import type { WithAuthenticatorProps } from '@aws-amplify/ui-react';
7
8Amplify.configure(config);
9
10function App({ Component, pageProps, signOut, user }: WithAuthenticatorProps) {
11  return (
12    <>
13      <h1>Hello {user?.username}</h1>
14      <button onClick={signOut}>Sign out</button>
15      <Component {...pageProps} />
16    </>
17  );
18}
19
20export default withAuthenticator(App);

Once you add the Authenticator component to your app, you can test the sign-up, sign-in, and sign-out functionality. You can also customize the Authenticator connected component to adjust colors and styling as needed.

Set up Amplify Auth

Building your auth backend

Configure auth resource

Deploy auth resource

Connect your application code to the auth backend

Manage users in the Amplify console

Conclusion

Next steps