Autenticação de Website React

O gerador de Autenticação de Website React 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 o Identity Pool associado, bem como uma UI hospedada para lidar com fluxos de login de usuário e sua integração com seu website React.

Uso

Adicionar Autenticação ao seu Website React

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

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

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

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 website React:

• Directorysrc

  • Directorycomponents

    • DirectoryCognitoAuth

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

Infraestrutura

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

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

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

Projeto Gerado

Este projeto é gerado usando o gerador ts#project e, portanto, configura os mesmos alvos de build.

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

Projeto Gerado

Este projeto é gerado usando o gerador terraform#project e, portanto, configura os mesmos alvos de build.

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

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

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.

Depois de observar as avaliações de risco para seus usuários, você pode mudar 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.

Autenticação multifator (MFA)

Por padrão, os usuários devem configurar MFA (um código SMS ou uma senha de uso único baseada em tempo) antes de poderem fazer login. Você pode tornar o MFA opcional, desativá-lo completamente ou restringir quais métodos de segundo fator estão disponíveis:

CDK

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

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

mfa aceita Mfa.OFF / Mfa.OPTIONAL / Mfa.REQUIRED. mfaSecondFactor.sms e mfaSecondFactor.otp habilitam ou desabilitam cada método de segundo fator independentemente; eles não têm efeito quando mfa é Mfa.OFF. Definir mfa: Mfa.REQUIRED com ambos os métodos desabilitados é rejeitado no momento da síntese, pois ninguém poderia então completar o login.

Terraform

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

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

mfa aceita "OFF" / "OPTIONAL" / "ON". mfa_second_factor_sms e mfa_second_factor_otp habilitam ou desabilitam cada método de segundo fator independentemente; eles não têm efeito quando mfa é "OFF".

SMS MFA está vinculado à verificação de número de telefone

O Cognito rejeita a verificação de número de telefone baseada em SMS a menos que SMS também seja um método MFA habilitado sempre que MFA não estiver desativado, tanto no CDK quanto no Terraform. Desabilitar mfaSecondFactor.sms / mfa_second_factor_sms enquanto mfa está ativado, portanto, também desabilita a verificação de número de telefone baseada em SMS para o user pool.

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 ao seu 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

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

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.

Remova 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 suas origens de aplicação reais.

CDK

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

Terraform

Edite as 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', {
      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}/*"
      }
    ]
  })
}