Personalización de flujos de trabajo de grupos de usuarios con desencadenadores de Lambda - Amazon Cognito

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Personalización de flujos de trabajo de grupos de usuarios con desencadenadores de Lambda

Amazon Cognito trabaja con AWS Lambda funciones para modificar el comportamiento de autenticación de su grupo de usuarios. Puede configurar su grupo de usuarios para que invoque automáticamente funciones de Lambda antes de su primer registro, después de que completen la autenticación y en varias etapas intermedias. Sus funciones pueden modificar el comportamiento predeterminado del flujo de autenticación, realizar API solicitudes para modificar el grupo de usuarios u otros AWS recursos y comunicarse con sistemas externos. El código de las funciones de Lambda es suyo. Amazon Cognito envía datos de eventos a su función, espera a que la función procese los datos y, en la mayoría de los casos, anticipa un evento de respuesta que refleja cualquier cambio que desee realizar en la sesión.

Dentro del sistema de eventos de solicitud y respuesta, puede introducir sus propios desafíos de autenticación, migrar usuarios entre su grupo de usuarios y otro almacén de identidades, personalizar los mensajes y modificar los identificadores JSON web (JWTs).

Los disparadores de Lambda pueden personalizar la respuesta que Amazon Cognito ofrece al usuario después de iniciar una acción en su grupo de usuarios. Por ejemplo, puede impedir el inicio de sesión de un usuario que, de otro modo, lo conseguiría. También pueden realizar operaciones en tiempo de ejecución en su AWS entorno, fuentes externasAPIs, bases de datos o almacenes de identidades. El disparador de migración de usuarios, por ejemplo, puede combinar una acción externa con un cambio en Amazon Cognito: puede buscar la información del usuario en un directorio externo y, a continuación, establecer los atributos de un nuevo usuario en función de esa información externa.

Cuando tiene un disparador de Lambda asignado a su grupo de usuarios, Amazon Cognito interrumpe su flujo predeterminado para solicitar información a su función. Amazon Cognito genera un JSON evento y lo transfiere a su función. El evento contiene información sobre la solicitud del usuario para crear una cuenta de usuario, iniciar sesión, restablecer una contraseña o actualizar un atributo. La función tendrá entonces la oportunidad de realizar una acción o de enviar de vuelta el evento sin modificarlo.

En la siguiente tabla se resumen algunas formas de utilizar los desencadenadores de Lambda para personalizar las operaciones del grupo de usuarios:

Flujo del grupo de usuarios Operación Descripción

Flujo de autenticación personalizado

Definición de desafíos de autenticación Determina el siguiente desafío en un flujo de autenticación personalizado
Creación de desafíos de autenticación Crea un desafío en un flujo de autenticación personalizado
Verificación de la respuesta al desafío de autenticación Determina si una respuesta es correcta en un flujo de autenticación personalizado
Eventos de autenticación Desencadenador de Lambda anterior a la autenticación Validación personalizada para aceptar o denegar la solicitud de inicio de sesión
Desencadenador de Lambda posterior a la autenticación. Registra eventos para los análisis personalizados
Desencadenador de Lambda anterior a la generación del token Aumenta o suprime las notificaciones de tokens
Registro Desencadenador de Lambda de prerregistro. Realiza una validación personalizada que acepta o rechaza la solicitud de inscripción
Desencadenador de Lambda de posconfirmación. Agrega mensajes de bienvenida personalizados o el registro de eventos para los análisis personalizados
Migración del desencadenador de Lambda del usuario Migra un usuario desde un directorio de usuarios existente a los grupos de usuarios
Mensajes Desencadenador de Lambda para mensajes personalizados Realiza una personalización avanzada y localiza mensajes
Creación de tokens Desencadenador de Lambda anterior a la generación del token Agrega o elimina atributos en tokens de identificación
Correo electrónico y SMS proveedores externos Desencadenadores de Lambda para remitentes personalizados Utiliza un proveedor externo para enviar SMS y enviar mensajes por correo electrónico

Consideraciones importantes

Al preparar sus grupos de usuarios para funciones de Lambda, tenga en cuenta lo siguiente:

  • Es posible que los eventos que Amazon Cognito envía a los desencadenadores de Lambda cambien con las nuevas características. Es posible que cambien las posiciones de los elementos de respuesta y solicitud en la JSON jerarquía o que se agreguen los nombres de los elementos. En la función de Lambda, puede esperar recibir los pares clave-valor del elemento de entrada que se describen en esta guía, pero una validación de entrada más estricta puede provocar errores en las funciones.

  • Puede elegir una de las múltiples versiones de los eventos que Amazon Cognito envía a algunos desencadenadores. Es posible que algunas versiones requieran que acepte un cambio en los precios de Amazon Cognito. Para obtener más información acerca de los precios, consulte Precios de Amazon Cognito. Para personalizar los tokens de acceso en Desencadenador de Lambda anterior a la generación del token, debe configurar el grupo de usuarios con características de seguridad avanzadas y actualizar la configuración de los desencadenadores de Lambda para usar la versión 2 del evento.

  • Excepto por Desencadenadores de Lambda para remitentes personalizados, Amazon Cognito invoca funciones de Lambda de forma sincrónica. Cuando Amazon Cognito llama a la función de Lambda, esta debe responder en un plazo de 5 segundos. Si no es así y si se puede volver a intentar la llamada, Amazon Cognito vuelve a intentar la llamada. Después de tres intentos fallidos, la función agota el tiempo de espera. No puede cambiar ese valor de tiempo de espera de cinco segundos. Para obtener más información, consulte el modelo de programación Lambda en la Guía para AWS Lambda desarrolladores.

    Amazon Cognito no vuelve a intentar las llamadas a funciones que devuelvan un error de Invoke con un código de HTTP estado 500-599. Estos códigos indican un problema de configuración que hace que Lambda no pueda lanzar la función. Para obtener más información, consulte Gestión de errores y reintentos automáticos. AWS Lambda

  • No puede declarar una versión de función en la configuración de su desencadenador de Lambda. Los grupos de usuarios de Amazon Cognito invocan la última versión de su función de forma predeterminada. Sin embargo, puedes asociar una versión de función LambdaArn a un alias y configurar el activador como el alias ARN de una UpdateUserPoolAPIsolicitud CreateUserPoolo. Esta opción no está disponible en la AWS Management Console. Para obtener más información acerca de los alias, consulte Alias de función de Lambda en la Guía para desarrolladores de AWS Lambda .

  • Si elimina un desencadenador de Lambda, deberá actualizar el desencadenador correspondiente en el grupo de usuarios. Por ejemplo, si elimina el desencadenador posterior a la autenticación, deberá establecer el desencadenador Posterior a la autenticación del grupo de usuarios correspondiente en none (ninguno).

  • Si la función de Lambda no devuelve los parámetros de solicitud y respuesta a Amazon Cognito o devuelve un error, el evento de autenticación no se realiza correctamente. Puede devolver un error en la función para impedir que un usuario se registre, autentique, genere el token o cualquier otra etapa del flujo de autenticación que invoque un desencadenador de Lambda.

    La interfaz de usuario alojada en Amazon Cognito devuelve los errores que los desencadenadores de Lambda generan como texto de error sobre la solicitud de inicio de sesión. Los grupos de usuarios de Amazon Cognito API devuelven errores desencadenantes en el formato. [trigger] failed with error [error text from response] Como práctica recomendada, en las funciones de Lambda solo genere errores que quiera que vean los usuarios. Utilice métodos de salida, como print() registrar cualquier información confidencial o de depuración en los CloudWatch registros. Para ver un ejemplo, consulte Ejemplo de antes de registrarse: denegar el registro si el nombre de usuario tiene menos de cinco caracteres.

  • Puede añadir una función Lambda en otra Cuenta de AWS como activador para su grupo de usuarios. Debe añadir activadores multicuenta con las UpdateUserPoolAPIoperaciones CreateUserPooly, o sus equivalentes, en y en AWS CloudFormation . AWS CLI No puedes añadir funciones multicuenta en. AWS Management Console

  • Al agregar un desencadenador de Lambda en la consola de Amazon Cognito, Amazon Cognito agrega una política basada en recursos a la función que permite al grupo de usuarios invocar la función. Cuando crea un desencadenador de Lambda fuera de la consola de Amazon Cognito, incluida una función entre cuentas, debe agregar permisos a la política basada en recursos de la función de Lambda. Los permisos agregados deben permitir a Amazon Cognito invocar la función en nombre del grupo de usuarios. Puede añadir permisos desde la consola Lambda o utilizar la operación Lambda. AddPermissionAPI

    Ejemplo de política basada en recursos de Lambda

    En el siguiente ejemplo de política basada en recursos de Lambda otorga a Amazon Cognito una capacidad limitada para invocar una función Lambda. Amazon Cognito solo puede invocar la función cuando lo hace en nombre del grupo de usuarios en la condición aws:SourceArn y en la cuenta en la condición aws:SourceAccount.

    { "Version": "2012-10-17", "Id": "default", "Statement": [ { "Sid": "lambda-allow-cognito", "Effect": "Allow", "Principal": { "Service": "cognito-idp.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "<your Lambda function ARN>", "Condition": { "StringEquals": { "AWS:SourceAccount": "<your account number>" }, "ArnLike": { "AWS:SourceArn": "<your user pool ARN>" } } } ] }

Adición de un desencadenador de Lambda a un grupo de usuarios

Para agregar un desencadenador de Lambda a un grupo de usuarios con la consola, siga estos pasos:
  1. Use la consola de Lambda para crear una función de Lambda. Para obtener más información sobre las funciones de Lambda, consulte la Guía para desarrolladores de AWS Lambda.

  2. Diríjase a la consola de Amazon Cognito y luego elija User Pools (Grupos de usuarios).

  3. Elija un grupo de usuarios existente en la lista o cree un grupo de usuarios.

  4. Elija la pestaña User pool properties (Propiedades del grupo de usuarios) y localice Lambda triggers (Desencadenadores Lambda).

  5. Elija Add a Lambda trigger (Agregar un desencadenador Lambda).

  6. Seleccione una Category (Categoría) de desencadenador de Lambda en función de la fase de autenticación que desee personalizar.

  7. Seleccione Asignar función Lambda y seleccione una función Región de AWS igual a la de su grupo de usuarios.

    nota

    Si sus credenciales AWS Identity and Access Management (IAM) tienen permiso para actualizar la función de Lambda, Amazon Cognito añade una política de Lambda basada en recursos. Con esta política, Amazon Cognito puede llamar a la función que seleccione. Si las credenciales con las que ha iniciado sesión no tienen IAM permisos suficientes, debe actualizar la política basada en recursos por separado. Para obtener más información, consulte Consideraciones importantes.

  8. Elija Save changes (Guardar cambios).

  9. Puede utilizarla CloudWatch en la consola Lambda para registrar la función Lambda. Para obtener más información, consulte Acceso a CloudWatch los registros de Lambda.

Evento desencadenador de Lambda para un grupo de usuarios

Amazon Cognito transfiere la información del evento a la función de Lambda. A continuación, la función de Lambda devuelve el mismo objeto de evento a Amazon Cognito con los cambios en la respuesta. Con este evento, se muestran los parámetros comunes del desencadenador de Lambda.

JSON
{ "version": "string", "triggerSource": "string", "region": AWSRegion, "userPoolId": "string", "userName": "string", "callerContext": { "awsSdkVersion": "string", "clientId": "string" }, "request": { "userAttributes": { "string": "string", .... } }, "response": {} }

Parámetros comunes del desencadenador de Lambda para un grupo de usuarios

versión

El número de versión de la función de Lambda.

triggerSource

El nombre del evento que desencadenó la función de Lambda. Para obtener una descripción de cada uno, triggerSource consulteConexión de disparadores de Lambda a las operaciones funcionales del grupo de usuarios.

región

El Región de AWS como AWSRegion ejemplo.

userPoolId

El ID del grupo de usuarios.

userName

El nombre de usuario del usuario actual.

callerContext

Metadatos sobre la solicitud y el entorno del código. Contiene los campos awsSdkVersiony clientId.

awsSdkVersion

La versión AWS SDK que generó la solicitud.

clientId

El ID de cliente de la aplicación del grupo de usuarios.

request

Detalles de la API solicitud de tu usuario. Incluye los siguientes campos y cualquier parámetro de solicitud que sea específico del disparador. Por ejemplo, un evento que Amazon Cognito envía a un desencadenador de autenticación previa también contendrá un parámetro userNotFound. Puede procesar el valor de este parámetro para realizar una acción personalizada cuando el usuario intente iniciar sesión con un nombre de usuario no registrado.

userAttributes

Uno o varios pares de clave-valor de nombres y valores de atributos de usuario, por ejemplo "email": "john@example.com".

Respuesta

Este parámetro no contiene ninguna información en la solicitud original. La función de Lambda debe devolver el evento completo a Amazon Cognito y añadir los parámetros de devolución a response. Para ver qué parámetros de devolución puede incluir la función, consulte la documentación del disparador que desee utilizar.

Conexión de API operaciones a activadores Lambda

En las siguientes secciones, se describen los disparadores de Lambda a los que invoca Amazon Cognito a partir de la actividad de su grupo de usuarios.

Cuando su aplicación inicia sesión con los usuarios a través de los grupos de usuariosAPI, la interfaz de usuario alojada o los puntos de enlace del grupo de usuarios de Amazon Cognito, Amazon Cognito invoca las funciones de Lambda en función del contexto de la sesión. Para obtener más información sobre los grupos de usuarios API y los puntos de enlace de los grupos de usuarios de Amazon Cognito, consulte. Uso de los grupos de usuarios API y el servidor de autorización En las tablas de las secciones siguientes, se describen los eventos que hacen que Amazon Cognito invoque una función y la cadena triggerSource que Amazon Cognito incluye en la solicitud.

Activadores Lambda en Amazon Cognito API

En la siguiente tabla, se describen las cadenas de origen de los disparadores de Lambda que Amazon Cognito puede invocar cuando la aplicación crea, inicia sesión o actualiza a un usuario local.

Fuentes de activación de usuarios locales en Amazon Cognito API
APIoperación Disparador de Lambda Origen del disparador

AdminCreateUser

Anterior a la inscripción

PreSignUp_AdminCreateUser

Anterior a la generación del token

TokenGeneration_NewPasswordChallenge

Mensaje personalizado

CustomMessage_AdminCreateUser

Remitente de correo electrónico personalizado

CustomEmailSender_AdminCreateUser

SMSRemitente personalizado

CustomSMSSender_AdminCreateUser

SignUp

Anterior a la inscripción

PreSignUp_SignUp

Mensaje personalizado

CustomMessage_SignUp

Remitente de correo electrónico personalizado

CustomEmailSender_SignUp

SMSRemitente personalizado

CustomSMSSender_SignUp

ConfirmSignUp

AdminConfirmSignUp

Posterior a la confirmación

PostConfirmation_ConfirmSignUp

InitiateAuth

AdminInitiateAuth

Anterior a la autenticación

PreAuthentication_Authentication

Definición de desafíos de autenticación

DefineAuthChallenge_Authentication

Creación de desafíos de autenticación

CreateAuthChallenge_Authentication

Anterior a la generación del token

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens

Migración de usuarios

UserMigration_Authentication

Mensaje personalizado

CustomMessage_Authentication

Remitente de correo electrónico personalizado

CustomEmailSender_AccountTakeOverNotification

CustomEmailSender_Authentication

SMSRemitente personalizado

CustomSMSSender_Authentication

ForgotPassword

Migración de usuarios

UserMigration_ForgotPassword

Mensaje personalizado

CustomMessage_ForgotPassword

Remitente de correo electrónico personalizado

CustomEmailSender_ForgotPassword

SMSRemitente personalizado

CustomSMSSender_ForgotPassword

ConfirmForgotPassword

Posterior a la confirmación

PostConfirmation_ConfirmForgotPassword

UpdateUserAttributes

AdminUpdateUserAttributes

Mensaje personalizado

CustomMessage_UpdateUserAttribute

Remitente de correo electrónico personalizado

CustomEmailSender_UpdateUserAttribute

SMSRemitente personalizado

CustomSMSSender_UpdateUserAttribute

VerifyUserAttributes

Mensaje personalizado

CustomMessage_VerifyUserAttribute

Remitente de correo electrónico personalizado

CustomEmailSender_VerifyUserAttribute

SMSRemitente personalizado

CustomSMSSender_VerifyUserAttribute

Se activa Lambda para los usuarios locales de Amazon Cognito en la interfaz de usuario alojada

En la siguiente tabla, se describen las cadenas de origen de los disparadores de Lambda que Amazon Cognito puede invocar cuando un usuario local inicia sesión en el grupo de usuarios con la interfaz de usuario alojada.

Orígenes de los desencadenadores de usuarios locales en la interfaz de usuario alojada
Interfaz de usuario alojada URI Disparador de Lambda Origen del disparador
/signup Anterior a la inscripción

PreSignUp_SignUp

Mensaje personalizado

CustomMessage_SignUp

Remitente de correo electrónico personalizado

CustomEmailSender_SignUp

SMSRemitente personalizado

CustomSMSSender_SignUp

/confirmuser Posterior a la confirmación

PostConfirmation_ConfirmSignUp

/login Anterior a la autenticación

PreAuthentication_Authentication

Definición de desafíos de autenticación

DefineAuthChallenge_Authentication

Creación de desafíos de autenticación

CreateAuthChallenge_Authentication

Anterior a la generación del token

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens

Migración de usuarios

UserMigration_Authentication

Mensaje personalizado

CustomMessage_Authentication

Remitente de correo electrónico personalizado

CustomEmailSender_AccountTakeOverNotification

CustomEmailSender_Authentication

SMSRemitente personalizado

CustomSMSSender_Authentication

/forgotpassword Migración de usuarios

UserMigration_ForgotPassword

Mensaje personalizado

CustomMessage_ForgotPassword

Remitente de correo electrónico personalizado

CustomEmailSender_ForgotPassword

SMSRemitente personalizado

CustomSMSSender_ForgotPassword

/confirmforgotpassword Posterior a la confirmación

PostConfirmation_ConfirmForgotPassword

Desencadenadores de Lambda para usuarios federados

Puede utilizar los siguientes desencadenadores de Lambda para personalizar los flujos de trabajo del grupo de usuarios para los usuarios que inician sesión con un proveedor federado.

nota

Los usuarios federados pueden usar la UI alojada en Amazon Cognito para iniciar sesión o pueden generar una solicitud a Autorizar punto de conexión que los redirija de forma silenciosa a la página de inicio de sesión de su proveedor de identidad. No puede iniciar sesión con los usuarios federados con los grupos de usuarios de Amazon Cognito. API

Orígenes de los desencadenadores de usuarios federados
Evento de inicio de sesión Disparador de Lambda Origen del disparador
Primer inicio de sesión Anterior a la inscripción

PreSignUp_ExternalProvider

Posterior a la confirmación

PostConfirmation_ConfirmSignUp

Anterior a la generación del token

TokenGeneration_HostedAuth

Inicios de sesión posteriores Anterior a la autenticación

PreAuthentication_Authentication

Posterior a la autenticación

PostAuthentication_Authentication

Anterior a la generación del token

TokenGeneration_HostedAuth

El inicio de sesión federado no llama a ningún Desencadenadores de Lambda de desafío de autenticación personalizado, Migración del desencadenador de Lambda del usuario, Desencadenador de Lambda para mensajes personalizados o Desencadenadores de Lambda para remitentes personalizados en el grupo de usuarios.

Conexión de disparadores de Lambda a las operaciones funcionales del grupo de usuarios

Cada disparador de Lambda cumple un rol funcional en su grupo de usuarios. Por ejemplo, un disparador puede modificar su flujo de registro o añadir un desafío de autenticación personalizado. El evento que Amazon Cognito envía a una función de Lambda puede reflejar una de las múltiples acciones que componen ese rol funcional. Por ejemplo, Amazon Cognito invoca un disparador previo al registro cuando el usuario se registra y cuando crea un usuario. Cada uno de estos casos para el mismo rol funcional tiene su propio valor de triggerSource. La función de Lambda puede procesar los eventos entrantes de forma diferente según la operación que la haya invocado.

Amazon Cognito también invoca todas las funciones asignadas cuando un evento se corresponde con el origen de un disparador. Por ejemplo, cuando un usuario inicia sesión en un grupo de usuarios al que ha asignado los disparadores de migración de usuario y autenticación previa, activa ambos.

Disparadores de inscripción, confirmación e inicio de sesión (autenticación)
Desencadenador triggerSource valor Evento
Anterior a la inscripción PreSignUp_SignUp Anterior a la inscripción.
Anterior a la inscripción PreSignUp_AdminCreateUser Anterior a la inscripción cuando un administrador crea un nuevo usuario.
Anterior a la inscripción PreSignUp_ExternalProvider Prerregistro para proveedores de identidad externos.
Posterior a la confirmación PostConfirmation_ConfirmSignUp Posterior a la confirmación de la inscripción.
Posterior a la confirmación PostConfirmation_ConfirmForgotPassword Posterior a la confirmación de la contraseña olvidada.
Anterior a la autenticación PreAuthentication_Authentication Anterior a la autenticación.
Posterior a la autenticación PostAuthentication_Authentication Posterior a la autenticación.
Disparadores de desafío de autenticación personalizados
Desencadenador triggerSource valor Evento
Definición de desafíos de autenticación DefineAuthChallenge_Authentication Definición de desafíos de autenticación.
Creación de desafíos de autenticación CreateAuthChallenge_Authentication Creación de desafíos de autenticación.
Verificación de desafío de autenticación VerifyAuthChallengeResponse_Authentication Verificación de la respuesta a los desafíos de autenticación.
Disparadores anteriores a la generación del token
Desencadenador triggerSource valor Evento
Anterior a la generación del token TokenGeneration_HostedAuth Amazon Cognito autentica el usuario desde su página de inicio de sesión de la IU alojada.
Anterior a la generación del token TokenGeneration_Authentication Flujos de autenticación de usuarios completos.
Anterior a la generación del token TokenGeneration_NewPasswordChallenge El administrador crea el usuario. Amazon Cognito lo llama cuando el usuario debe cambiar una contraseña temporal.
Anterior a la generación del token TokenGeneration_AuthenticateDevice Fin de la autenticación de un dispositivo de usuario.
Anterior a la generación del token TokenGeneration_RefreshTokens Un usuario intenta actualizar los tokens de identidad y acceso.
Disparadores de migración de usuarios
Desencadenador triggerSource valor Evento
Migración de usuario UserMigration_Authentication Migración de usuarios durante el inicio de sesión.
Migración de usuario UserMigration_ForgotPassword Migración de usuarios durante el flujo de recuperación de contraseñas olvidadas.
Disparadores de mensaje personalizado
Desencadenador triggerSource valor Evento
Mensaje personalizado CustomMessage_SignUp Mensaje personalizado cuando un usuario se registra en el grupo de usuarios.
Mensaje personalizado CustomMessage_AdminCreateUser Mensaje personalizado al crear un usuario como administrador y Amazon Cognito le envía una contraseña temporal.
Mensaje personalizado CustomMessage_ResendCode Mensaje personalizado cuando el usuario actual solicita un nuevo código de confirmación.
Mensaje personalizado CustomMessage_ForgotPassword Mensaje personalizado cuando el usuario solicita un restablecimiento de contraseña.
Mensaje personalizado CustomMessage_UpdateUserAttribute Mensaje personalizado cuando un usuario cambia su dirección de correo electrónico o número de teléfono y Amazon Cognito envía un código de verificación.
Mensaje personalizado CustomMessage_VerifyUserAttribute Mensaje personalizado cuando un usuario agrega una dirección de correo electrónico o un número de teléfono y Amazon Cognito envía un código de verificación.
Mensaje personalizado CustomMessage_Authentication Mensaje personalizado cuando un usuario que lo ha configurado SMS MFA inicia sesión.