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 ou ao token de identidade (ID). 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 do Amazon Cognito e fornece os atributos personalizados necessários para a geração do token. Você pode usar os acionadores do AWS Lambda 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.

Pré-requisitos e limitações

Pré-requisitos

Limitações

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.

O diagrama mostra o seguinte fluxo de trabalho:

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ê 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

Outras ferramentas

Práticas recomendadas

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

Para obter práticas recomendadas adicionais, consulte Security best practices for Amazon Cognito user pools na documentação do Amazon Cognito.

Épicos

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>"

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

npm run build
npm start

Solução de problemas

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 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 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.<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>"
}

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.<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>"
}