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á. # Envio de atributos personalizados para o Amazon Cognito e injeção desses atributos em tokens *Carlos Alessandro Ribeiro e Mauricio Mendoza, Amazon Web Services* ## Resumo O envio de atributos personalizados ao processo de autenticação do Amazon Cognito pode fornecer contexto adicional à aplicação, possibilitar controles de acesso mais detalhados e facilitar o gerenciamento de perfis de usuário e requisitos de autenticação. Esses recursos são úteis em uma ampla variedade de aplicações e cenários, e podem contribuir para aprimorar tanto a segurança quanto a performance de uma aplicação. Este padrão apresenta como enviar atributos personalizados para o processo de autenticação do Amazon Cognito sempre que uma aplicação necessitar adicionar informações ao [token de acesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html) ou ao [token de identidade (ID)](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html). Você emprega o Node.js como backend da aplicação A aplicação autentica um usuário com base em um [grupo de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html) do Amazon Cognito e fornece os atributos personalizados necessários para a geração do token. Você pode usar os [acionadores do AWS Lambda](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html) para o Amazon Cognito a fim de personalizar o processo de autenticação sem necessidade de modificações complexas no código ou esforço significativo. **Importante** O código e os exemplos deste padrão não são recomendados para workloads em produção, pois destinam-se apenas a fins de demonstração. Para workloads de produção, é necessária 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 ** + Um ativo Conta da AWS + Permissões para criar e gerenciar grupos de usuários e funções do Amazon Cognito AWS Lambda + AWS Command Line Interface (AWS CLI), [instalado](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [configurado](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) + Um ambiente de desenvolvimento integrado (IDE) com suporte para Node.js + Node.js, versão 18 ou versões posteriores, [instalado](https://nodejs.org/en/download/) + npm versão 8 ou versões posteriores, [instalado](https://docs.npmjs.com/getting-started) + O TypeScript, [instalado](https://www.typescriptlang.org/download/) **Limitações** + Este padrão não é aplicável à integração de aplicações por meio do fluxo de autenticação de credenciais de clientes. + Com o acionador para executar antes da geração de tokens, é possível adicionar ou alterar apenas determinados atributos do token de acesso e do token de identidade. Para obter mais informações, consulte [Pre token generation Lambda trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html) na documentação do Amazon Cognito. ## Arquitetura **Arquitetura de destino** O diagrama apresentado a seguir ilustra a arquitetura de destino para este padrão. O diagrama também mostra como a aplicação do Node.js pode funcionar com um backend para atualizar bancos de dados. No entanto, as atualizações do banco de dados pelo backend não fazem parte do escopo deste padrão. ![Uma aplicação do Node.js que emite um token de acesso com atributos personalizados para um grupo de usuários do Amazon Cognito.](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/images/pattern-img/9f0855e6-77f9-48c2-846e-f9c317127e1f/images/8c52c88b-8954-4b4c-aed3-fd8c22f84c1d.png) O diagrama mostra o seguinte fluxo de trabalho: 1. A aplicação do Node.js emite um token de acesso com atributos personalizados para o grupo de usuários do Amazon Cognito. 1. O grupo de usuários do Amazon Cognito aciona a função do Lambda para executar antes da geração de tokens, que personaliza os tokens de acesso e de identidade. 1. A aplicação do Node.js realiza uma chamada de API por meio do Amazon API Gateway. **nota** Os demais componentes da arquitetura apresentados são apenas ilustrativos e não fazem parte do escopo deste 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 CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)o [HashiCorp Terraform](https://www.terraform.io/docs) ou qualquer [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html)ferramenta de infraestrutura como código (IaC) compatível. Se você deseja escalar suas implantações, use pipelines de integração e entrega contínuas (CI/CD), que ajudam a evitar erros associados a implantações manuais. ## Ferramentas **Serviços da AWS** + [O Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) ajuda você a criar, publicar, manter, monitorar e proteger REST, HTTP e WebSocket APIs em qualquer escala. + O [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html) 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)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) é 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](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) é 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 JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html)fornece uma JavaScript API para Serviços da AWS. Você pode usá-la para criar bibliotecas ou aplicações para Node.js ou para o navegador. **Outras ferramentas** + [O Node.js](https://nodejs.org/en/docs/) é um ambiente de tempo de JavaScript execução orientado a eventos, projetado para criar aplicativos de rede escaláveis. + O [npm](https://docs.npmjs.com/about-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 sensíveis**: não armazene segredos ou dados sensíveis dentro da aplicação. Em vez disso, use um sistema externo no qual a aplicação possa obter essas informações, como [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html), [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) ou [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html). + **Implantação padronizada** — Use CI/CD pipelines para implantar seus aplicativos. Você pode usar serviços como [AWS CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html) e [AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html). + **Expiração do token**: defina um prazo de expiração curto para o token de acesso. + **Use uma conexão segura**: toda a comunicação entre a aplicação cliente e o backend deve ser criptografada utilizando SSL/TLS. Use [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html) para gerar e gerenciar SSL/TLS certificados e use a [Amazon CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) ou o [Elastic Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/what-is-load-balancing.html) para lidar com a SSL/TLS rescisão. + **Validar a entrada do usuário**: certifique-se de que toda entrada do usuário seja validada para prevenir ataques de injeção e outras vulnerabilidades de segurança. Use bibliotecas de validação de entrada e serviços como o Amazon API Gateway e o [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html#waf-intro) para prevenir vetores de ataque comuns. + **Use funções do IAM** — Use funções [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) para controlar o acesso aos AWS recursos e garantir que somente usuários autorizados tenham acesso. Siga o princípio de privilégio mínimo e assegure que cada usuário tenha somente as permissões necessárias para seu perfil. + **Use uma política de senhas**: configure uma política de senhas 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 a fim de fornecer uma camada adicional de segurança e reduzir o risco de acessos não autorizados. Use o [Centro de Identidade do AWS IAM](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) ou o Amazon Cognito para habilitar a MFA e outros métodos de autenticação. + **Armazene informações sensíveis com segurança**: armazene informações sensíveis, como senhas e tokens de acesso, de forma segura usando o [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) ou outros serviços de criptografia. + **Use métodos de autenticação robustos**: para aumentar a segurança do processo de autenticação, utilize métodos de autenticação robustos, como a autenticação biométrica ou a autenticação multifator. + **Monitore atividades suspeitas**: use o [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) e outras ferramentas de monitoramento para acompanhar atividades suspeitas e possíveis ameaças à segurança. Configure alertas automatizados para atividades incomuns e use a [Amazon GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html) ou [AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html)para detectar possíveis ameaças. + **Revise e atualize regularmente as políticas de segurança**: analise e atualize periodicamente as políticas e os procedimentos de segurança para garantir que atendam aos requisitos de segurança em constante mudança e às práticas recomendadas. Use AWS Config para rastrear e auditar alterações em suas políticas e procedimentos de segurança. + **Cadastro automático**: não habilite o cadastro automatizado 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 Cognito](https://aws.amazon.com/blogs/security/reduce-risks-of-user-sign-up-fraud-and-sms-pumping-with-amazon-cognito-user-pools/)AWS (postagem no blog). Para obter práticas recomendadas adicionais, consulte [Security best practices for Amazon Cognito user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-security-best-practices.html) na documentação do Amazon Cognito. ## Épicos ### Configurar os AWS recursos | Tarefa | Description | Habilidades necessárias | | --- | --- | --- | | Criar um grupo de usuários. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)Para obter mais informações e instruções sobre como configurar um grupo de usuários no Console de gerenciamento da AWS, consulte [Introdução aos grupos de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-user-pools.html) e [Adicionar mais recursos e opções de segurança ao seu grupo de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-next-steps.html).Para reduzir os custos, experimente o plano Essentials ou Lite para testar esse padrão. Para mais informações, consulte [Preço do Amazon Cognito](https://aws.amazon.com/cognito/pricing/). | Desenvolvedor de aplicativos, AWS DevOps | | Adicione um usuário ao grupo de usuários. | Digite o seguinte comando para criar um usuário no grupo de usuários do Amazon Cognito:
aws cognito-idp sign-up \
   --client-id  \
   --username  \
   --password  \
   --user-attributes Name="email",Value="" Name="name",Value=""
| Desenvolvedor de aplicativos, AWS DevOps | | Adicione o cliente da aplicação ao grupo de usuários. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | Administrador de sistemas da AWS, administrador da AWS, AWS DevOps, desenvolvedor de aplicativos | | Crie um acionador do Lambda para executar antes da geração de tokens. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | AWS DevOps, desenvolvedor de aplicativos | | Personalize o fluxo de trabalho do grupo de usuários. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)Para obter mais informações, consulte [Customizing user pool workflows with Lambda triggers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html) na documentação do Amazon Cognito. | AWS DevOps, desenvolvedor de aplicativos | ### Criação da aplicação do Node.js | Tarefa | Description | Habilidades necessárias | | --- | --- | --- | | Crie a aplicação do Node.js. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | Desenvolvedor de aplicativos | | Implemente a lógica de autenticação. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)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, digite os seguintes comandos para criar as variáveis de ambiente:
export USERNAME=""
export PASSWORD=""
export USER_POOL_ID=""
export CLIENT_ID=""
Não codifique segredos diretamente nem exponha suas credenciais. | Desenvolvedor de aplicativos | | Execute a aplicação . | Digite os seguintes comandos para executar a aplicação e confirmar que está funcionando:
npm run build
npm start
| Desenvolvedor de aplicativos | | Confirme se os atributos personalizados foram inseridos nos tokens. | Use os recursos de depuração do seu IDE para visualizar os tokens de acesso e de ID. Confirme se os atributos personalizados foram adicionados. Para obter tokens de amostra, consulte a seção [Informações adicionais](#send-custom-attributes-cognito-additional) deste padrão. | Desenvolvedor de aplicativos | ## Solução de problemas | Problema | Solução | | --- | --- | | ID de cliente inválida ao tentar autenticar o usuário | Este erro geralmente ocorre quando você usa uma ID de cliente com um segredo do cliente gerado. É necessário criar uma ID de cliente que não tenha um segredo vinculado. Para obter mais informações, consulte [Application-specific settings with app clients](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html). | ## Recursos relacionados + [Customizing user pool workflows with Lambda triggers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html) (documentação do Amazon Cognito) + [Pre token generation Lambda trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html) (documentação do Amazon Cognito) + [CognitoIdentityProviderClient](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cognito-identity-provider/)(AWS SDK para JavaScript documentação) + [cognito-idp](https://awscli.amazonaws.com/v2/documentation/api/2.0.34/reference/cognito-idp/index.html#cli-aws-cognito-idp) (documentação)AWS CLI ## 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 usando os tokens de acesso e de ID. **Amostra de função Lambda** A amostra de código apresentada a seguir é uma função do Lambda vinculada ao [token de pré-geração](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html) do Amazon Cognito. A função ajuda você a personalizar o token de acesso e o token de ID utilizados pelo Amazon Cognito. Os tokens são transmitidos por meio das integrações da sua arquitetura. Esta amostra inclui um atributo de declaração personalizado chamado `customApplicationData` e um nome de grupo personalizado chamado `MyCustomGroup`: ``` 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); }; ``` **Token de acesso de amostra** É possível decodificar o token de acesso para visualizar os atributos personalizados que foram adicionados. Abaixo, apresentamos um token de acesso de amostra: ``` { "sub": "6daf331f-4451-48b4-abde-774579299204", "cognito:groups": [ "MyCustomGroup" ], "iss": "https://cognito-idp..amazonaws.com/", "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": "" } ``` **Token de ID de amostra** É possível decodificar o token de acesso para visualizar os atributos personalizados que foram adicionados. Abaixo, apresentamos um token de acesso de amostra: ``` { "sub": "6daf331f-4451-48b4-abde-774579299204", "cognito:groups": [ "MyCustomGroup" ], "iss": "https://cognito-idp..amazonaws.com/", "cognito:username": "", "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc", "customApplicationData": "Custom data from a custom application", "aud": "", "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e", "token_use": "id", "auth_time": 1677979246, "exp": 1677982846, "iat": 1677979246, "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f", "email": "" } ```