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

Amazon Cognito trabaja con funciones de AWS Lambda 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 de su flujo de autenticación, realizar solicitudes a la API para modificar su grupo de usuarios u otros recursos de AWS 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 retos de autenticación, migrar usuarios entre su grupo de usuarios y otro almacén de identidades, personalizar mensajes y modificar tokens web JSON (JWT).

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. El usuario también puede realizar operaciones en tiempo de ejecución en su entorno de AWS, API externas, 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 evento de JSON y lo pasa a la 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. Un evento devuelto sin modificar notifica a su grupo de usuarios que debe continuar con la acción predeterminada para el evento. Por ejemplo, el desencadenador Antes del registro puede confirmar automáticamente a los usuarios para el origen del desencadenador PreSignUp_SignUp, pero devolver el evento sin cambios en el caso de los usuarios externos y creados por el administrador.

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

Conceptos importantes sobre los desencadenadores de Lambda

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

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

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. Si la función devuelve el evento de entrada sin modificarlo, Amazon Cognito procederá con el comportamiento predeterminado. A continuación, se muestran los parámetros que son comunes a todos los eventos de entrada del desencadenador de Lambda. Para conocer la sintaxis de los eventos específicos de cada desencadenador, consulte el esquema de eventos de la sección de esta guía para cada desencadenador.

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

Metadatos del cliente

Puede enviar parámetros personalizados a sus funciones de desencadenación de Lambda en las operaciones API y las solicitudes Punto de conexión de token. Con los metadatos del cliente, su aplicación puede recopilar información adicional sobre el entorno en el que se originan las solicitudes. Al pasar los metadatos del cliente a las funciones de Lambda, estas pueden procesar los datos adicionales y utilizarlos para registrar o personalizar los flujos de autenticación. Los metadatos del cliente son pares de cadenas que usted elige y diseña en formato clave-valor JSON.

Este es un ejemplo de cómo pasar los metadatos del cliente al desencadenador Antes del registro.

SignUp request

A continuación, tiene un ejemplo de solicitud SignUp con metadatos de cliente que Amazon Cognito transfiere a un desencadenador Antes del registro.

POST HTTP/1.1
Host: cognito-idp.us-east-1.amazonaws.com
X-Amz-Date: 20230613T200059Z
Accept-Encoding: gzip, deflate, br
X-Amz-Target: AWSCognitoIdentityProviderService.SignUp
User-Agent: <UserAgentString>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>

{
    "ClientId": "1example23456789",
    "Username": "mary_major",
    "Password": "<Password>",
    "SecretHash": "<Secret hash>",
    "ClientMetadata": { 
        "IpAddress" : "192.0.2.252",
        "GeoLocation" : "Netherlands (Kingdom of the) [NL]"
    }
    "UserAttributes": [
        {
            "Name": "name",
            "Value": "Mary"
        },
        {
            "Name": "email",
            "Value": "mary_major@example.com"
        },
        {
            "Name": "phone_number",
            "Value": "+12065551212"
        }
    ],
}

Lambda trigger input event

La solicitud da como resultado el siguiente cuerpo de solicitud para su función Antes del registro.

{
    "callerContext": {
        "awsSdkVersion": "aws-sdk-unknown-unknown",
        "clientId": "1example23456789"
    },
    "region": "us-west-2",
    "request": {
        "clientMetadata": {
            "GeoLocation": "Netherlands (Kingdom of the) [NL]",
            "IpAddress": "192.0.2.252"
        },
        "userAttributes": {
            "email": "mary_major@example.com",
            "name": "Mary",
            "phone_number": "+12065551212"
        },
        "validationData": null
    },
    "response": {
        "autoConfirmUser": false,
        "autoVerifyEmail": false,
        "autoVerifyPhone": false
    },
    "triggerSource": "PreSignUp_SignUp",
    "userName": "mary_major2",
    "userPoolId": "us-west-2_EXAMPLE",
    "version": "1"
}

Metadatos del cliente para credenciales de cliente máquina a máquina (M2M)

Puede pasar los metadatos del cliente en las solicitudes M2M. Los metadatos del cliente son información adicional de un entorno de usuario o aplicación que puede contribuir a los resultados de una Desencadenador de Lambda de pregeneración de tokens.. En las operaciones de autenticación con una entidad principal de usuario, puede pasar los metadatos del cliente al desencadenador Antes de la generación del token en el cuerpo de las solicitudes de API AdminRespondToAuthChallenge y RespondToAuthChallenge. Dado que las aplicaciones dirigen el flujo de generación de tokens de acceso para M2M con solicitudes directas al Punto de conexión de token, tienen un modelo diferente. En el cuerpo POST de las solicitudes de token para las credenciales de los clientes, pase un parámetro aws_client_metadata con el objeto de metadatos del cliente codificado en la URL (x-www-form-urlencoded) a cadena. Para obtener una solicitud de ejemplo, consulte Credenciales de cliente con autorización básica. A continuación, puede ver un ejemplo de parámetro que transfiere los pares clave-valor {"environment": "dev", "language": "en-US"}.

aws_client_metadata=%7B%22environment%22%3A%20%22dev%22,%20%22language%22%3A%20%22en-US%22%7D

Atributos de usuario temporales: validationData

Algunas operaciones de autenticación también tienen un parámetro validationData. Al igual que los metadatos de los clientes, esta es una oportunidad para pasar información externa que Amazon Cognito no recopila automáticamente a los desencadenadores de Lambda. El campo de datos de validación está diseñado para proporcionar a la función de Lambda un contexto de usuario adicional en las operaciones de registro e inicio de sesión. SignUp y AdminCreateUser pasan validationData al desencadenador Antes del registro. InitiateAuth y AdminInitiateAuth pasan ClientMetadata en el cuerpo de la solicitud de la API como validationData en el evento de entrada a los desencadenadores Antes de la autenticación y Migrar usuario.

Para asignar las operaciones de la API a las funciones a las que pueden pasar los metadatos del cliente, consulte las secciones sobre los orígenes de activación que aparecen a continuación.

Conexión de las operaciones de la API a los disparadores de 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 la aplicación inicia la sesión de los usuarios a través de la API de los grupos de usuarios, el inicio de sesión administrado o los puntos de conexión de 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 la API de los grupos de usuarios de Amazon Cognito y los puntos de conexión del grupo de usuarios, consulte Descripción de la autenticación mediante API, OIDC y páginas de inicio de sesión administrado. 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.

Disparadores de Lambda en la API de Amazon Cognito

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.

Desencadenadores de Lambda para los usuarios locales de Amazon Cognito en el inicio de sesión administrado

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

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.

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.