Déclencheur Lambda de fédération entrante - Amazon Cognito
Vue d'ensemble du fluxParametersExemple : adhésion à un groupeExemple : tronquer les attributsExemple : enregistrement d'événements

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Déclencheur Lambda de fédération entrante

Le déclencheur de fédération entrante transforme les attributs des utilisateurs fédérés pendant le processus d'authentification avec les fournisseurs d'identité externes. Lorsque les utilisateurs s'authentifient via des fournisseurs d'identité configurés, ce déclencheur vous permet de modifier les réponses des fournisseurs SAML et OIDC externes en interceptant et en transformant les données au cours du processus d'authentification, offrant ainsi un contrôle programmatique sur la manière dont les groupes d'utilisateurs Amazon Cognito gèrent les utilisateurs fédérés et leurs attributs.

Utilisez ce déclencheur pour ajouter, remplacer ou supprimer des attributs avant de créer de nouveaux utilisateurs ou de mettre à jour des profils d'utilisateurs fédérés existants. Ce déclencheur reçoit les attributs bruts du fournisseur d'identité en entrée et renvoie les attributs modifiés qu'Amazon Cognito applique au profil utilisateur.

Vue d'ensemble du flux

Lorsqu'un utilisateur s'authentifie auprès d'un fournisseur d'identité externe, Amazon Cognito invoque le déclencheur de fédération entrante avant de créer ou de mettre à jour le profil utilisateur. Le déclencheur reçoit les attributs bruts du fournisseur d'identité et peut les transformer avant qu'Amazon Cognito ne les stocke. Ce flux s'applique à la fois aux nouveaux utilisateurs fédérés et aux utilisateurs existants qui se reconnectent par le biais de la fédération.

Flux de déclencheurs Lambda pour la fédération entrante

Paramètres du déclencheur Lambda de la fédération entrante

La demande qu’Amazon Cognito transmet à cette fonction Lambda est une combinaison des paramètres ci-dessous et des paramètres courants qu’Amazon Cognito ajoute à toutes les demandes.

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

Paramètres des demandes de fédération entrantes

Nom du fournisseur

Nom du fournisseur d'identité externe.

Type de fournisseur

Type du fournisseur d'identité externe. Valeurs valides :OIDC,SAML,Facebook,Google,SignInWithApple,LoginWithAmazon.

attributs

Les attributs bruts reçus du fournisseur d'identité avant le traitement. La structure varie en fonction du type de fournisseur.

Attributs.tokenResponse

OAuth données de réponse du jeton provenant du /token point de terminaison. Disponible uniquement pour l'OIDC et les prestataires sociaux. Contientaccess_token,id_token, refresh_tokentoken_type,expires_in, etscope.

Attributs.IDToken

JWT revendique un jeton d'identification décodé et validé. Disponible uniquement pour l'OIDC et les prestataires sociaux. Contient des informations d'identité utilisateur vérifiées, notamment sub (identifiant utilisateur unique) emailname,,, iss (émetteur), aud (public), exp (expiration) et iat (heure d'émission).

Attributs.UserInfo

Informations de profil utilisateur étendues depuis le UserInfo terminal. Disponible uniquement pour l'OIDC et les prestataires sociaux. Contient des attributs de profil détaillés tels quegiven_name,,family_name, pictureaddress, et d'autres champs spécifiques au fournisseur. Peut être vide si l'IdP ne prend pas en charge le point de UserInfo terminaison ou si l'appel du point de terminaison échoue.

Attributs.SAML Response

Attributs d'assertion SAML. Disponible uniquement pour les fournisseurs SAML. Contient les attributs de la réponse SAML.

Paramètres de réponse de la fédération entrante

userAttributesToCarte

Les attributs utilisateur à appliquer au profil utilisateur.

Important

Vous devez inclure TOUS les attributs utilisateur que vous souhaitez conserver dans la réponse, y compris les attributs que vous ne modifiez pas. Tous les attributs non inclus dans la userAttributesToMap réponse seront supprimés et ne seront pas stockés dans le profil utilisateur. Cela s'applique à la fois aux attributs modifiés et non modifiés.

Comportement de réponse vide

Si vous renvoyez un objet vide {} pouruserAttributesToMap, tous les attributs d'origine du fournisseur d'identité restent inchangés. Cela agit comme un no-op, comme si la fonction Lambda n'avait jamais été exécutée. Cela est différent de l'omission d'attributs, qui les supprime.

Attributs spécifiques au fournisseur

La structure de request.attributes varie en fonction duproviderType. L'OIDC et les fournisseurs sociaux incluent tokenResponseidToken, et les userInfo objets. Les fournisseurs SAML incluent uniquement l'samlResponseobjet.

Exemple de fédération entrante : gestion des membres de groupes

Cet exemple montre comment mapper des groupes de fournisseurs d'identité fédérés à des groupes de groupes d'utilisateurs Amazon Cognito. Cette fonction extrait l'appartenance à un groupe à partir de la réponse fédérée et ajoute automatiquement les utilisateurs aux groupes Amazon Cognito correspondants, éliminant ainsi le besoin de déclencheurs post-authentification.

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 transmet les informations d’événement à votre fonction Lambda. Cette fonction renvoie alors le même objet d’événement à Amazon Cognito, avec d’éventuelles modifications dans la réponse. Dans la console Lambda, vous pouvez configurer un événement de test avec des données pertinentes pour votre déclencheur Lambda. Voici un événement de test pour cet exemple de code :

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

Exemple de fédération entrante : tronquer de grands attributs

Cet exemple montre comment tronquer les valeurs d'attribut qui dépassent les limites de stockage d'Amazon Cognito. Cette fonction vérifie chaque attribut du fournisseur d'identité. Si la valeur d'un attribut dépasse 2 048 caractères, elle est tronquée et des points de suspension sont ajoutés pour indiquer la troncature. Tous les autres attributs sont transmis sans modification.

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 transmet les informations d’événement à votre fonction Lambda. Cette fonction renvoie alors le même objet d’événement à Amazon Cognito, avec d’éventuelles modifications dans la réponse. Dans la console Lambda, vous pouvez configurer un événement de test avec des données pertinentes pour votre déclencheur Lambda. Voici un événement de test pour cet exemple de code :

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

Exemple de fédération entrante : enregistrement des événements de fédération

Cet exemple montre comment enregistrer les événements d'authentification fédérée à des fins de surveillance et de débogage. Cet exemple de fonction capture des informations détaillées sur les utilisateurs fédérés et leurs attributs, offrant ainsi une visibilité sur le processus d'authentification.

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 transmet les informations d’événement à votre fonction Lambda. Cette fonction renvoie alors le même objet d’événement à Amazon Cognito, avec d’éventuelles modifications dans la réponse. Dans la console Lambda, vous pouvez configurer un événement de test avec des données pertinentes pour votre déclencheur Lambda. Voici un événement de test pour cet exemple de code :

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

Sortie CloudWatch des journaux attendue :

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