Acionador Lambda de federação de entrada

O gatilho de federação de entrada transforma os atributos do usuário federado durante o processo de autenticação com provedores de identidade externos. Quando os usuários se autenticam por meio de provedores de identidade configurados, esse gatilho permite que você modifique as respostas de provedores externos de SAML e OIDC interceptando e transformando dados no processo de autenticação, fornecendo controle programático sobre como os grupos de usuários do Amazon Cognito lidam com usuários federados e seus atributos.

Use esse gatilho para adicionar, substituir ou suprimir atributos antes de criar novos usuários ou atualizar perfis de usuários federados existentes. Esse gatilho recebe atributos brutos do provedor de identidade como entrada e retorna atributos modificados que o Amazon Cognito aplica ao perfil do usuário.

Visão geral do fluxo

Quando um usuário se autentica com um provedor de identidade externo, o Amazon Cognito invoca o gatilho de federação de entrada antes de criar ou atualizar o perfil do usuário. O gatilho recebe os atributos brutos do provedor de identidade e pode transformá-los antes que o Amazon Cognito os armazene. Esse fluxo ocorre tanto para novos usuários federados quanto para usuários existentes que se conectam novamente por meio da federação.

Parâmetros de gatilho do Lambda de federação de entrada

A solicitação que o Amazon Cognito transmite para essa função do Lambda é uma combinação dos parâmetros abaixo e dos parâmetros comuns que o Amazon Cognito adiciona a todas as solicitações.

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 solicitação de federação de entrada

Nome do provedor

O nome do provedor de identidade externo.

Tipo de provedor

O tipo do provedor de identidade externo. Valores válidos:OIDC,SAML,Facebook,Google,SignInWithApple,LoginWithAmazon.

attributes

Os atributos brutos recebidos do provedor de identidade antes do processamento. A estrutura varia de acordo com o tipo de provedor.

Atributos. TokenResponse

OAuth dados de resposta do token do /token endpoint. Disponível somente para OIDC e provedores sociais. Contém access_tokenid_token, refresh_tokentoken_type,expires_in,, scope e.

Attributes.idToken

O token de ID decodificado e validado que a JWT reivindica. Disponível somente para OIDC e provedores sociais. Contém informações verificadas de identidade do usuário, incluindo sub (identificador de usuário exclusivo) emailname,,, iss (emissor), aud (público), exp (expiração) e iat (horário de emissão).

Atributos. Informações do usuário

Informações estendidas do perfil do usuário a partir do UserInfo endpoint. Disponível somente para OIDC e provedores sociais. Contém atributos de perfil detalhadosgiven_name, comofamily_name,picture,address, e outros campos específicos do provedor. Pode estar vazio se o IdP não suportar o UserInfo endpoint ou se a chamada do endpoint falhar.

Atributos. Resposta SAML

Atributos de asserção SAML. Disponível somente para provedores de SAML. Contém atributos da resposta SAML.

Parâmetros de resposta da federação de entrada

userAttributesToMapa

Os atributos do usuário a serem aplicados ao perfil do usuário.

Importante

Você deve incluir TODOS os atributos do usuário que deseja reter na resposta, incluindo os atributos que você não está modificando. Todos os atributos não incluídos na userAttributesToMap resposta serão descartados e não serão armazenados no perfil do usuário. Isso se aplica tanto aos atributos modificados quanto aos não modificados.

Comportamento de resposta vazia

Se você retornar um objeto vazio {} parauserAttributesToMap, todos os atributos originais do provedor de identidade serão mantidos inalterados. Isso funciona como um sistema autônomo, como se a função Lambda nunca tivesse sido executada. Isso é diferente de omitir atributos, o que os elimina.

Atributos específicos do provedor

A estrutura do request.attributes varia com base noproviderType. O OIDC e os provedores sociais incluem tokenResponseidToken, e userInfo objetos. Os provedores de SAML incluem somente o samlResponse objeto.

Exemplo de federação de entrada: gerenciamento de membros de grupos

Este exemplo mostra como mapear grupos de provedores de identidade federados para grupos de grupos de usuários do Amazon Cognito. Essa função extrai a associação ao grupo da resposta federada e adiciona automaticamente usuários aos grupos correspondentes do Amazon Cognito, eliminando a necessidade de acionadores de pós-autenticação.

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

O Amazon Cognito transmite informações de evento para a função do Lambda. A função retorna o mesmo objeto de evento para o Amazon Cognito, com as alterações na resposta. No console do Lambda, você pode configurar um evento de teste com dados relevantes para o acionador do Lambda. A seguir, é mostrado um evento de teste para esse exemplo de código:

JSON

{
    "userPoolId": "us-east-1_XXXXXXXXX",
    "request": {
        "providerName": "CorporateAD",
        "providerType": "SAML",
        "attributes": {
            "samlResponse": {
                "email": "[e-mail]",
                "given_name": "Jane",
                "family_name": "Smith",
                "groups": "Engineering,Domain Admins",
                "department": "Engineering"
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

Exemplo de federação de entrada: truncar atributos grandes

Este exemplo mostra como truncar valores de atributos que excedem os limites de armazenamento do Amazon Cognito. Essa função verifica cada atributo do provedor de identidade. Se um valor de atributo exceder 2048 caracteres, ele trunca o valor e adiciona reticências para indicar truncamento. Todos os outros atributos passam inalterados.

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

O Amazon Cognito transmite informações de evento para a função do Lambda. A função retorna o mesmo objeto de evento para o Amazon Cognito, com as alterações na resposta. No console do Lambda, você pode configurar um evento de teste com dados relevantes para o acionador do Lambda. A seguir, é mostrado um evento de teste para esse exemplo de código:

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": "[e-mail]"
            },
            "userInfo": {
                "email": "[e-mail]",
                "given_name": "Example",
                "family_name": "User",
                "bio": "This is a very long biography that contains more than 2048 characters..."
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

Exemplo de federação de entrada: registro de eventos de federação

Este exemplo mostra como registrar eventos de autenticação federada para monitoramento e depuração. Esse exemplo de função captura informações detalhadas sobre usuários federados e seus atributos, fornecendo visibilidade do processo de autenticação.

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

O Amazon Cognito transmite informações de evento para a função do Lambda. A função retorna o mesmo objeto de evento para o Amazon Cognito, com as alterações na resposta. No console do Lambda, você pode configurar um evento de teste com dados relevantes para o acionador do Lambda. A seguir, é mostrado um evento de teste para esse exemplo de código:

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": "[e-mail]",
                "given_name": "John",
                "family_name": "Doe",
                "department": "Engineering",
                "employee_id": "EMP12345"
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

Saída CloudWatch de registros esperada:

JSON

{
    "timestamp": "2025-01-14T21:17:40.153Z",
    "providerName": "CorporateAD",
    "providerType": "SAML",
    "userEmail": "[e-mail]",
    "attributeCount": 5,
    "attributes": {
        "email": "[e-mail]",
        "given_name": "John",
        "family_name": "Doe",
        "department": "Engineering",
        "employee_id": "EMP12345"
    }
}