Desencadenador de Lambda de pregeneración de tokens.

Dado que Amazon Cognito invoca este desencadenador antes de que se genere el token, puede personalizar las notificaciones de los tokens del grupo de usuarios. Con las Características básicas de la versión dos o del evento desencadenante previo a la generación del token V1_0, puede personalizar el token de identidad (ID). En los grupos de usuarios con el plan de características Essentials o Plus, puede generar la versión dos o el evento desencadenante V2_0 con la personalización del token de acceso y la versión tres o el evento desencadenante V3_0 con la personalización del token de acceso para la concesión de credenciales en el cliente de máquina a máquina (M2M).

Amazon Cognito envía un evento V1_0 como una solicitud a la función con datos que escribiría en el token de ID. Un evento V2_0 o V3_0 es una solicitud única con los datos que Amazon Cognito escribiría en los tokens tanto de identidad y de acceso. Para personalizar ambos tokens, debe actualizar la función para usar la versión dos o tres del desencadenador y enviar los datos de ambos tokens en la misma respuesta.

Amazon Cognito aplica las respuestas a eventos de la versión dos a los tokens de acceso de la autenticación de usuario, en la que un usuario humano ha presentado las credenciales a su grupo de usuarios. Las respuestas a los eventos de la versión tres se aplican a los tokens de acceso procedentes de la autenticación de usuario y de la autenticación automática, en la que los sistemas automatizados autorizan las solicitudes de token de acceso con los secretos del cliente de la aplicación. Aparte de las circunstancias de los tokens de acceso resultantes, los eventos de las versiones dos y tres son idénticos.

Este desencadenador Lambda puede añadir, eliminar y modificar algunas notificaciones en los tokens de identidad y acceso antes de que Amazon Cognito las envíe a su aplicación. Para utilizar esta característica, asocie una función de Lambda desde la consola del grupos de usuarios de Amazon Cognito o actualice su grupo de usuarios LambdaConfig a través de la (AWS Command Line Interface)AWS CLI.

Versiones de eventos

Su grupo de usuarios puede entregar a su función de Lambda diferentes versiones de un evento desencadenante anterior a la generación del token. Un desencadenador V1_0 proporciona los parámetros de modificación de los tokens de ID. Un desencadenador V2_0 o V3_0 proporciona parámetros para lo siguiente.

Los grupos de usuarios proporcionan de forma predeterminada eventos para V1_0. A fin de configurar el grupo de usuarios para enviar un evento de V2_0, elija la opción Versión del evento desencadenador en Características básicas + personalización del token de acceso para identidades de usuario al configurar el desencadenador en la consola de Amazon Cognito. Para producir eventos V3_0, elija Características básicas + personalización del token de acceso para las identidades de usuario y máquina. También puede establecer el valor de LambdaVersion en los parámetros de LambdaConfig en una solicitud de API UpdateUserPool o CreateUserPool. Las versiones uno, dos y tres de los eventos están disponibles en los planes de características Essentials y Plus. Las operaciones M2M para los eventos de la tercera versión tienen una estructura de precios independiente de la fórmula de usuarios activos mensuales (MAU). Para obtener más información, consulte Precios de Amazon Cognito.

Referencia sobre reclamaciones y ámbitos

Amazon Cognito limita las reclamaciones y los ámbitos que puede agregar, modificar o suprimir en los tokens de acceso e identidad. En la siguiente tabla, se describen las notificaciones que la función de Lambda puede y no puede modificar, así como los parámetros del evento desencadenador que afectan a la presencia o al valor de la notificación.

¹ Los tokens de acceso para las identidades de las máquinas solo están disponibles con la versión v3_0 del evento de entrada del desencadenador. La versión tres solo está disponible en los niveles de características Essentials y Plus. Los grupos de usuarios del nivel Lite pueden recibir eventos v1_0. Los grupos de usuarios del nivel Lite con características de seguridad avanzadas pueden recibir eventos v1_0 y v2_0.

² Configure su desencadenador Antes de la generación del token en la versión de eventos v1_0 solo para el token de ID, en la versión v2_0 para el token de acceso e ID y en la versión v3_0 para el token de acceso e ID con capacidades para las identidades de máquinas.

³ Para suprimir las reclamaciones cognito:preferred_role y cognito:roles, añada cognito:groups a claimsToSuppress.

⁴ Puede agregar una reclamación de aud para acceder a los tokens, pero el valor debe coincidir con el ID de cliente de aplicación de la sesión actual. Puede derivar el ID de cliente en el evento de solicitud de event.callerContext.clientId.

Personalización del token de identidad

En todas las versiones de eventos del desencadenador de Lambda Antes de la generación del token, puede personalizar el contenido de un token de identidad (ID) desde su grupo de usuarios. El token de ID proporciona los atributos de usuario de un origen de identidades fiable para iniciar sesión en una aplicación web o móvil. Para obtener más información acerca de los tokens de ID, consulte Descripción del token de identidad (ID).

Los usos del desencadenador de Lambda previo a la generación de tokens con un token de ID incluyen los siguientes.

Personalización del token de acceso

En las versiones de eventos dos y tres del desencadenador de Lambda Antes de la generación del token, puede personalizar el contenido de un token de acceso desde su grupo de usuarios. El token de acceso autoriza a los usuarios a recuperar información de recursos de acceso protegido, como las operaciones de API autorizadas por el token de Amazon Cognito y las API de terceros. Para la autorización de máquina a máquina (M2M) con una concesión de credenciales de cliente, Amazon Cognito solo invoca al desencadenador Antes de la generación del token cuando el grupo de usuarios está configurado para un evento de versión tres (V3_0). Para obtener más información acerca de los tokens de acceso, consulte Descripción del token de acceso.

Los usos del desencadenador de Lambda previo a la generación de tokens con un token de acceso incluyen los siguientes.

Para poder personalizar el acceso al grupo de usuarios, debe configurar el grupo de usuarios para que genere una versión actualizada de la solicitud de desencadenador. Actualice el grupo de usuarios como se muestra en el siguiente procedimiento.

Consola de administración de AWS

Para admitir la personalización del token de acceso en un desencadenador de Lambda previo a la generación de tokens

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

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

3. Seleccione el menú Extensiones y localice los desencadenadores de Lambda.

4. Agregue o edite un desencadenador previo a la generación de tokens.

5. Elija una función de Lambda en Asignar función de Lambda.

6. Elija una versión de evento desencadenador Características básicas + personalización de token de acceso para identidades de usuario o Características básicas + personalización de token de acceso para identidades de usuario y máquina. 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.

User pools API

Para admitir la personalización del token de acceso en un desencadenador de Lambda previo a la generación de tokens

Genere una solicitud de la API CreateUserPool o UpdateUserPool. Debe especificar un valor para todos los parámetros que no desee establecer en un valor predeterminado. Para obtener más información, consulte Actualización de la configuración del grupo de usuarios y del cliente de aplicación.

Incluya el siguiente contenido en el parámetro LambdaVersion de la solicitud. El valor V2_0 en LambdaVersion hace que el grupo de usuarios agregue parámetros para los tokens de acceso y que aplique los cambios en estos. El valor V3_0 en LambdaVersion produce el mismo evento que V2_0, pero hace que su grupo de usuarios también aplique cambios a los tokens de acceso M2M. Para invocar una versión de función específica, utilice el ARN de una función de Lambda con una versión de función como el valor de LambdaArn.

"PreTokenGenerationConfig": { 
   "LambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:MyFunction",
   "LambdaVersion": "V3_0"
},

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

Fuentes del desencadenador de Lambda de pregeneración de tokens

Parámetros del desencadenador de Lambda de pregeneración de tokens

La solicitud que Amazon Cognito envía a esta función de Lambda es una combinación de los parámetros que se indican a continuación y los parámetros comunes que Amazon Cognito agrega a todas las solicitudes. Al agregar un desencadenador de Lambda previo a la generación de tokens al grupo de usuarios, puede elegir una versión de desencadenador. Esta versión determina si Amazon Cognito transfiere una solicitud a la función de Lambda con parámetros adicionales para la personalización del token de acceso.

Version one

El token de la versión uno puede establecer la pertenencia a grupos, los roles de IAM y las nuevas notificaciones en los tokens de ID. La anulación de la pertenencia a un grupo también se aplica a la reclamación cognito:groups de los tokens de acceso.

{
    "request": {
        "userAttributes": {"string": "string"},
        "groupConfiguration": {
                "groupsToOverride": [
                    "string",
                    "string"
                ],
                "iamRolesToOverride": [
                    "string",
                    "string"
                ],
                "preferredRole": "string"
        },
        "clientMetadata": {"string": "string"}
    },
    "response": {
        "claimsOverrideDetails": {
            "claimsToAddOrOverride": {"string": "string"},
            "claimsToSuppress": [
                "string",
                "string"
            ],
            "groupOverrideDetails": {
                "groupsToOverride": [
                    "string",
                    "string"
                ],
                "iamRolesToOverride": [
                    "string",
                    "string"
                ],
                "preferredRole": "string"
            }
        }
    }
}

Versions two and three

Las versiones dos y tres solicitan eventos que añaden campos que personalizan el token de acceso. Los grupos de usuarios aplican los cambios de los eventos de la tercera versión a los tokens de acceso para las identidades de las máquinas. Estas versiones también añaden compatibilidad con tipos de datos claimsToOverride complejos en el objeto de respuesta. La función de Lambda puede devolver los siguientes tipos de datos con el valor de claimsToOverride:

• Cadena

• Número

• Booleano

• Matriz de cadenas, números, valores booleanos o una combinación de cualquiera de ellos

• JSON

{
    "request": {
        "userAttributes": {
            "string": "string"
        },
        "scopes": ["string", "string"],
        "groupConfiguration": {
            "groupsToOverride": ["string", "string"],
            "iamRolesToOverride": ["string", "string"],
            "preferredRole": "string"
        },
        "clientMetadata": {
            "string": "string"
        }
    },
    "response": {
        "claimsAndScopeOverrideDetails": {
            "idTokenGeneration": {
                "claimsToAddOrOverride": {
                    "string": [accepted datatype]
                },
                "claimsToSuppress": ["string", "string"]
            },
            "accessTokenGeneration": {
                "claimsToAddOrOverride": {
                    "string": [accepted datatype]
                },
                "claimsToSuppress": ["string", "string"],
                "scopesToAdd": ["string", "string"],
                "scopesToSuppress": ["string", "string"]
            },
            "groupOverrideDetails": {
                "groupsToOverride": ["string", "string"],
                "iamRolesToOverride": ["string", "string"],
                "preferredRole": "string"
            }
        }
    }
}

Parámetros de la solicitud anterior a la generación del token

Parámetros de la respuesta anterior a la generación del token

^* Los objetos de respuesta a los eventos de la versión uno pueden devolver cadenas. Los objetos de respuesta a los eventos de la versión dos y tres pueden devolver objetos complejos.

Ejemplo de la segunda versión de un evento desencadenante previo al token: añadir y suprimir notificaciones, ámbitos y grupos

En este ejemplo, se realizan las siguientes modificaciones a los tokens de un usuario.

JavaScript

export const handler = function(event, context) {
  event.response = {
    "claimsAndScopeOverrideDetails": {
      "idTokenGeneration": {
        "claimsToAddOrOverride": {
          "family_name": "Doe"
        },
        "claimsToSuppress": [
          "email",
          "phone_number"
        ]
      },
      "accessTokenGeneration": {
        "scopesToAdd": [
          "openid",
          "email",
          "solar-system-data/asteroids.add"
        ],
        "scopesToSuppress": [
          "phone_number",
          "aws.cognito.signin.user.admin"
        ]
      },
      "groupOverrideDetails": {
        "groupsToOverride": [
          "new-group-A",
          "new-group-B",
          "new-group-C"
        ],
        "iamRolesToOverride": [
          "arn:aws:iam::123456789012:role/new_roleA",
          "arn:aws:iam::123456789012:role/new_roleB",
          "arn:aws:iam::123456789012:role/new_roleC"
        ],
        "preferredRole": "arn:aws:iam::123456789012:role/new_role",
      }
    }
  };
  // Return to Amazon Cognito
  context.done(null, event);
};

Amazon Cognito transfiere la información del evento a la función de Lambda. A continuación, la función devuelve el mismo objeto de evento a Amazon Cognito con los cambios en la respuesta. En la consola de Lambda puede configurar un evento de prueba con los datos relevantes para el desencadenador de Lambda. El siguiente es un evento de prueba para este código de ejemplo:

JSON

{
    "version": "2",
    "triggerSource": "TokenGeneration_Authentication",
    "region": "us-east-1",
    "userPoolId": "us-east-1_EXAMPLE",
    "userName": "JaneDoe",
    "callerContext": {
        "awsSdkVersion": "aws-sdk-unknown-unknown",
        "clientId": "1example23456789"
    },
    "request": {
        "userAttributes": {
            "sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "cognito:user_status": "CONFIRMED",
            "email_verified": "true",
            "phone_number_verified": "true",
            "phone_number": "+12065551212",
            "family_name": "Zoe",
            "email": "Jane.Doe@example.com"
        },
        "groupConfiguration": {
            "groupsToOverride": ["group-1", "group-2", "group-3"],
            "iamRolesToOverride": ["arn:aws:iam::123456789012:role/sns_caller1", "arn:aws:iam::123456789012:role/sns_caller2", "arn:aws:iam::123456789012:role/sns_caller3"],
            "preferredRole": ["arn:aws:iam::123456789012:role/sns_caller"]
        },
        "scopes": [
            "aws.cognito.signin.user.admin", "openid", "email", "phone"
        ]
    },
    "response": {
        "claimsAndScopeOverrideDetails": []
    }
}

Ejemplo de la versión dos de evento de generación anterior al token: añadir notificaciones con objetos complejos

En este ejemplo, se realizan las siguientes modificaciones a los tokens de un usuario.

JavaScript

export const handler = function(event, context) {

    var scopes = ["MyAPI.read", "MyAPI.write", "MyAPI.admin"]
    var claims = {}
    claims["aud"]= event.callerContext.clientId;
    claims["booleanTest"] = false;
    claims["longTest"] = 9223372036854775807;
    claims["exponentTest"] = 1.7976931348623157E308;
    claims["ArrayTest"] = ["test", 9223372036854775807, 1.7976931348623157E308, true];
    claims["longStringTest"] = "\{\
        \"first_json_block\": \{\
            \"key_A\": \"value_A\",\
            \"key_B\": \"value_B\"\
        \},\
        \"second_json_block\": \{\
            \"key_C\": \{\
                \"subkey_D\": [\
                    \"value_D\",\
                    \"value_E\"\
                ],\
                \"subkey_F\": \"value_F\"\
            \},\
            \"key_G\": \"value_G\"\
        \}\
    \}";
    claims["jsonTest"] = {
    	"first_json_block": {
    		"key_A": "value_A",
    		"key_B": "value_B"
    	},
    	"second_json_block": {
    		"key_C": {
    			"subkey_D": [
    				"value_D",
    				"value_E"
    			],
    			"subkey_F": "value_F"
    		},
    		"key_G": "value_G"
    	}
    };
    event.response = {
        "claimsAndScopeOverrideDetails": {
            "idTokenGeneration": {
                "claimsToAddOrOverride": claims,
                "claimsToSuppress": ["email"]
            },
            "accessTokenGeneration": {
                "claimsToAddOrOverride": claims,
                "claimsToSuppress": ["email"],
                "scopesToAdd": scopes,
                "scopesToSuppress": ["aws.cognito.signin.user.admin"]
            }
        }
    };
    console.info("EVENT response\n" + JSON.stringify(event, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2))
    console.info("EVENT response size\n" + JSON.stringify(event, (_, v) => typeof v === 'bigint' ? v.toString() : v).length)
    // Return to Amazon Cognito
    context.done(null, event);
};

Amazon Cognito transfiere la información del evento a la función de Lambda. A continuación, la función devuelve el mismo objeto de evento a Amazon Cognito con los cambios en la respuesta. En la consola de Lambda puede configurar un evento de prueba con los datos relevantes para el desencadenador de Lambda. El siguiente es un evento de prueba para este código de ejemplo:

JSON

{
    "version": "2",
    "triggerSource": "TokenGeneration_HostedAuth",
    "region": "us-west-2",
    "userPoolId": "us-west-2_EXAMPLE",
    "userName": "JaneDoe",
    "callerContext": {
        "awsSdkVersion": "aws-sdk-unknown-unknown",
        "clientId": "1example23456789"
    },
    "request": {
        "userAttributes": {
            "sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "cognito:user_status": "CONFIRMED"
            "email_verified": "true",
            "phone_number_verified": "true",
            "phone_number": "+12065551212",
            "email": "Jane.Doe@example.com"
        },
        "groupConfiguration": {
            "groupsToOverride": ["group-1", "group-2", "group-3"],
            "iamRolesToOverride": ["arn:aws:iam::123456789012:role/sns_caller1"],
            "preferredRole": ["arn:aws:iam::123456789012:role/sns_caller1"]
        },
        "scopes": [
            "aws.cognito.signin.user.admin",
            "phone",
            "openid",
            "profile",
            "email"
        ]
    },
    "response": {
        "claimsAndScopeOverrideDetails": []
    }
}

Ejemplo uno de versión de evento de generación anterior al token: Agregar una notificación nueva y suprimir otra existente

En este ejemplo, se utiliza el evento de desencadenador versión 1 con una función de Lambda anterior a la generación del token para agregar una reclamación nueva y suprimir una existente.

Node.js

const handler = async (event) => {
  event.response = {
    claimsOverrideDetails: {
      claimsToAddOrOverride: {
        my_first_attribute: "first_value",
        my_second_attribute: "second_value",
      },
      claimsToSuppress: ["email"],
    },
  };

  return event;
};

export { handler };

Amazon Cognito transfiere la información del evento a la función de Lambda. A continuación, la función devuelve el mismo objeto de evento a Amazon Cognito con los cambios en la respuesta. En la consola de Lambda puede configurar un evento de prueba con los datos relevantes para el desencadenador de Lambda. El siguiente es un evento de prueba para este código de ejemplo: puesto que el ejemplo de código no procesa ningún parámetro de solicitud, puede utilizar un evento de prueba con una solicitud vacía. Para obtener más información sobre los parámetros de solicitud habituales, consulte Evento desencadenador de Lambda para un grupo de usuarios.

JSON

{
  "request": {},
  "response": {}
}

Ejemplo uno de versión de evento de generación anterior al token: Modificar la pertenencia de un usuario a un grupo

En este ejemplo, se utiliza el evento de desencadenador versión 1 con una función de Lambda anterior a la generación del token para modificar la suscripción de un grupo de usuarios.

Node.js

const handler = async (event) => {
  event.response = {
    claimsOverrideDetails: {
      groupOverrideDetails: {
        groupsToOverride: ["group-A", "group-B", "group-C"],
        iamRolesToOverride: [
          "arn:aws:iam::XXXXXXXXXXXX:role/sns_callerA",
          "arn:aws:iam::XXXXXXXXX:role/sns_callerB",
          "arn:aws:iam::XXXXXXXXXX:role/sns_callerC",
        ],
        preferredRole: "arn:aws:iam::XXXXXXXXXXX:role/sns_caller",
      },
    },
  };

  return event;
};

export { handler };

Amazon Cognito transfiere la información del evento a la función de Lambda. A continuación, la función devuelve el mismo objeto de evento a Amazon Cognito con los cambios en la respuesta. En la consola de Lambda puede configurar un evento de prueba con los datos relevantes para el desencadenador de Lambda. El siguiente es un evento de prueba para este código de ejemplo:

JSON

{
  "request": {},
  "response": {}
}