React Website Authentication

O gerador React Website Authentication adiciona autenticação ao seu website React usando Amazon Cognito.

Este gerador configura a infraestrutura CDK ou Terraform para criar um Cognito User Pool e um Identity Pool associado, bem como uma interface hospedada para gerenciar fluxos de login de usuários e sua integração com seu website React.

Uso

Adicionar Autenticação ao seu React Website

Você pode adicionar autenticação ao seu React website de duas maneiras:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#website#auth
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	O diretório raiz do website.
cognitoDomain	string	-	O prefixo do domínio Cognito a ser usado. Se omitido, um valor é derivado do escopo npm e do nome do projeto do website.
allowSignup	boolean		Se deve permitir auto-registro
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

Você encontrará as seguintes alterações em seu React website:

• Directorysrc

  • Directorycomponents

    • DirectoryCognitoAuth

      • index.tsx Componente de autenticação principal
  • main.tsx Atualizado para instrumentar o componente CognitoAuth

Infraestrutura

Como este gerador fornece infraestrutura como código com base no iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

O projeto comum de infraestrutura como código está estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Constructs genéricos reutilizados pelos constructs em app

      • …
    • index.ts Ponto de entrada exportando os constructs de app
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Módulos genéricos reutilizados pelos módulos em app

      • …
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

Você também encontrará o seguinte código de infraestrutura gerado com base no iac selecionado:

CDK

• Directorypackages/common/constructs/src

  • Directorycore

    • user-identity.ts Construct que define o user pool e o identity pool

Terraform

• Directorypackages/common/terraform/src

  • Directorycore

    • Directoryuser-identity

      • main.tf Wrapper de módulo para a configuração de identidade
      • Directoryidentity

        • identity.tf Infraestrutura de identidade principal incluindo Cognito User Pool e Identity Pool
      • Directoryadd-callback-url

        • add-callback-url.tf Módulo para adicionar URLs de callback a clientes de user pool existentes

Arquitetura

Este gerador adiciona um Amazon Cognito user pool (para login) e um identity pool (para federar usuários autenticados a credenciais IAM com escopo) à arquitetura de website estático existente:

Proteção contra ameaças

O User Pool é criado no plano de recursos Plus do Cognito com proteção contra ameaças definida para o modo AUDIT para autenticação padrão. No modo de auditoria, o Cognito atribui um nível de risco a cada login e registra a avaliação no CloudWatch sem bloquear usuários.

Uma vez que você tenha observado as avaliações de risco para seus usuários, você pode alternar para a aplicação de função completa para responder automaticamente a atividades arriscadas (por exemplo, exigindo MFA ou bloqueando o login):

CDK

Defina standardThreatProtectionMode como StandardThreatProtectionMode.FULL_FUNCTION em packages/common/constructs/src/core/user-identity.ts.

Terraform

Defina advanced_security_mode como ENFORCED no bloco user_pool_add_ons em packages/common/terraform/src/core/user-identity/identity/identity.tf.

Web Application Firewall (WAF)

Por padrão, o User Pool é associado a um AWS WAFv2 Web ACL usando os grupos de regras gerenciadas AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet. Você pode desabilitar isso se desejar gerenciar seu próprio Web ACL ou não precisar de um:

CDK

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

Terraform

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

  enable_waf = false
}

EC2MetaDataSSRF_QUERYARGUMENTS está definido como Count

Esta regra sinaliza endereços de loopback em argumentos de consulta como tentativas de SSRF, o que bloquearia o login local, pois a Hosted UI recebe um redirect_uri localhost. Portanto, está definida como Count enquanto as URLs de callback locais estão configuradas — as correspondências ainda são registradas e todas as outras regras bloqueiam. Remova as URLs de callback locais para restaurá-la para Block.

Uso da Infraestrutura

CDK

Você precisará adicionar a infraestrutura de identidade de usuário à sua stack, declarando-a antes do 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');
  }
}

O construct UserIdentity adiciona automaticamente a Configuração de Runtime necessária para garantir que seu website possa apontar para o Cognito User Pool correto para autenticação.

Retenção de função SMS

O User Pool é apoiado por uma função IAM que o Cognito assume para enviar mensagens SMS. A política de remoção da função espelha a do User Pool — por padrão, o UserPool do CDK usa RemovalPolicy.RETAIN, então no cdk destroy tanto o User Pool quanto sua função SMS são retidos e precisarão ser limpos manualmente se não forem mais necessários.

Terraform

Você precisará adicionar o módulo de identidade de usuário e garantir que seu website dependa dele:

packages/infra/src/main.tf

# Implanta a identidade primeiro para adicionar à configuração de runtime
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Implanta o website após a identidade para incluir a configuração de runtime
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Garante que a identidade seja implantada primeiro para adicionar à configuração de runtime
  depends_on = [module.user_identity]
}

O módulo de identidade de usuário adiciona automaticamente a Configuração de Runtime necessária para garantir que seu website possa apontar para o Cognito User Pool correto para autenticação.

Remover URLs de callback localhost para produção

O cliente User Pool gerado permite a URL de distribuição do CloudFront (e quaisquer nomes de domínio personalizados configurados nele) como URLs de callback/logout OAuth, além de http://localhost:4200 e http://localhost:4300 para desenvolvimento local contra o pool implantado.

É recomendado remover as URLs de callback/logout http://localhost para estágios de produção, mantendo a lista de permissões limitada às origens reais da sua aplicação.

CDK

Edite as URLs de callback/logout em packages/common/constructs/src/core/user-identity.ts.

Terraform

Edite os callback_urls/logout_urls em packages/common/terraform/src/core/user-identity/identity/identity.tf.

Concedendo Acesso a Usuários Autenticados

Para conceder aos usuários autenticados acesso para realizar certas ações, como conceder permissões para invocar uma API, você pode adicionar declarações de política IAM à função autenticada do identity pool:

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');

    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
}

# Adiciona permissões para usuários autenticados invocarem a 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}/*"
      }
    ]
  })
}