React 网站身份验证

React 网站身份验证生成器使用 Amazon Cognito 为您的 React 网站添加身份验证功能。

此生成器配置 CDK 或 Terraform 基础设施以创建 Cognito 用户池和关联的身份池，以及用于处理用户登录流程的托管 UI，并将其与您的 React 网站集成。

用法

为您的 React 网站添加身份验证

您可以通过两种方式为 React 网站添加身份验证：

运行此生成器@aws/nx-plugin:ts#website#auth

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

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#website#auth
5. 填写必需参数
6. 点击 Generate

构建你的命令5

project必需

cognitoDomain

allowSignup

false

iac

inheritcdkterraform

preferInstallDependencies

true

--dry-run您还可以执行试运行以查看哪些文件会被更改

选项

生成器选项5 个选项

project必需string

网站的根目录。

cognitoDomainstring

要使用的 Cognito 域前缀。如果省略，将从 npm scope 和网站项目名称派生一个值。

allowSignupboolean默认值: false

是否允许自助注册

iacenum默认值: inherit

首选的 IaC 提供商。默认情况下，这继承自您的初始选择。

inheritcdkterraform

preferInstallDependenciesboolean默认值: true

是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

您将在 React 网站中找到以下更改：

• 文件夹src

  • 文件夹components

    • 文件夹CognitoAuth

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

基础设施

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ Constructs for infrastructure specific to a project/generator

      • …
    • 文件夹core/ 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

此项目使用 ts#project 生成器生成，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ Terraform modules for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

此项目使用 terraform#project 生成器生成，因此配置了相同的构建目标。

您还将根据所选的 iac 找到以下生成的基础设施代码：

CDK

• 文件夹packages/common/constructs/src

  • 文件夹core

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

Terraform

• 文件夹packages/common/terraform/src

  • 文件夹core

    • 文件夹user-identity

      • main.tf Module wrapper for the identity configuration
      • 文件夹identity

        • identity.tf Core identity infrastructure including Cognito User Pool and Identity Pool
      • 文件夹add-callback-url

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

架构

此生成器在现有静态网站架构中添加了 Amazon Cognito 用户池（用于登录）和身份池（用于将已登录用户联合到作用域 IAM 凭证）：

Loading the diagram…

威胁防护

用户池在 Cognito Plus 功能计划上创建，并将标准身份验证的威胁防护设置为 AUDIT 模式。在审计模式下，Cognito 为每次登录分配风险级别，并将评估记录到 CloudWatch，而不会阻止用户。

一旦您观察了用户的风险评估，您可以切换到全功能强制执行，以自动响应风险活动（例如要求 MFA 或阻止登录）：

CDK

在 packages/common/constructs/src/core/user-identity.ts 中将 standardThreatProtectionMode 设置为 StandardThreatProtectionMode.FULL_FUNCTION。

Terraform

在 packages/common/terraform/src/core/user-identity/identity/identity.tf 的 user_pool_add_ons 块中将 advanced_security_mode 设置为 ENFORCED。

多因素身份验证（MFA）

默认情况下，用户必须在登录之前配置 MFA（短信验证码或基于时间的一次性密码）。您可以将 MFA 设为可选、完全关闭它，或限制可用的第二因素方法：

CDK

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

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

mfa 接受 Mfa.OFF / Mfa.OPTIONAL / Mfa.REQUIRED。mfaSecondFactor.sms 和 mfaSecondFactor.otp 独立启用或禁用每个第二因素方法；当 mfa 为 Mfa.OFF 时它们无效。将 mfa: Mfa.REQUIRED 设置为两种方法都禁用会在合成时被拒绝，因为这样就没有人能完成登录。

Terraform

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

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

mfa 接受 "OFF" / "OPTIONAL" / "ON"。mfa_second_factor_sms 和 mfa_second_factor_otp 独立启用或禁用每个第二因素方法；当 mfa 为 "OFF" 时它们无效。

短信 MFA 与电话号码验证绑定

在 CDK 和 Terraform 中，除非短信也是启用的 MFA 方法（当 MFA 未关闭时），否则 Cognito 会拒绝基于短信的电话号码验证。因此，当 mfa 开启时禁用 mfaSecondFactor.sms / mfa_second_factor_sms 也会禁用用户池的基于短信的电话号码验证。

Web 应用程序防火墙（WAF）

默认情况下，用户池与 AWS WAFv2 Web ACL 关联，使用 AWSManagedRulesCommonRuleSet 和 AWSManagedRulesKnownBadInputsRuleSet 托管规则组。如果您希望管理自己的 Web ACL 或不需要 Web ACL，可以禁用此功能：

CDK

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

Terraform

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

  enable_waf = false
}

EC2MetaDataSSRF_QUERYARGUMENTS 设置为 Count

此规则将查询参数中的环回地址标记为 SSRF 尝试，这会阻止本地登录，因为托管 UI 接收 localhost redirect_uri。因此，在配置本地回调 URL 时，它被设置为 Count —— 匹配项仍会被记录，其他每个规则都会阻止。删除本地回调 URL 以将其恢复为 Block。

基础设施用法

CDK

您需要将用户身份基础设施添加到您的堆栈中，在网站_之前_声明它：

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

import { Stack, StackProps } 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, props?: StackProps) {
    super(scope, id, props);

    new UserIdentity(this, 'Identity');

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

UserIdentity 构造会自动添加必要的运行时配置，以确保您的网站可以指向正确的 Cognito 用户池进行身份验证。

短信角色保留

用户池由 Cognito 代入的 IAM 角色支持以发送短信消息。角色的删除策略与用户池的删除策略一致 —— 默认情况下，CDK 的 UserPool 使用 RemovalPolicy.RETAIN，因此在 cdk destroy 时，用户池及其短信角色都会被保留，如果不再需要，需要手动清理。

Terraform

您需要添加用户身份模块，并确保您的网站依赖于它：

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]
}

用户身份模块会自动添加必要的运行时配置，以确保您的网站可以指向正确的 Cognito 用户池进行身份验证。

为生产环境删除 localhost 回调 URL

生成的用户池客户端允许您的 CloudFront 分发 URL（以及在其上配置的任何自定义域名）作为 OAuth 回调/注销 URL，加上每个连接网站自己的本地开发服务器和预览 URL（例如，工作区中生成的第一个网站的 http://localhost:4200 和 http://localhost:4300），用于针对已部署池的本地开发。使用 ts#website 生成的每个网站都分配有自己独特的端口，因此具有多个网站的工作区将在此处允许列表中有多个 http://localhost:<port> 对。

建议为生产阶段删除 http://localhost 回调/注销 URL，将允许列表限制为您的真实应用程序源。

CDK

在 packages/common/constructs/src/core/user-identity.ts 中编辑回调/注销 URL。

Terraform

在 packages/common/terraform/src/core/user-identity/identity/identity.tf 中编辑 callback_urls/logout_urls。

授予已认证用户访问权限

为了授予已认证用户执行某些操作的权限，例如授予调用 API 的权限，您可以向身份池已认证角色添加 IAM 策略语句：

CDK

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

import { Stack, StackProps } 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, props?: StackProps) {
    super(scope, id, props);

    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}/*"
      }
    ]
  })
}