Versiones de eventos Reclamaciones y ámbitos excluidos Personalización del token de identidad Personalización del token de acceso Fuentes del desencadenador de Lambda de pregeneración de tokens Parámetros del desencadenador de Lambda de pregeneración de tokens Ejemplo de la segunda versión de un evento desencadenante previo al token: añadir y suprimir notificaciones, ámbitos y grupos Ejemplo de la segunda versión del evento previo a la generación de fichas: añadir reclamaciones con objetos complejos Ejemplo uno de versión de evento de generación anterior al token: Agregar una notificación nueva y suprimir otra existente Ejemplo uno de versión de evento de generación anterior al token: Modificar la pertenencia de un usuario a un grupo

Desencadenador de Lambda anterior a la generación del token

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 características de seguridad avanzadas activas, puede generar la versión 2 o evento desencadenante V2_0 con la personalización del token de acceso.

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 es una solicitud única con los datos que Amazon Cognito escribiría en los tokens tanto de de identidad como de acceso. Para personalizar ambos tokens, debe actualizar la función para usar la versión del desencadenador más reciente y enviar los datos de ambos tokens en la misma respuesta.

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 diferentes versiones de un evento desencadenante previo a la generación del token a su función Lambda. Un V1_0 disparador proporciona los parámetros para la modificación de los tokens de identificación. Un V2_0 disparador proporciona los parámetros siguientes.

Las funciones de un V1_0 disparador.
La posibilidad de personalizar los tokens de acceso.
La capacidad de transferir tipos de datos complejos a los valores declarados de los identificadores y los identificadores de acceso:
- Cadena
- Número
- Booleano
- Matriz de cadenas, números, valores booleanos o una combinación de cualquiera de estos
- JSON

nota

En el token de identificación, puede rellenar objetos complejos con los valores de las reclamacionesphone_number_verified, excepto,email_verified, updated_at y. address

Los grupos de usuarios proporcionan V1_0 eventos de forma predeterminada. Para configurar su grupo de usuarios para enviar un V2_0 evento, elija una versión de evento desencadenante de Funciones básicas y personalización del token de acceso al configurar el activador en la consola de Amazon Cognito. También puede establecer el valor de LambdaVersion en los LambdaConfigparámetros de una solicitud UpdateUserPool o de CreateUserPool API. Se aplican costes adicionales a la personalización de los tokens de acceso con V2_0 los eventos. Para obtener más información, consulte Precios de Amazon Cognito.

Reclamaciones y ámbitos excluidos

Amazon Cognito limita las reclamaciones y los ámbitos que puede agregar, modificar o suprimir en los tokens de acceso e identidad. Si la función de Lambda intenta establecer un valor para cualquiera de estas afirmaciones, Amazon Cognito emite un token con el valor de la reclamación original, si había alguno en la solicitud.

Reclamaciones compartidas

acr
amr
at_hash
auth_time
azp
exp
iat
iss
jti
nbf
nonce
origin_jti
sub
token_use

Reclamaciones del token del ID

identities
aud
cognito:username

Reclamaciones del token de acceso

username
client_id
scope

nota
Puede cambiar los alcances de un token de acceso con scopesToAdd y los valores de respuesta scopesToSuppress, pero no puede modificar la reclamación de scope directamente. No puede agregar ámbitos que comiencen por aws.cognito, como el ámbito reservado del grupo de usuarios aws.cognito.signin.user.admin.
device_key
event_id
version

No puede agregar ni invalidar reclamaciones con los siguientes prefijos, pero puede suprimirlas o impedir que aparezcan en el token.

dev:
cognito:

Puede agregar una reclamación de aud para acceder a los tokens, pero el valor debe coincidir con el ID de cliente de la 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

Con el desencadenador de Lambda previo a la generación de tokens, puede personalizar el contenido de un token de identidad (ID) del 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 Uso del token de ID.

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

Realice un cambio en el tiempo de ejecución en el rol de IAM que el usuario solicita de un grupo de identidades.
Agregue atributos de usuario desde un origen externo.
Agregue o sustituya los valores de los atributos de usuario existentes.
Suprima la divulgación de los atributos de usuario que, debido a los ámbitos autorizados del usuario y al acceso de lectura a los atributos que ha concedido al cliente de la aplicación, se transferirían a la aplicación.

Personalización del token de acceso

Con el desencadenador de Lambda previo a la generación de tokens, puede personalizar el contenido de un token de acceso del 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. Si bien puede generar tokens de acceso para la autorización machine-to-machine (M2M) con Amazon Cognito con una concesión de credenciales de cliente, las solicitudes M2M no invocan la función de activación previa a la generación del token y no pueden emitir tokens de acceso personalizados. Para obtener más información acerca de los tokens de acceso, consulte Uso 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.

Agregue o suprima los ámbitos de OAuth 2.0 en la reclamación de scope. Por ejemplo, puede agregar ámbitos a un token de acceso resultante de la autenticación de la API de grupos de usuarios de Amazon Cognito, que solo asigna el ámbito aws.cognito.signin.user.admin.
Cambie la suscripción de un usuario en los grupos de usuarios.
Agregue notificaciones que aún no estén presentes en un token de acceso de Amazon Cognito.
Suprima la divulgación de las reclamaciones que, de otro modo, se transferirían a la aplicación.

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.

AWS Management Console

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

Diríjase a la consola de Amazon Cognito y luego elija User Pools (Grupos de usuarios).
Elija un grupo de usuarios existente en la lista o cree un grupo de usuarios.
Si aún no lo ha hecho, active las características de seguridad avanzadas desde la pestaña Integración de la aplicación.
Elija la pestaña User pool properties (Propiedades del grupo de usuarios) y localice Lambda triggers (Desencadenadores Lambda).
Agregue o edite un desencadenador previo a la generación de tokens.
Elija una función de Lambda en Asignar función de Lambda.
Elija una Versión del evento del desencadenador de las Características básicas y personalización del token de acceso. 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 CreateUserPoolsolicitud de API o API. 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.

Incluya el siguiente contenido en el parámetro LambdaVersion de la solicitud. Un valor LambdaVersion de V2_0 hace que el grupo de usuarios agregue parámetros para la personalización del token de acceso. 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": "V2_0"
},

Más recursos

Cómo personalizar los tokens de acceso en los grupos de usuarios de Amazon Cognito

Temas

Fuentes del desencadenador de Lambda de pregeneración de tokens
Parámetros del desencadenador de Lambda de pregeneración de tokens
Ejemplo de la segunda versión de un evento desencadenante previo al token: añadir y suprimir notificaciones, ámbitos y grupos
Ejemplo de la segunda versión del evento previo a la generación de fichas: añadir reclamaciones con objetos complejos
Ejemplo uno de versión de evento de generación anterior al token: Agregar una notificación nueva y suprimir otra existente
Ejemplo uno de versión de evento de generación anterior al token: Modificar la pertenencia de un usuario a un grupo

Fuentes del desencadenador de Lambda de pregeneración de tokens

Valor de triggerSource	Evento
`TokenGeneration_HostedAuth`	Se llama durante la autenticación desde la página de inicio de sesión de la IU alojada de Amazon Cognito.
`TokenGeneration_Authentication`	Se llama después de que se hayan completado los flujos de autenticación.
`TokenGeneration_NewPasswordChallenge`	Se llama después de que un administrador cree al usuario. Este flujo se invoca cuando el usuario tiene que cambiar una contraseña temporal.
`TokenGeneration_AuthenticateDevice`	Se llama al final de la autenticación de un dispositivo de usuario.
`TokenGeneration_RefreshTokens`	Se llama cuando un usuario intenta actualizar los tokens de identidad y acceso.

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 1

El token de la versión 1 puede establecer la pertenencia a grupos, las funciones de IAM y nuevos atributos en los tokens de identificación.


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

Version 2

El evento de solicitud de la versión 2 añade campos que personalizan el token de acceso. También añade compatibilidad con tipos de claimsToOverride datos complejos en el objeto de respuesta. La función 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 estos
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

Nombre	Descripción	Versión mínima del evento del desencadenador
userAttributes	Los atributos del perfil de usuario en el grupo de usuarios.	1
groupConfiguration	Objeto de entrada que contiene la configuración de grupo actual. El objeto incluye `groupsToOverride`, `iamRolesToOverride` y `preferredRole`.	1
groupsToOverride	Los grupos del grupo de usuarios de los que es miembro su usuario.	1
iamRolesToAnular	Puede asociar un grupo de grupos de usuarios a un rol AWS Identity and Access Management (IAM). Este elemento es una lista de todos los roles de IAM de los grupos a los que pertenece su usuario.	1
preferredRole	Puede establecer una prioridad para los grupos del grupo de usuarios. Este elemento contiene el nombre del rol de IAM del grupo con la mayor prioridad en el elemento `groupsToOverride`.	1
clientMetadata	Uno o varios pares clave-valor que puede especificar y proporcionar como datos de entrada personalizados a la función de Lambda para el desencadenador anterior a la generación del token. Para pasar estos datos a la función Lambda, utilice el ClientMetadata parámetro en las operaciones AdminRespondToAuthChallengey RespondToAuthChallengeAPI. Amazon Cognito no incluye datos del `ClientMetadata` parámetro ni de las operaciones de InitiateAuthAPI en AdminInitiateAuthla solicitud que transfiere a la función de generación previa del token.	1
alcances	Los ámbitos de OAuth 2.0 del usuario. Los ámbitos que están presentes en un token de acceso son los ámbitos estándar y personalizados del grupo de usuarios que el usuario ha solicitado y que usted ha autorizado emitir al cliente de la aplicación.	2

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

Nombre	Descripción	Versión mínima del evento del desencadenador
claimsOverrideDetails	Un contenedor para todos los elementos de un evento desencadenante `V1_0`.	1
claimsAndScopeOverrideDetails	Un contenedor para todos los elementos de un evento desencadenante `V2_0`.	2
idTokenGeneration	Las reclamaciones que desea invalidar, agregar o suprimir en el token del ID de usuario. Estos valores de personalización del token principal al ID aparecen solo en los eventos de la versión 2, pero los elementos secundarios aparecen en los eventos de la versión 1.	2
accessTokenGeneration	Las reclamaciones y ámbitos que desea invalidar, agregar o suprimir en el token de acceso del usuario. Este elemento principal para acceder a los valores de personalización del token solo aparece en los eventos de la versión 2.	2
claimsToAddOrOverride	Un mapa de una o más reclamaciones y los valores que desee agregar o modificar. Para las reclamaciones relacionadas con el grupo, utilice `groupOverrideDetails` en su lugar. En los eventos de la versión 2, este elemento aparece en `accessTokenGeneration` y `idTokenGeneration`.	1. ^*
claimsToSuppress	Una lista de reclamaciones que quiere que Amazon Cognito suprima. Si tu función suprime y reemplaza un valor de notificación, Amazon Cognito suprime la notificación. En los eventos de la versión 2, este elemento aparece en `accessTokenGeneration` y `idTokenGeneration`.	1
groupOverrideDetails	Objeto de salida que contiene la configuración de grupo actual. El objeto incluye `groupsToOverride`, `iamRolesToOverride` y `preferredRole`. La función sustituye el objeto `groupOverrideDetails` por el objeto que proporcione. Si proporciona un objeto vacío o nulo en la respuesta, entonces Amazon Cognito suprimirá los grupos. Para dejar la configuración de grupos existente tal como está, copie el valor del objeto `groupConfiguration` de la solicitud en el objeto `groupOverrideDetails` de la respuesta. Luego transfiéralo de nuevo al servicio. Los tokens de ID y de acceso de Amazon Cognito contienen la notificación `cognito:groups`. El objeto `groupOverrideDetails` sustituye la reclamación de `cognito:groups` en tokens de acceso y tokens de ID.	1
scopesToAdd	Una lista de ámbitos de OAuth 2.0 que quiere agregar a la reclamación de `scope` en el token de acceso del usuario. No puede agregar valores de ámbito que contengan uno o más caracteres de espacio en blanco.	2
scopesToSuppress	Una lista de ámbitos de OAuth 2.0 que quiere eliminar de la reclamación de `scope` en el token de acceso del usuario.	2

^* Los objetos de respuesta a los eventos de la versión 1 pueden devolver cadenas. Los objetos de respuesta a los eventos de la versión 2 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.

Establece su family_name como Doe en el token de ID.
Impide que las notificaciones email y phone_number aparezcan en el token de ID.
Establece su notificación cognito:roles de token de ID a "arn:aws:iam::123456789012:role\/sns_callerA","arn:aws:iam::123456789012:role\/sns_callerC","arn:aws:iam::123456789012:role\/sns_callerB".
Establece su notificación cognito:preferred_role de token de ID a arn:aws:iam::123456789012:role/sns_caller.
Añade los ámbitos openid, email y solar-system-data/asteroids.add al token de acceso.
Suprime el ámbito phone_number y aws.cognito.signin.user.admin del token de acceso. La eliminación de phone_number impide la recuperación del número de teléfono del usuario de userInfo. La eliminación de aws.cognito.signin.user.admin impide las solicitudes de la API por el usuario para leer y modificar su propio perfil con la API de grupos de usuarios de Amazon Cognito.

nota
La eliminación de phone_number de los ámbitos solo impide la recuperación del número de teléfono de un usuario si los ámbitos restantes del token de acceso incluyen openid y al menos un ámbito estándar más. Para obtener más información, consulte Acerca de los ámbitos.
Establece su ID y notificación cognito:groups de token de acceso en "new-group-A","new-group-B","new-group-C".

Ejemplo de la segunda versión del evento previo a la generación de fichas: añadir reclamaciones con objetos complejos

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

Agrega afirmaciones de los tipos numérico, de cadena, booleano y JSON al token de ID. Este es el único cambio que los eventos desencadenantes de la segunda versión ponen a disposición del token de ID.
Añade notificaciones de los tipos numérico, de cadena, booleano y JSON al token de acceso.
Agrega tres ámbitos al token de acceso.
Suprime los sub reclamos email y atributos en los identificadores de acceso y de identificación.
Suprime el aws.cognito.signin.user.admin alcance del token de acceso.

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","sub"]
            },
            "accessTokenGeneration": {
                "claimsToAddOrOverride": claims,
                "claimsToSuppress": ["email","sub"],
                "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);
};

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.

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.

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.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Desencadenador de Lambda para verificar la respuesta al desafío de autenticación.

Migración del desencadenador de Lambda del usuario