Set up an example React single page application - Amazon Cognito
Create an applicationCreate a Lightsail developer environment
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Set up an example React single page application

In this tutorial, you'll create a React single page application where you can test user sign-up, confirmation, and sign-in. React is a JavaScript-based library for web and mobile apps, with a focus on the user interface (UI). This example application demonstrates some basic functions of Amazon Cognito user pools. If you're already experienced in web app development with React, download the example app from GitHub.

The following screenshot is of the initial authentication page in the application that you'll create.

A screenshot of the sign-up page for a React-based example web application.

The Create a user pool procedure sets you up with a user pool that works with the example application. You can skip this step if you have a user pool that meets the following requirements:

  • Users can sign in with their email address. Cognito user pool sign-in options: Email.

  • Usernames are case insensitive. User name requirements: Make user name case sensitive is not selected.

  • Multi-factor authentication (MFA) isn't required. MFA enforcement: Optional MFA.

  • Your user pool verifies attributes for user-profile confirmation with an email message. Attributes to verify: Send email message, verify email address.

  • Email is the only required attribute. Required attributes: email.

  • Users can sign themselves up in your user pool. Self-registration: Enable self-registration is selected.

  • Your initial app client is a public client that permits sign-in with username and password. App type: Public client, Authentication flows: ALLOW_USER_PASSWORD_AUTH.

Create a new user pool

  1. Go to the Amazon Cognito console. If prompted, enter your Amazon credentials.

  2. Choose the Create user pool button. You might be required to select User Pools from the left navigation pane to reveal this option.

  3. In the top-right corner of the page, choose Create a user pool to start the user pool creation wizard.

  4. In Configure sign-in experience, you can choose the identity providers (IdPs) that you will use with this user pool. For more information, see Adding user pool sign-in through a third party.

    1. Under Authentication providers, for Provider types, ensure that only Cognito user pool is selected.

    2. For Cognito user pool sign-in options, choose User name. Don't select any additional User name requirements.

    3. Keep all other options as the default and choose Next.

  5. In Configure security requirements, you can choose your password policy, multi-factor authentication (MFA) requirements, and user account recovery options. For more information, see Using Amazon Cognito user pools security features.

    1. For Password policy, confirm that Password policy mode is set to Cognito defaults.

    2. Under Multi-factor authentication, for MFA enforcement, choose Optional MFA.

    3. For MFA methods, choose Authenticator apps and SMS message.

    4. For User account recovery, confirm that Enable self-service account recovery is selected, and that the user account recovery message delivery method is set to Email only.

    5. Keep all other options as the default and choose Next.

  6. In Configure sign-up experience, you can determine how new users will verify their identities when signing up as a new user, and which attributes should be required or optional during the user sign-up flow. For more information, see Managing users in your user pool.

    1. Confirm that Enable self-registration is selected. This setting opens your user pool to sign-up from anyone on the internet. This is intended for the purposes of the example application, but apply this setting with caution in production environments.

    2. Under Cognito-assisted verification and confirmation, verify that the Allow Cognito to automatically send messages to verify and confirm check box is selected.

    3. Confirm that Attributes to verify is set to Send email message, verify email address.

    4. Under Verifying attribute changes, confirm that the default options are selected: Keep original attribute value when an update is pending is selected, and Active attribute values when an update is pending is set to Email address.

    5. Under Required attributes, confirm that Required attributes based on previous selections displays email.

      Important

      For this example application, your user pool must not set phone_number as a required attribute. If phone_number is shown as a required attribute, review and update your earlier choices:

      • Optional MFA, Email only for Delivery method for user account recovery messages

      • Send email message, verify email address for Attributes to verify

    6. Keep all other options as the default and choose Next.

  7. In Configure message delivery, you can configure integration with Amazon Simple Email Service and Amazon Simple Notification Service to send email and SMS messages to your users for sign-up, account confirmation, MFA, and account recovery. For more information, see Email settings for Amazon Cognito user pools and SMS message settings for Amazon Cognito user pools.

    1. For Email provider, choose Send email with Cognito, and use the default email sender provided by Amazon Cognito. This setting for low email volume is sufficient for application testing. You can return after you verify an email address with Amazon Simple Email Service (Amazon SES) and choose Send email with Amazon SES.

    2. For SMS, select Create a new IAM role and enter an IAM role name. This creates a role that grants permissions to Amazon Cognito to send SMS messages.

    3. Keep all other options as the default and choose Next.

  8. In Integrate your app, you can name your user pool, configure the hosted UI, and create an app client. For more information, see Add an app client with the hosted UI. The example applications don't use the hosted UI.

    1. Under User pool name, enter a User pool name.

    2. Don’t select Use the Cognito hosted UI.

    3. Under Initial app client, confirm that App type is set to Public client.

    4. Under Client secret, confirm that Don’t generate a client secret is selected.

    5. Enter an App client name.

    6. Expand Advanced app client settings. Add ALLOW_USER_PASSWORD_AUTH to the list of Authentication flows.

    7. Keep all other options as the default and choose Next.

  9. Review your choices in the Review and create screen and modify any selections as needed. When you're satisfied with your user pool configuration, choose Create user pool to proceed.

  10. From the User pools page, choose your new user pool.

  11. Under User pool overview, note your User pool ID. You'll provide this string when you create your example application.

  12. Choose the App integration tab and locate the App clients and analytics section. Select your new app client. Note your Client ID.

Create an application

To build this application, you must set up a developer environment. The developer environment requirements are:

  1. Node.js is installed and updated.

  2. Node package manager (npm) is installed and updated to at least version 10.2.3.

  3. The environment is accessible on TCP port 5173 in a web browser.

To create an example React web application

  1. Sign in to your developer environment and navigate to the parent directory for your application.

    cd ~/path/to/project/folder/

  2. Create a new React service.

    npm create vite@latest frontend-client -- --template react-ts

  3. Clone the cognito-developer-guide-react-example project folder from the Amazon code examples repository on GitHub.

    cd ~/some/other/path
    git clone https://github.com/awsdocs/aws-doc-sdk-examples.git
    cp -r ./aws-doc-sdk-examples/javascriptv3/example_code/cognito-identity-provider/scenarios/cognito-developer-guide-react-example/frontend-client ~/path/to/project/folder/frontend-client

  4. Navigate to the src directory in your project.

    cd ~/path/to/project/folder/frontend-client/src

  5. Edit config.ts and replace the following values:

    1. Replace YOUR_AWS_REGION with an Amazon Web Services Region code. For example: us-east-1.

    2. Replace YOUR_COGNITO_USER_POOL_ID with the ID of the user pool that you have designated for testing. For example: us-east-1_EXAMPLE. The user pool must be in the Amazon Web Services Region that you entered in the previous step.

    3. Replace YOUR_COGNITO_APP_CLIENT_ID with the ID of the app client that you have designated for testing. For example: 1example23456789. The app client must be in the user pool from the previous step.

  6. If you want to access your example application from an IP other than localhost, edit package.json and change the line "dev": "vite", to "dev": "vite --host 0.0.0.0",.

  7. Install your application.

    npm install

  8. Launch the application.

    npm run dev

  9. Access the application in a web browser at http://localhost:5173 or http://[IP address]:5173.

  10. Sign up a new user with a valid email address.

  11. Retrieve the confirmation code from your email message. Enter the confirmation code into the application.

  12. Sign in with your username and password.

Creating a React developer environment with Amazon Lightsail

A quick way to get started with this application is to create a virtual cloud server with Amazon Lightsail.

With Lightsail, you can quickly create a small server instance that comes preconfigured with the prerequisites for this example application. You can SSH to your instance with a browser-based client, and connect to the web server at a public or private IP address.

To create a Lightsail instance for this example application

  1. Go to the Lightsail console. If prompted, enter your Amazon credentials.

  2. Choose Create instance.

  3. For Select a platform, choose Linux/Unix.

  4. For Select a blueprint, choose Node.js.

  5. Under Identify your instance, give your development environment a friendly name.

  6. Choose Create instance.

  7. After Lightsail has created your instance, select it and from the Connect tab, choose Connect using SSH.

  8. An SSH session opens in a browser window. Run node -v and npm -v to confirm that your instance was provisioned with Node.js and the minimum npm version of 10.2.3.

  9. Proceed to configure your React application.