Activador Lambda de federación entrante - Amazon Cognito
Información general sobre flujosParametersEjemplo: pertenencia a un grupoEjemplo: truncar atributosEjemplo: registro de eventos

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.

Activador Lambda de federación entrante

El activador de federación entrante transforma los atributos de los usuarios federados durante el proceso de autenticación con proveedores de identidad externos. Cuando los usuarios se autentican a través de proveedores de identidad configurados, este disparador le permite modificar las respuestas de proveedores de SAML y OIDC externos al interceptar y transformar los datos en el proceso de autenticación, lo que proporciona un control programático sobre la forma en que los grupos de usuarios de Amazon Cognito gestionan los usuarios federados y sus atributos.

Utilice este activador para añadir, anular o suprimir atributos antes de crear nuevos usuarios o actualizar los perfiles de usuarios federados existentes. Este activador recibe los atributos sin procesar del proveedor de identidad como entrada y devuelve los atributos modificados que Amazon Cognito aplica al perfil de usuario.

Información general sobre flujos

Cuando un usuario se autentica con un proveedor de identidad externo, Amazon Cognito invoca el activador de federación entrante antes de crear o actualizar el perfil de usuario. El activador recibe los atributos sin procesar del proveedor de identidad y puede transformarlos antes de que Amazon Cognito los almacene. Este flujo se produce tanto para los nuevos usuarios federados como para los usuarios existentes que vuelven a iniciar sesión mediante la federación.

Flujo de activación de Lambda de federación entrante

Parámetros de activación de Lambda de federación entrante

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.

JSON
{
    "version": "string",
    "triggerSource": "InboundFederation_ExternalProvider",
    "region": AWSRegion,
    "userPoolId": "string",
    "userName": "string",
    "callerContext": {
        "awsSdkVersion": "string",
        "clientId": "string"
    },
    "request": {
        "providerName": "string",
        "providerType": "string",
        "attributes": {
            "tokenResponse": {
                "access_token": "string",
                "token_type": "string",
                "expires_in": "string"
            },
            "idToken": {
                "sub": "string",
                "email": "string",
                "email_verified": "string"
            },
            "userInfo": {
                "email": "string",
                "given_name": "string",
                "family_name": "string"
            },
            "samlResponse": {
                "string": "string"
            }
        }
    },
    "response": {
        "userAttributesToMap": {
            "string": "string"
        }
    }
}

Parámetros de las solicitudes de federación entrantes

Nombre del proveedor

El nombre del proveedor de identidad externo.

Tipo de proveedor

El tipo de proveedor de identidad externo. Valores válidos: OIDCSAML,Facebook,Google,SignInWithApple,LoginWithAmazon.

attributes

Los atributos sin procesar recibidos del proveedor de identidad antes del procesamiento. La estructura varía según el tipo de proveedor.

Atributos. TokenResponse

OAuth datos de respuesta simbólicos del punto final. /token Disponible solo para el OIDC y los proveedores sociales. Contieneaccess_token,id_token, refresh_token token_typeexpires_in, y. scope

Attributes.idToken

JWT afirma que el token de identificación decodificado y validado. Disponible solo para el OIDC y los proveedores sociales. Contiene información de identidad de usuario verificada, que incluye sub (identificador de usuario único) emailname,, iss (emisor), aud (audiencia), exp (caducidad) y iat (hora de emisión).

Attributes.UserInfo

Información de perfil de usuario ampliada desde el punto final. UserInfo Disponible solo para el OIDC y los proveedores sociales. Contiene atributos de perfil detalladosgiven_name, como, family_name pictureaddress, y otros campos específicos del proveedor. Puede estar vacío si el IdP no es compatible con el UserInfo punto final o si la llamada al punto final falla.

Atributos. Respuesta SAML

Atributos de aserción de SAML. Disponible solo para proveedores de SAML. Contiene los atributos de la respuesta de SAML.

Parámetros de respuesta de la federación entrante

userAttributesToMapa

Los atributos de usuario que se van a aplicar al perfil de usuario.

importante

Debe incluir TODOS los atributos de usuario que desee conservar en la respuesta, incluidos los atributos que no vaya a modificar. Los atributos que no estén incluidos en la userAttributesToMap respuesta se eliminarán y no se almacenarán en el perfil de usuario. Esto se aplica tanto a los atributos modificados como a los no modificados.

Comportamiento de respuesta vacía

Si devuelves un objeto vacío {} parauserAttributesToMap, todos los atributos originales del proveedor de identidad se conservan sin cambios. Esto actúa como una operación no operativa, como si la función Lambda nunca se hubiera ejecutado. Esto es diferente de omitir atributos, que los elimina.

Atributos específicos del proveedor

La estructura de request.attributes varía según. providerType El OIDC y los proveedores sociales incluyen tokenResponseidToken, y userInfo objetos. Los proveedores de SAML incluyen solo el objeto. samlResponse

Ejemplo de federación entrante: administración de miembros de grupos

En este ejemplo, se muestra cómo asignar grupos de proveedores de identidad federados a grupos de grupos de usuarios de Amazon Cognito. Esta función extrae la pertenencia a un grupo de la respuesta federada y añade automáticamente los usuarios a los grupos de Amazon Cognito correspondientes, lo que elimina la necesidad de activar activadores posteriores a la autenticación.

Node.js
exports.handler = async (event) => {
    const { providerType, attributes } = event.request;
    
    // Extract user attributes based on provider type
    let userAttributesFromIdp = {};
    if (providerType === 'SAML') {
        userAttributesFromIdp = attributes.samlResponse || {};
    } else {
        // For OIDC and Social providers, merge userInfo and idToken
        userAttributesFromIdp = {
            ...(attributes.userInfo || {}),
            ...(attributes.idToken || {})
        };
    }
    
    // Extract groups from federated response
    const federatedGroups = userAttributesFromIdp.groups?.split(',') || [];
    
    // Map federated groups to Cognito groups
    const groupMapping = {
        'Domain Admins': 'Administrators',
        'Engineering': 'Developers',
        'Sales': 'SalesTeam'
    };
    
    // Filter to only in-scope groups
    const mappedGroups = federatedGroups
        .map(group => groupMapping[group.trim()])
        .filter(group => group); // Remove undefined values
    
    // Pass through attributes with mapped groups as custom attribute
    const attributesToMap = {
        ...userAttributesFromIdp,
        'custom:user_groups': mappedGroups.join(',')
    };
    
    // Remove original groups attribute
    delete attributesToMap.groups;
    
    event.response.userAttributesToMap = attributesToMap;
    return 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
{
    "userPoolId": "us-east-1_XXXXXXXXX",
    "request": {
        "providerName": "CorporateAD",
        "providerType": "SAML",
        "attributes": {
            "samlResponse": {
                "email": "jane.smith@company.com",
                "given_name": "Jane",
                "family_name": "Smith",
                "groups": "Engineering,Domain Admins",
                "department": "Engineering"
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

Ejemplo de federación entrante: truncar atributos grandes

En este ejemplo, se muestra cómo truncar los valores de atributo que superan los límites de almacenamiento de Amazon Cognito. Esta función comprueba cada atributo del proveedor de identidad. Si el valor de un atributo supera los 2048 caracteres, trunca el valor y añade puntos suspensivos para indicar el truncamiento. Todos los demás atributos pasan sin cambios.

Node.js
exports.handler = async (event) => {
    const MAX_ATTRIBUTE_LENGTH = 2048;
    
    // Get the identity provider attributes based on provider type
    const { providerType, attributes } = event.request;
    let idpAttributes = {};
    
    if (providerType === 'SAML') {
        idpAttributes = attributes.samlResponse || {};
    } else {
        // For OIDC and Social providers, merge userInfo and idToken
        idpAttributes = {
            ...(attributes.userInfo || {}),
            ...(attributes.idToken || {})
        };
    }
    
    const userAttributes = {};
    
    // Process each attribute
    for (const [key, value] of Object.entries(idpAttributes)) {
        if (typeof value === 'string' && value.length > MAX_ATTRIBUTE_LENGTH) {
            // Truncate the value and add ellipsis
            userAttributes[key] = value.substring(0, MAX_ATTRIBUTE_LENGTH - 3) + '...';
            console.log(`Truncated attribute ${key} from ${value.length} to ${userAttributes[key].length} characters`);
        } else {
            // Keep the original value
            userAttributes[key] = value;
        }
    }
    
    // Return the modified attributes
    event.response.userAttributesToMap = userAttributes;
    return 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": "string",
    "triggerSource": "InboundFederation_ExternalProvider",
    "region": "us-east-1",
    "userPoolId": "us-east-1_XXXXXXXXX",
    "userName": "ExampleProvider_12345",
    "callerContext": {
        "awsSdkVersion": "string",
        "clientId": "string"
    },
    "request": {
        "providerName": "ExampleProvider",
        "providerType": "OIDC",
        "attributes": {
            "tokenResponse": {
                "access_token": "abcDE...",
                "token_type": "Bearer",
                "expires_in": "3600"
            },
            "idToken": {
                "sub": "12345",
                "email": "user@example.com"
            },
            "userInfo": {
                "email": "user@example.com",
                "given_name": "Example",
                "family_name": "User",
                "bio": "This is a very long biography that contains more than 2048 characters..."
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

Ejemplo de federación entrante: registro de eventos de federación

En este ejemplo se muestra cómo registrar los eventos de autenticación federada para su supervisión y depuración. Esta función de ejemplo captura información detallada sobre los usuarios federados y sus atributos, lo que proporciona visibilidad del proceso de autenticación.

Node.js
exports.handler = async (event) => {
    const { providerName, providerType, attributes } = event.request;
    
    // Extract user attributes based on provider type
    let userAttributesFromIdp = {};
    if (providerType === 'SAML') {
        userAttributesFromIdp = attributes.samlResponse || {};
    } else {
        // For OIDC and Social providers, merge userInfo and idToken
        userAttributesFromIdp = {
            ...(attributes.userInfo || {}),
            ...(attributes.idToken || {})
        };
    }
    
    // Log federated authentication details
    console.log(JSON.stringify({
        timestamp: new Date().toISOString(),
        providerName,
        providerType,
        userEmail: userAttributesFromIdp.email,
        attributeCount: Object.keys(userAttributesFromIdp).length,
        attributes: userAttributesFromIdp
    }));
    
    // Pass through all attributes unchanged
    event.response.userAttributesToMap = userAttributesFromIdp;
    return 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": "string",
    "triggerSource": "InboundFederation_ExternalProvider",
    "region": "us-east-1",
    "userPoolId": "us-east-1_XXXXXXXXX",
    "userName": "CorporateAD_john.doe",
    "callerContext": {
        "awsSdkVersion": "string",
        "clientId": "string"
    },
    "request": {
        "providerName": "CorporateAD",
        "providerType": "SAML",
        "attributes": {
            "samlResponse": {
                "email": "john.doe@company.com",
                "given_name": "John",
                "family_name": "Doe",
                "department": "Engineering",
                "employee_id": "EMP12345"
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

Resultado esperado CloudWatch de los registros:

JSON
{
    "timestamp": "2025-01-14T21:17:40.153Z",
    "providerName": "CorporateAD",
    "providerType": "SAML",
    "userEmail": "john.doe@company.com",
    "attributeCount": 5,
    "attributes": {
        "email": "john.doe@company.com",
        "given_name": "John",
        "family_name": "Doe",
        "department": "Engineering",
        "employee_id": "EMP12345"
    }
}