Envie atributos personalizados para o Amazon Cognito e injete-os em tokens - Recomendações da AWS
ResumoPré-requisitos e limitaçõesArquiteturaFerramentasPráticas recomendadasÉpicosSolução de problemasRecursos relacionadosMais informações

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Envie atributos personalizados para o Amazon Cognito e injete-os em tokens

Carlos Alessandro Ribeiro e Mauricio Mendoza, Amazon Web Services

Resumo

O envio de atributos personalizados para um processo de autenticação do Amazon Cognito pode fornecer contexto adicional a um aplicativo, permitir controles de acesso mais granulares e facilitar o gerenciamento de perfis de usuário e requisitos de autenticação. Esses recursos são úteis em uma ampla variedade de aplicativos e cenários e podem ajudá-lo a melhorar a segurança e a funcionalidade gerais de um aplicativo.

Esse padrão mostra como enviar atributos personalizados para um processo de autenticação do Amazon Cognito quando um aplicativo precisa fornecer contexto adicional ao token de acesso ou token de identidade (ID). Você usa o Node.js como aplicativo de back-end. O aplicativo autentica um usuário de um grupo de usuários do Amazon Cognito e transmite atributos personalizados que são necessários para a geração de tokens. Você pode usar AWS Lambda gatilhos para o Amazon Cognito para personalizar seu processo de autenticação sem grande personalização de código ou esforço significativo.

Importante

O código e as amostras desse padrão não são recomendados para cargas de trabalho de produção porque são destinados apenas para fins de demonstração. Para cargas de trabalho de produção, é necessária uma configuração adicional no lado do cliente. Use esse padrão como referência apenas para fins piloto ou para proof-of-concept fins.

Pré-requisitos e limitações

Pré-requisitos

Limitações

  • Esse padrão não é aplicável à integração de aplicativos por meio do fluxo de autenticação de credenciais do cliente.

  • O gatilho de geração pré-token pode adicionar ou alterar somente alguns atributos do token de acesso e do token de identidade. Para obter mais informações, consulte Acionador Lambda de pré-geração de tokens na documentação do Amazon Cognito.

Arquitetura

Arquitetura de destino

O diagrama a seguir mostra a arquitetura de destino desse padrão. Também mostra como o aplicativo Node.js pode funcionar com um back-end para atualizar bancos de dados. No entanto, as atualizações do banco de dados de back-end estão fora do escopo desse padrão.

Um aplicativo Node.js emitindo um token de acesso com atributos personalizados para um grupo de usuários do Amazon Cognito.

O diagrama mostra o seguinte fluxo de trabalho:

  1. O aplicativo Node.js emite um token de acesso com atributos personalizados para o grupo de usuários do Amazon Cognito.

  2. O grupo de usuários do Amazon Cognito inicia a função Lambda de pré-geração de tokens, que personaliza os tokens de acesso e ID.

  3. O aplicativo Node.js faz uma chamada de API por meio do Amazon API Gateway.

nota

Os outros componentes arquitetônicos mostrados nessa arquitetura são apenas, por exemplo, e estão fora do escopo desse padrão.

Automação e escala

Você pode automatizar o provisionamento de grupos de usuários, AWS Lambda funções, instâncias de banco de dados e outros recursos do Amazon Cognito usando AWS CloudFormationo HashiCorp Terraform ou qualquer AWS Cloud Development Kit (AWS CDK)ferramenta de infraestrutura como código (IaC) compatível. Se você quiser escalar suas implantações, use pipelines de integração contínua e entrega contínua (CI/CD), que ajudam a evitar erros associados às implantações manuais.

Ferramentas

Serviços da AWS

  • O Amazon API Gateway ajuda você a criar, publicar, manter, monitorar e proteger REST, HTTP e WebSocket APIs em qualquer escala.

  • O Amazon Cognito fornece autenticação, autorização e gerenciamento de usuários para suas aplicações Web e móveis.

  • O Amazon Elastic Container Service (Amazon ECS) é um serviço de gerenciamento de contêineres escalável e rápido que facilita a execução, a interrupção e o gerenciamento de contêineres em um cluster.

  • O AWS Lambda é um serviço de computação que ajuda a executar código sem exigir provisionamento ou gerenciamento de servidores. Ele executa o código somente quando necessário e dimensiona automaticamente, assim, você paga apenas pelo tempo de computação usado.

  • AWS SDK para JavaScriptfornece uma JavaScript API para Serviços da AWS. Você pode usá-lo para criar bibliotecas ou aplicativos para o Node.js ou o navegador.

Outras ferramentas

  • O Node.js é um ambiente de tempo de JavaScript execução orientado por eventos, projetado para criar aplicativos de rede escaláveis.

  • O npm é um registro de software executado em um ambiente Node.js e usado para compartilhar ou emprestar pacotes e gerenciar a implantação de pacotes privados.

Práticas recomendadas

Recomendamos que você implemente as seguintes práticas recomendadas:

  • Segredos e dados confidenciais — Não armazene segredos ou dados confidenciais no aplicativo. Use um sistema externo do qual o aplicativo possa extrair os dados, como AWS AppConfigAWS Secrets Manager, ou AWS Systems Manager Parameter Store.

  • Implantação padronizada — Use CI/CD pipelines para implantar seus aplicativos. Você pode usar serviços como AWS CodeBuildAWS CodePipelinee.

  • Expiração do token — defina uma data de expiração curta para o token de acesso.

  • Use uma conexão segura — Toda comunicação entre o aplicativo cliente e o back-end deve ser criptografada usando SSL/TLS. Use AWS Certificate Manager (ACM) para gerar e gerenciar SSL/TLS certificados e use a Amazon CloudFront ou o Elastic Load Balancing para lidar com a SSL/TLS rescisão.

  • Validar a entrada do usuário — Certifique-se de que todas as entradas do usuário sejam validadas para evitar ataques de injeção e outras vulnerabilidades de segurança. Use bibliotecas e serviços de validação de entrada, como o Amazon API Gateway, AWS WAFpara evitar vetores de ataque comuns.

  • Use funções do IAM — Use funções AWS Identity and Access Management (IAM) para controlar o acesso aos AWS recursos e garantir que somente usuários autorizados tenham acesso. Siga o princípio do privilégio mínimo e certifique-se de que cada usuário tenha somente as permissões necessárias para desempenhar sua função.

  • Use uma política de senha — configure uma política de senha que atenda aos seus requisitos de segurança, como tamanho mínimo, complexidade e expiração. Use o Secrets Manager ou o AWS Systems Manager Parameter Store para armazenar e gerenciar senhas com segurança.

  • Habilite a autenticação multifator (MFA) — habilite a MFA para todos os usuários para fornecer uma camada adicional de segurança e reduzir o risco de acesso não autorizado. Use o AWS IAM Identity CenterAmazon Cognito para habilitar o MFA e outros métodos de autenticação.

  • Armazene informações confidenciais com segurança — armazene informações confidenciais, como senhas e tokens de acesso, com segurança usando AWS Key Management Service (AWS KMS) ou outros serviços de criptografia.

  • Use métodos de autenticação fortes — Para aumentar a segurança do processo de autenticação, use métodos de autenticação fortes, como autenticação biométrica ou autenticação multifatorial.

  • Monitore atividades suspeitas — Use AWS CloudTrailoutras ferramentas de monitoramento para monitorar atividades suspeitas e possíveis ameaças à segurança. Configure alertas automatizados para atividades incomuns e use a Amazon GuardDuty ou AWS Security Hubpara detectar possíveis ameaças.

  • Revise e atualize regularmente as políticas de segurança — revise e atualize regularmente suas políticas e procedimentos de segurança para garantir que eles atendam às mudanças nos requisitos de segurança e nas melhores práticas. Use AWS Config para rastrear e auditar alterações em suas políticas e procedimentos de segurança.

  • Inscrição automática — Não habilite a inscrição automática em um grupo de usuários do Amazon Cognito. Para obter mais informações, consulte Reduzir os riscos de fraude na inscrição de usuários e envio de SMS com grupos de usuários do Amazon CognitoAWS (postagem no blog).

Para obter melhores práticas adicionais, consulte Melhores práticas de segurança para grupos de usuários do Amazon Cognito na documentação do Amazon Cognito.

Épicos

TarefaDescriçãoHabilidades necessárias

Criar um grupo de usuários.

  1. Em um terminal CLI, digite o seguinte comando para criar um grupo de usuários do Amazon Cognito:

    aws cognito-idp create-user-pool \
   --pool-name <MyUserPool>

  2. Digite o comando a seguir para criar um ID de cliente e um segredo que serão usados com o SDK para JavaScript:

    aws cognito-idp create-user-pool-client \
   --user-pool-id <UserPoolID>  \
   --client-name <MyNewClient> \
   --no-generate-secret \
   --explicit-auth-flows "USER_PASSWORD_AUTH" "ADMIN_NO_SRP_AUTH"

Para obter mais informações e instruções sobre como configurar um grupo de usuários no AWS Management Console, consulte Introdução aos grupos de usuários e Adicionar mais recursos e opções de segurança ao seu grupo de usuários.

dica

Para reduzir custos, use o plano Essentials ou o plano Lite para testar esse padrão. Para mais informações, consulte Preço do Amazon Cognito.

Desenvolvedor de aplicativos, AWS DevOps

Adicione um usuário ao grupo de usuários.

Insira o seguinte comando para criar um usuário no grupo de usuários do Amazon Cognito:

aws cognito-idp sign-up \
   --client-id <ClientID> \
   --username <jane@example.com> \
   --password <PASSWORD> \
   --user-attributes Name="email",Value="<jane@example.com>" Name="name",Value="<Jane>"
Desenvolvedor de aplicativos, AWS DevOps

Adicione o cliente do aplicativo ao grupo de usuários.

  1. Acesse o console do Amazon Cognito.

  2. Escolha User Pools (Grupos de usuários).

  3. Escolha o grupo de usuários que você criou anteriormente.

  4. Em Definir seu aplicativo, escolha o tipo de aplicativo que melhor se adapta ao cenário de aplicativo para o qual você deseja criar serviços de autenticação e autorização.

  5. Em Nomeie seu aplicativo, insira um nome descritivo ou continue com o nome padrão.

  6. Em Adicionar uma URL de retorno, insira um caminho de redirecionamento para seu aplicativo para depois que os usuários concluam a autenticação.

  7. Escolha Criar seu aplicativo. Você pode configurar as opções avançadas depois de criar seu cliente de aplicativo.

Administrador de sistemas da AWS, administrador da AWS, AWS DevOps, desenvolvedor de aplicativos

Crie um gatilho Lambda para geração pré-token.

  1. Abra a página de funções do console do Lambda.

  2. Escolha a opção Criar função.

  3. Selecione Criar do zero.

  4. No painel Informações básicas, em Nome da função, insiramyPreTokenGenerationLambdaFunction.

  5. Em Runtime, escolha Node.js 22.

  6. Deixe a arquitetura definida como x86_64.

  7. Escolha a opção Criar função.

  8. Na guia Código, em Fonte do código, insira o exemplo da função Lambda na seção Recursos adicionais desse padrão. Essa função Lambda injeta os atributos personalizados no token de ID e no token de acesso.

AWS DevOps, desenvolvedor de aplicativos

Personalize o fluxo de trabalho do grupo de usuários.

  1. Acesse o console do Amazon Cognito.

  2. Escolha User Pools (Grupos de usuários).

  3. Escolha o grupo de usuários que você criou anteriormente.

  4. No painel de navegação esquerdo, em Autenticação, escolha Extensões.

  5. Escolha Adicionar gatilho Lambda.

  6. Adicione ou edite um Acionador de geração de pré-token.

  7. Para Tipo de gatilho, escolha Autenticação.

  8. Em Autenticação, escolha Acionador de pré-geração de token.

  9. Em Atribuir função Lambda, escolha. myPreTokenGenerationLambdaFunction

  10. Escolha Adicionar gatilho Lambda.

  11. Escolha uma versão do evento Trigger de recursos básicos + personalização de token de acesso para identidades de usuários ou Recursos básicos + personalização de token de acesso para identidades de usuários e máquinas. Essa configuração atualiza os parâmetros de solicitação que o Amazon Cognito envia à função para incluir campos para personalização do token de acesso.

Para obter mais informações, consulte Personalização de fluxos de trabalho de grupos de usuários com acionadores Lambda na documentação do Amazon Cognito.

AWS DevOps, desenvolvedor de aplicativos
TarefaDescriçãoHabilidades necessárias

Crie o aplicativo Node.js.

  1. Em um terminal, insira os seguintes comandos:

    mkdir my-app
cd my-app
npm init -y
npm install --save-dev typescript
npm i --save-dev @types/node
npm i amazon-cognito-identity-js
npx tsc --init
mkdir src
touch src/index.ts

  2. Modifique o package.json arquivo para incluir os scripts de TypeScript compilação:

    "scripts": {
  "start": "node src/index.js",
  "build": "tsc"
},
Desenvolvedor de aplicativos

Implemente a lógica de autenticação.

  1. Abra o arquivo index.ts.

  2. Cole o exemplo de texto datilografado fornecido na seção Recursos adicionais desse padrão.

  3. Salve e feche o arquivo index.ts.

nota

Você pode criar seu próprio TypeScript arquivo ou modificar a amostra fornecida conforme necessário para seu caso de uso.

Desenvolvedor de aplicativos

Configure as variáveis de ambiente e o arquivo de configuração.

Em um terminal, insira os seguintes comandos para criar as variáveis de ambiente:

export USERNAME="<COGNITO_USER_NAME>"
export PASSWORD="<COGNITO_USER_PASSWORD>"
export USER_POOL_ID="<COGNITO_USER_ID>"
export CLIENT_ID="<COGNITO_CLIENT_ID>"
Importante

Não codifique segredos nem exponha suas credenciais.

Desenvolvedor de aplicativos

Execute o aplicativo.

Insira os seguintes comandos para executar o aplicativo e confirmar se ele está funcionando:

npm run build
npm start
Desenvolvedor de aplicativos

Confirme se os atributos personalizados foram injetados nos tokens.

Use os recursos de depuração do seu IDE para visualizar os tokens de acesso e ID. Confirme se os atributos personalizados foram adicionados. Para exemplos de tokens, consulte a seção Informações adicionais desse padrão.

Desenvolvedor de aplicativos

Solução de problemas

ProblemaSolução

ID de cliente inválida ao tentar autenticar o usuário

Esse erro geralmente ocorre quando você está usando um ID de cliente com um segredo de cliente gerado. Você deve criar uma ID de cliente sem um segredo anexado a ela. Para obter mais informações, consulte Configurações específicas do aplicativo com clientes de aplicativos.

Recursos relacionados

Mais informações

TypeScript Arquivo de amostra

O exemplo de código a seguir é um TypeScript arquivo que invoca o processo de autenticação usando um AWS SDK para enviar atributos personalizados ao Amazon Cognito:

import * as AmazonCognitoIdentity from "amazon-cognito-identity-js";

const userPoolId: string = process.env.USER_POOL_ID ?? '';
const clientId: string = process.env.CLIENT_ID ?? '';

const poolData = {
  UserPoolId: userPoolId,
  ClientId: clientId
};
const userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData);

export const loginWithCognitoSDK = function (userName: string, password: string) {
  const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({
    Username: userName,
    Password: password,
    ClientMetadata: {
        customGroup: "MyCustomGroup",
        customApplicationData: "Custom data from a custom application"
    }
  });
  const userData = {
    Username: userName,
    Pool: userPool
  };

  const cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData);

  // Authenticate the user using the authenticationDetails object
  cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: function (result: any) {},
    onFailure: function (err: any) {},
  });
}
loginWithCognitoSDK(process.env.USERNAME ?? '', process.env.PASSWORD ?? '');

A amostra usa o AuthenticationDetails modelo do SDK JavaScript para fornecer o nome de usuário, a senha e o. ClientMetadada Após a autenticação no Amazon Cognito, os metadados do cliente podem ser recuperados dos tokens de acesso e ID.

Amostra de função Lambda

O exemplo de código a seguir é uma função Lambda vinculada ao Token de pré-geração do Amazon Cognito. Ele ajuda você a personalizar o token de acesso e o token de ID que o Amazon Cognito usa. Os tokens são passados pelas integrações entre sua arquitetura. Esse exemplo inclui um atributo de declaração personalizado chamado customApplicationData e um nome de grupo personalizado chamadoMyCustomGroup:

export const handler = async(event, context, callback) => {
    event.response = {
        claimsOverrideDetails: {
            claimsToAddOrOverride: { customApplicationData: event.request.clientMetadata.customApplicationData },
            groupOverrideDetails: { groupsToOverride: [event.request.clientMetadata.customGroup] }
        }
    };
    callback(null, event);
};

Exemplo de token de acesso

Você pode decodificar o token de acesso para visualizar os atributos personalizados que foram adicionados. Veja a seguir um exemplo de token de acesso:

{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "client_id": "<YOUR_CLIENT_ID>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "access",
  "scope": "aws.cognito.signin.user.admin",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "5c9c2708-a871-4428-bd9b-18ad261bea90",
  "username": "<USER_NAME>"
}

Exemplo de token de ID

Você pode decodificar o token de acesso para visualizar os atributos personalizados que foram adicionados. Veja a seguir um exemplo de token de acesso:

{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "cognito:username": "<USER_NAME>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "customApplicationData": "Custom data from a custom application",
  "aud": "<YOUR_CLIENT_ID>",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "id",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f",
  "email": "<USER_EMAIL>"
}