Envíe atributos personalizados a Amazon Cognito e introdúzcalos en los tokens

Carlos Alessandro Ribeiro y Mauricio Mendoza, Amazon Web Services

Resumen

El envío de atributos personalizados a un proceso de autenticación de Amazon Cognito puede proporcionar contexto adicional a una aplicación, permitir controles de acceso más detallados y facilitar la administración de los perfiles de usuario y los requisitos de autenticación. Estas funciones son útiles en una amplia gama de aplicaciones y escenarios, y pueden ayudarle a mejorar la seguridad y la funcionalidad generales de una aplicación.

Este patrón muestra cómo enviar atributos personalizados a un proceso de autenticación de Amazon Cognito cuando una aplicación necesita proporcionar contexto adicional al token de acceso o al token de identidad (ID). El archivo Node.js se utiliza como aplicación de back-end. La aplicación autentica a un usuario de un grupo de usuarios de Amazon Cognito y transfiere los atributos personalizados necesarios para la generación de los tokens. Puede utilizar los AWS Lambda activadores de Amazon Cognito para personalizar el proceso de autenticación sin necesidad de una personalización importante del código ni un esfuerzo significativo.

importante

El código y los ejemplos de este patrón no se recomiendan para las cargas de trabajo de producción porque están destinados únicamente a fines de demostración. Para las cargas de trabajo de producción, se requiere una configuración adicional por parte del cliente. Utilice este patrón como referencia únicamente con fines piloto o para proof-of-concept fines específicos.

Requisitos previos y limitaciones

Requisitos previos 

• Un activo Cuenta de AWS

• Permisos para crear y gestionar grupos de usuarios y funciones de Amazon Cognito AWS Lambda

• AWS Command Line Interface (AWS CLI), instalado y configurado

• Un entorno de desarrollo integrado (IDE) compatible con Node.js

• Node.js, versión 18 o posterior, instalada

• npm versión 8 o posterior, instalada

• TypeScript, instalado

Limitaciones

• Este patrón no se aplica a la integración de aplicaciones a través del flujo de autenticación de credenciales de cliente.

• El activador previo a la generación del token puede añadir o cambiar solo algunos atributos del token de acceso y del token de identidad. Para obtener más información, consulte el activador Lambda previo a la generación del token en la documentación de Amazon Cognito.

Arquitectura

Arquitectura de destino

El siguiente diagrama muestra la arquitectura de destino de este patrón. También muestra cómo podría funcionar la aplicación Node.js con un backend para actualizar las bases de datos. Sin embargo, las actualizaciones de las bases de datos de fondo están fuera del ámbito de este patrón.

En el diagrama, se muestra el siguiente flujo de trabajo:

1. La aplicación Node.js emite un token de acceso con atributos personalizados para el grupo de usuarios de Amazon Cognito.

2. El grupo de usuarios de Amazon Cognito inicia la función Lambda previa a la generación del token, que personaliza los tokens de acceso e ID.

3. La aplicación Node.js realiza una llamada a la API a través de Amazon API Gateway.

nota

Los demás componentes arquitectónicos que se muestran en esta arquitectura son solo de ejemplo y están fuera del alcance de este patrón.

Automatizar y escalar

Puede automatizar el aprovisionamiento de grupos de usuarios AWS Lambda , funciones, instancias de bases de datos y otros recursos de Amazon Cognito AWS CloudFormationmediante Terraform o cualquier herramienta de infraestructura como código (IaC) compatible. AWS Cloud Development Kit (AWS CDK)HashiCorp Si desea escalar sus implementaciones, utilice canalizaciones de integración y entrega continuas (CI/CD), que ayudan a evitar los errores asociados a las implementaciones manuales.

Herramientas

Servicios de AWS

• Amazon API Gateway le ayuda a crear, publicar, mantener, supervisar y proteger REST, HTTP y WebSocket APIs a cualquier escala.

• Amazon Cognito ofrece autenticación, autorización y administración de usuarios para aplicaciones móviles y web.

• Amazon Elastic Container Service (Amazon ECS) es un servicio de administración de contenedores escalable y rápido que ayuda a ejecutar, detener y administrar contenedores en un clúster.

• AWS Lambda es un servicio de computación que ayuda a ejecutar código sin necesidad de aprovisionar ni administrar servidores. Ejecuta el código solo cuando es necesario y amplía la capacidad de manera automática, por lo que solo pagará por el tiempo de procesamiento que utilice.

• AWS SDK para JavaScriptproporciona una JavaScript API para Servicios de AWS. Puede usarla para crear bibliotecas o aplicaciones para Node.js o el navegador.

Otras herramientas

• Node.js es un entorno de JavaScript ejecución basado en eventos que está diseñado para crear aplicaciones de red escalables.

• npm es un registro de software que se ejecuta en un entorno Node.js y se utiliza para compartir o tomar prestados paquetes y administrar la implementación de paquetes privados.

Prácticas recomendadas

Le recomendamos que implemente las siguientes prácticas recomendadas:

• Secretos y datos confidenciales: no almacene secretos ni datos confidenciales en la aplicación. Utilice un sistema externo del que la aplicación pueda extraer los datos AWS AppConfigAWS Secrets Manager, como un almacén de AWS Systems Manager parámetros.

• Implementación estandarizada: utilice CI/CD canalizaciones para implementar sus aplicaciones. Puede utilizar servicios como AWS CodeBuildy AWS CodePipeline.

• Caducidad del token: establece una fecha de caducidad corta para el token de acceso.

• Utilice una conexión segura: todas las comunicaciones entre la aplicación cliente y el backend deben cifrarse mediante SSL/TLS. Utilice AWS Certificate Manager (ACM) para generar y gestionar SSL/TLS certificados, y utilice Amazon CloudFront o Elastic Load Balancing para gestionar la SSL/TLS rescisión.

• Valide las entradas de los usuarios: asegúrese de que todas las entradas de los usuarios estén validadas para evitar ataques por inyección y otras vulnerabilidades de seguridad. Utilice bibliotecas y servicios de validación de entradas, como Amazon API Gateway, AWS WAFpara evitar los vectores de ataque más comunes.

• Utilice funciones de IAM: utilice funciones AWS Identity and Access Management (IAM) para controlar el acceso a AWS los recursos y asegurarse de que solo los usuarios autorizados tengan acceso. Siga el principio de privilegios mínimos y asegúrese de que cada usuario solo tenga los permisos necesarios para desempeñar su función.

• Utilice una política de contraseñas: configure una política de contraseñas que cumpla con sus requisitos de seguridad, como la longitud mínima, la complejidad y la caducidad. Utilice Secrets Manager o AWS Systems Manager Parameter Store para almacenar y gestionar las contraseñas de forma segura.

• Habilite la autenticación multifactorial (MFA): habilite la MFA para todos los usuarios a fin de proporcionar una capa adicional de seguridad y reducir el riesgo de acceso no autorizado. Utilice AWS IAM Identity CenterAmazon Cognito para habilitar el MFA y otros métodos de autenticación.

• Guarde la información confidencial de forma segura: almacene la información confidencial, como contraseñas y tokens de acceso, de forma segura mediante AWS Key Management Service (AWS KMS) u otros servicios de cifrado.

• Utilice métodos de autenticación sólidos: para aumentar la seguridad del proceso de autenticación, utilice métodos de autenticación sólidos, como la autenticación biométrica o la autenticación multifactorial.

• Supervise la actividad sospechosa: utilice AWS CloudTraily otras herramientas de supervisión para detectar actividades sospechosas y posibles amenazas a la seguridad. Configura alertas automatizadas para detectar actividades inusuales y utiliza Amazon GuardDuty o AWS Security Hubpara detectar posibles amenazas.

• Revise y actualice periódicamente las políticas de seguridad: revise y actualice periódicamente sus políticas y procedimientos de seguridad para asegurarse de que cumplen con sus requisitos de seguridad y mejores prácticas cambiantes. Úselo AWS Config para realizar un seguimiento y auditar los cambios en sus políticas y procedimientos de seguridad.

• Registro automático: no habilite el registro automático en un grupo de usuarios de Amazon Cognito. Para obtener más información, consulte Reducir los riesgos de fraude en el registro de usuarios y la transferencia de SMS con los grupos de usuarios de Amazon CognitoAWS (entrada del blog).

Para obtener más información sobre las prácticas recomendadas, consulte las prácticas recomendadas de seguridad para los grupos de usuarios de Amazon Cognito en la documentación de Amazon Cognito.

Epics

Configure los recursos AWS

Tarea	Descripción	Habilidades requeridas
Cree un grupo de usuarios.	En un terminal CLI, introduzca el siguiente comando para crear un grupo de usuarios de Amazon Cognito: aws cognito-idp create-user-pool \ --pool-name <MyUserPool> Introduzca el siguiente comando para crear un identificador de cliente y un secreto que se utilizarán con el 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 obtener más información e instrucciones sobre cómo configurar un grupo de usuarios en el AWS Management Console, consulte Introducción a los grupos de usuarios y Añadir más funciones y opciones de seguridad a su grupo de usuarios. sugerencia Para reducir los costes, utilice el plan Essentials o el plan Lite para probar este patrón. Para obtener más información, consulte Precios de Amazon Cognito.	Desarrollador de aplicaciones, AWS DevOps
Agregue un usuario al grupo de usuarios.	Introduzca el siguiente comando para crear un usuario en el grupo de usuarios de Amazon Cognito: aws cognito-idp sign-up \ --client-id <ClientID> \ --username <[e-mail]> \ --password <PASSWORD> \ --user-attributes Name="email",Value="<[e-mail]>" Name="name",Value="<Jane>"	Desarrollador de aplicaciones, AWS DevOps
Agregue el cliente de la aplicación al grupo de usuarios.	Vaya a la consola de Amazon Cognito. Elija User pools (Grupos de usuarios). Elija el grupo de usuarios que creó anteriormente. En Defina su aplicación, elija el tipo de aplicación que mejor se adapte al escenario de aplicación para el que desea crear los servicios de autenticación y autorización. En Asigne un nombre a su aplicación, introduzca un nombre descriptivo o continúe con el nombre predeterminado. En Añadir una URL de retorno, introduce una ruta de redireccionamiento a tu aplicación para que los usuarios completen la autenticación. Selecciona Crear tu aplicación. Puede configurar las opciones avanzadas después de crear el cliente de la aplicación.	Administrador de sistemas de AWS, administrador de AWS DevOps, desarrollador de aplicaciones
Cree un activador Lambda para la generación previa al token.	Abra la página de Functions (Funciones) en la consola de Lambda. Elija Crear función. Seleccione Crear desde cero. En el panel de información básica, escriba el nombre de la función. myPreTokenGenerationLambdaFunction En Runtime, elija Node.js 22. Deje la arquitectura establecida en x86_64. Elija Crear función. En la pestaña Código, en Código fuente, introduzca la función Lambda de ejemplo de la sección Recursos adicionales de este patrón. Esta función Lambda inyecta los atributos personalizados en el token de ID y el token de acceso.	AWS DevOps, desarrollador de aplicaciones
Personalice el flujo de trabajo del grupo de usuarios.	Vaya a la consola de Amazon Cognito. Elija User pools (Grupos de usuarios). Elija el grupo de usuarios que creó anteriormente. En el panel de navegación izquierdo, en Autenticación, elija Extensiones. Seleccione Añadir disparador Lambda. Agregue o edite un desencadenador previo a la generación de tokens. En el tipo de disparador, elija Autenticación. En Autenticación, elija Activador previo a la generación del token. En Asignar función Lambda, elija. myPreTokenGenerationLambdaFunction Seleccione Añadir disparador Lambda. Elija una versión de evento desencadenante de Funciones básicas con personalización del token de acceso para las identidades de los usuarios o Funciones básicas con personalización del token de acceso para las identidades de los usuarios y las máquinas. Esta configuración actualiza los parámetros de solicitud que Amazon Cognito envía a la función para incluir campos para la personalización del token de acceso. Para obtener más información, consulte Personalización de los flujos de trabajo de grupos de usuarios con activadores Lambda en la documentación de Amazon Cognito.	AWS DevOps, desarrollador de aplicaciones

Cree la aplicación Node.js

Tarea	Descripción	Habilidades requeridas
Cree la aplicación Node.js.	En una terminal, introduzca los siguientes 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 Modifique el package.json archivo para incluir los scripts de TypeScript compilación: "scripts": { "start": "node src/index.js", "build": "tsc" },	Desarrollador de aplicaciones
Implemente la lógica de autenticación.	Abra el archivo index.ts. Pegue el ejemplo de texto mecanografiado que se proporciona en la sección de recursos adicionales de este patrón. Guarde y cierre el archivo index.ts. nota Puede crear su propio TypeScript archivo o modificar la muestra proporcionada según sea necesario para su caso de uso.	Desarrollador de aplicaciones
Configure las variables de entorno y el archivo de configuración.	En un terminal, introduzca los siguientes comandos para crear las variables de entorno: export USERNAME="<COGNITO_USER_NAME>" export PASSWORD="<COGNITO_USER_PASSWORD>" export USER_POOL_ID="<COGNITO_USER_ID>" export CLIENT_ID="<COGNITO_CLIENT_ID>" importante No codifique secretos ni exponga sus credenciales.	Desarrollador de aplicaciones
Ejecute la aplicación.	Introduzca los siguientes comandos para ejecutar la aplicación y confirmar que funciona: npm run build npm start	Desarrollador de aplicaciones
Confirme que los atributos personalizados estén insertados en los tokens.	Utilice las funciones de depuración de su IDE para ver los tokens de acceso e ID. Confirme que se hayan agregado los atributos personalizados. Para ver ejemplos de fichas, consulta la sección de información adicional de este patrón.	Desarrollador de aplicaciones

Solución de problemas

Problema	Solución
El ID de cliente no es válido al intentar autenticar al usuario	Este error suele producirse cuando se utiliza un ID de cliente con un secreto de cliente generado. Debe crear un ID de cliente sin ningún secreto adjunto. Para obtener más información, consulte Configuración específica de la aplicación con los clientes de la aplicación.

Recursos relacionados

• Personalización de los flujos de trabajo de grupos de usuarios con activadores Lambda (documentación de Amazon Cognito)

• Activador Lambda previo a la generación del token (documentación de Amazon Cognito)

• CognitoIdentityProviderClient(documentación)AWS SDK para JavaScript

• cognito-idp (documentación)AWS CLI

Información adicional

Archivo de TypeScript muestra

El siguiente ejemplo de código es un TypeScript archivo que invoca el proceso de autenticación mediante un AWS SDK para enviar atributos personalizados a 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 ?? '');

En el ejemplo se utiliza el AuthenticationDetails modelo del SDK JavaScript para proporcionar el nombre de usuario, la contraseña y el. ClientMetadada Tras la autenticación en Amazon Cognito, los metadatos del cliente se pueden recuperar de los tokens de acceso e ID.

Función de Lambda de ejemplo

El siguiente ejemplo de código es una función Lambda vinculada al token de pregeneración de Amazon Cognito. Le ayuda a personalizar el token de acceso y el token de ID que utiliza Amazon Cognito. Los tokens se transfieren a través de las integraciones entre su arquitectura. Este ejemplo incluye un atributo de notificación personalizado denominado customApplicationData y un nombre de grupo personalizado denominadoMyCustomGroup:

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

Ejemplo de token de acceso

Puede decodificar el token de acceso para visualizar los atributos personalizados que se agregaron. El siguiente es un ejemplo de token de acceso:

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

Ejemplo de token de identificación

Puede decodificar el token de acceso para visualizar los atributos personalizados que se agregaron. El siguiente es un ejemplo de token de acceso:

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