Configuration

Initial State

By default, unauthenticated users are redirected to the Sign In flow. You can explicitly redirect to Sign Up or Forgot Password:

Login Mechanisms

Without the zero configuration, the Authenticator by default creates new users in the Amazon Cognito UserPool based on a unique username.

You can provide an alternative to username such as email or phone_number.

Note: A username, email, or phone_number value is required for Cognito User Pools. The username field will only work with Gen 1 Auth. For more information about using username see the docs.

<Authenticator loginMechanisms={['username']}>
  {({ signOut, user }) => (
    <main>
      <h1>Hello {user.username}</h1>
      <button onClick={signOut}>Sign out</button>
    </main>
  )}
</Authenticator>

<Authenticator loginMechanisms={['email']}>
  {({ signOut, user }) => (
    <main>
      <h1>Hello {user.username}</h1>
      <button onClick={signOut}>Sign out</button>
    </main>
  )}
</Authenticator>

<Authenticator loginMechanisms={['phone_number']}>
  {({ signOut, user }) => (
    <main>
      <h1>Hello {user.username}</h1>
      <button onClick={signOut}>Sign out</button>
    </main>
  )}
</Authenticator>

Passwordless Authentication

Backend Configuration

For backend setup including Email OTP, SMS OTP, and WebAuthn (Passkey) configuration, see the Passwordless documentation.

Basic Usage

The Authenticator automatically detects passwordless authentication methods from your backend (amplify_outputs.json):

Available Authentication Methods

Configuration

Use the passwordless prop to:

• Override settings from amplify_outputs.json
• Configure passwordless for Gen 1 backends

interface PasswordlessSettings {
  hiddenAuthMethods?: ('PASSWORD' | 'EMAIL_OTP' | 'SMS_OTP' | 'WEB_AUTHN')[];
  preferredAuthMethod?: 'PASSWORD' | 'EMAIL_OTP' | 'SMS_OTP' | 'WEB_AUTHN';
  passkeyRegistrationPrompts?: {
    afterSignin?: 'ALWAYS' | 'NEVER';
    afterSignup?: 'ALWAYS' | 'NEVER';
  } | boolean;
}

Examples

<Authenticator
  passwordless={{
    hiddenAuthMethods: ['PASSWORD'],
    preferredAuthMethod: 'WEB_AUTHN',
    passkeyRegistrationPrompts: {
      afterSignin: 'ALWAYS',
      afterSignup: 'ALWAYS'
    }
  }}
>
  {({ signOut, user }) => (
    <main>
      <h1>Hello {user?.username}</h1>
      <button onClick={signOut}>Sign out</button>
    </main>
  )}
</Authenticator>

<Authenticator
  passwordless={{
    hiddenAuthMethods: ['PASSWORD', 'SMS_OTP', 'WEB_AUTHN'],
    preferredAuthMethod: 'EMAIL_OTP'
  }}
/>

<Authenticator
  passwordless={{
    passkeyRegistrationPrompts: {
      afterSignin: 'NEVER',
      afterSignup: 'ALWAYS'
    }
  }}
/>

<Authenticator
  passwordless={{
    passkeyRegistrationPrompts: false
  }}
/>

Sign Up Attributes

The Authenticator automatically renders most Cognito User Pools attributes, with the exception of address, gender, locale, picture, updated_at, and zoneinfo. Because these are often app-specific, they can be customized via Sign Up fields.

export default function App() {
  return (
    <Authenticator signUpAttributes={[]}>
      {({ signOut, user }) => (
        <main>
          <h1>Hello {user.username}</h1>
          <button onClick={signOut}>Sign out</button>
        </main>
      )}
    </Authenticator>
  );
}

export default function App() {
  return (
    <Authenticator signUpAttributes={[
      'address',
      'birthdate',
      'email',
      'family_name',
      'gender',
      'given_name',
      'locale',
      'middle_name',
      'name',
      'nickname',
      'phone_number',
      'picture',
      'preferred_username',
      'profile',
      'updated_at',
      'website',
      'zoneinfo',
    ]}>
      {({ signOut, user }) => (
        <main>
          <h1>Hello {user.username}</h1>
          <button onClick={signOut}>Sign out</button>
        </main>
      )}
    </Authenticator>
  );
}

Social Providers

For your configured social providers, you can also provide amazon, facebook, or google:

export default function App() {
  return (
    <Authenticator socialProviders={['amazon', 'apple', 'facebook', 'google']}>
      {({ signOut, user }) => (
        <main>
          <h1>Hello {user.username}</h1>
          <button onClick={signOut}>Sign out</button>
        </main>
      )}
    </Authenticator>
  );
}

Step by step video on setting up social providers.

Variation

The Authenticator has multiple variations to meet the needs of your application.

export default function App() {
  return (
    <Authenticator>
      {({ signOut, user }) => (
        <main>
          <h1>Hello {user.username}</h1>
          <button onClick={signOut}>Sign out</button>
        </main>
      )}
    </Authenticator>
  );
}

export default function App({ signOut }) {
  return (
    <Authenticator variation="modal">
      {({ signOut }) => <button onClick={signOut}>Sign out</button>}
    </Authenticator>
  );
}

Hide Sign Up

The Authenticator has an option to hide the sign up page including the Create Account tab.

Authenticator Example:

<Authenticator hideSignUp>
  <App />
</Authenticator>

withAuthenticator Example:

withAuthenticator(App, { hideSignUp: true });