React Website Authentication

The React Website Authentication generator adds authentication to your React website using Amazon Cognito.

This generator configures the CDK or Terraform infrastructure to create a Cognito User Pool and associated Identity Pool, as well as a hosted UI for handling user login flows, and its integration with your React website.

Usage

Add Authentication to your React Website

You can add authentication to your React website in two ways:

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth

yarn

yarn nx g @aws/nx-plugin:ts#website#auth

npm

npx nx g @aws/nx-plugin:ts#website#auth

bun

bunx nx g @aws/nx-plugin:ts#website#auth

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --dry-run

npm

npx nx g @aws/nx-plugin:ts#website#auth --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website#auth --dry-run

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#website#auth
5. Fill in the required parameters
6. Click Generate

Options

Parameter	Type	Default	Description
project Required	string	-	The root directory of the website.
cognitoDomain	string	-	The cognito domain prefix to use. If omitted, a value is derived from the npm scope and website project name.
allowSignup	boolean		Whether to allow self-signup
iac	inherit | cdk | terraform	inherit	The preferred IaC provider. By default this is inherited from your initial selection.
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

You will find the following changes in your React website:

• Directorysrc

  • Directorycomponents

    • DirectoryCognitoAuth

      • index.tsx Main authentication component
  • main.tsx Updated to instrument the CognitoAuth component

Infrastructure

Since this generator vends infrastructure as code based on your chosen iac, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

This project is generated using the ts#project generator and therefore configures the same build targets.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

This project is generated using the terraform#project generator and therefore configures the same build targets.

You will also find the following infrastructure code generated based on your selected iac:

CDK

• Directorypackages/common/constructs/src

  • Directorycore

    • user-identity.ts Construct which defines the user pool and identity pool

Terraform

• Directorypackages/common/terraform/src

  • Directorycore

    • Directoryuser-identity

      • main.tf Module wrapper for the identity configuration
      • Directoryidentity

        • identity.tf Core identity infrastructure including Cognito User Pool and Identity Pool
      • Directoryadd-callback-url

        • add-callback-url.tf Module for adding callback URLs to existing user pool clients

Architecture

This generator adds an Amazon Cognito user pool (for sign-in) and an identity pool (for federating signed-in users to scoped IAM credentials) to the existing static-website architecture:

Threat protection

The User Pool is created on the Cognito Plus feature plan with threat protection set to AUDIT mode for standard authentication. In audit mode, Cognito assigns a risk level to each sign-in and logs the assessment to CloudWatch without blocking users.

Once you have observed the risk assessments for your users, you can switch to full-function enforcement to automatically respond to risky activity (for example requiring MFA or blocking sign-in):

CDK

Set standardThreatProtectionMode to StandardThreatProtectionMode.FULL_FUNCTION in packages/common/constructs/src/core/user-identity.ts.

Terraform

Set advanced_security_mode to ENFORCED in the user_pool_add_ons block in packages/common/terraform/src/core/user-identity/identity/identity.tf.

Multi-factor authentication (MFA)

By default users must configure MFA (an SMS code or a time-based one time password) before they can sign in. You can make MFA optional, turn it off entirely, or restrict which second-factor methods are available:

CDK

import { Mfa } from 'aws-cdk-lib/aws-cognito';

new UserIdentity(this, 'Identity', {
  mfa: Mfa.OPTIONAL,
  mfaSecondFactor: { sms: false, otp: true },
});

mfa accepts Mfa.OFF / Mfa.OPTIONAL / Mfa.REQUIRED. mfaSecondFactor.sms and mfaSecondFactor.otp enable or disable each second-factor method independently; they have no effect when mfa is Mfa.OFF. Setting mfa: Mfa.REQUIRED with both methods disabled is rejected at synth time, since nobody could then complete sign-in.

Terraform

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"

  mfa = "OPTIONAL"
  mfa_second_factor_sms = false
  mfa_second_factor_otp = true
}

mfa accepts "OFF" / "OPTIONAL" / "ON". mfa_second_factor_sms and mfa_second_factor_otp enable or disable each second-factor method independently; they have no effect when mfa is "OFF".

SMS MFA is tied to phone number verification

Cognito rejects SMS-based phone number verification unless SMS is also an enabled MFA method whenever MFA is not off, in both CDK and Terraform. Disabling mfaSecondFactor.sms / mfa_second_factor_sms while mfa is on therefore also disables SMS-based phone number verification for the user pool.

Web Application Firewall (WAF)

By default the User Pool is associated with an AWS WAFv2 Web ACL using the AWSManagedRulesCommonRuleSet and AWSManagedRulesKnownBadInputsRuleSet managed rule groups. You can disable this if you wish to manage your own Web ACL or do not require one:

CDK

new UserIdentity(this, 'Identity', { enableWaf: false });

Terraform

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"

  enable_waf = false
}

EC2MetaDataSSRF_QUERYARGUMENTS is set to Count

This rule flags loopback addresses in query arguments as SSRF attempts, which would block local sign-in since the Hosted UI receives a localhost redirect_uri. It is therefore set to Count while local callback URLs are configured — matches are still logged, and every other rule blocks. Remove the local callback URLs to restore it to Block.

Infrastructure Usage

CDK

You will need to add the user identity infrastructure to your stack, declaring it before the website:

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, UserIdentity } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new UserIdentity(this, 'Identity');

    new MyWebsite(this, 'MyWebsite');
  }
}

The UserIdentity construct automatically adds the necessary Runtime Configuration to ensure that your website can point to the correct Cognito User Pool for authentication.

SMS role retention

The User Pool is backed by an IAM role that Cognito assumes to send SMS messages. The role’s removal policy mirrors the User Pool’s — by default CDK’s UserPool uses RemovalPolicy.RETAIN, so on cdk destroy both the User Pool and its SMS role are retained and will need to be cleaned up manually if no longer needed.

Terraform

You will need to add the user identity module, and ensure your website depends on it:

packages/infra/src/main.tf

# Deploy user identity first to add to runtime config
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Deploy website after identity to include runtime config
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Ensure identity is deployed first to add to runtime config
  depends_on = [module.user_identity]
}

The user identity module automatically adds the necessary Runtime Configuration to ensure that your website can point to the correct Cognito User Pool for authentication.

Remove localhost callback URLs for production

The generated User Pool client allows your CloudFront distribution URL (and any custom domain names configured on it) as OAuth callback/logout URLs, plus http://localhost:4200 and http://localhost:4300 for local development against the deployed pool.

It is recommended to remove the http://localhost callback/logout URLs for production stages, keeping the allowlist limited to your real application origins.

CDK

Edit the callback/logout URLs in packages/common/constructs/src/core/user-identity.ts.

Terraform

Edit the callback_urls/logout_urls in packages/common/terraform/src/core/user-identity/identity/identity.tf.

Granting Access to Authenticated Users

In order to grant authenticated users access to perform certain actions, such as granting permissions to invoke an API, you can add IAM policy statements to the identity pool authenticated role:

CDK

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, UserIdentity, MyApi } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const identity = new UserIdentity(this, 'Identity');
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });

    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new MyWebsite(this, 'MyWebsite');
  }
}

Terraform

packages/infra/src/main.tf

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Add permissions for authenticated users to invoke Fast API
resource "aws_iam_role_policy" "authenticated_fast_api_invoke" {
  name = "authenticated-user-invoke-my-api"
  role = module.user_identity.authenticated_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "execute-api:Invoke"
        ]
        Resource = "${module.my_api.api_execution_arn}/*"
      }
    ]
  })
}