Como personalizar fluxos de trabalho do grupo de usuários com acionadores do Lambda

O Amazon Cognito trabalha com funções do AWS Lambda para modificar o comportamento de autenticação do grupo de usuários. É possível configurar o grupo de usuários para invocar automaticamente as funções do Lambda antes da primeira inscrição, após a conclusão da autenticação e em vários estágios intermediários. As funções podem modificar o comportamento-padrão do fluxo de autenticação, fazer solicitações de API para modificar o grupo de usuários ou outros recursos da AWS e se comunicar com sistemas externos. O código nas funções do Lambda é seu. O Amazon Cognito envia dados de eventos para a função, espera que a função processe os dados e, na maioria dos casos, antecipa um evento de resposta que reflete as alterações que você deseja fazer na sessão.

No sistema de eventos de solicitação e resposta, você pode apresentar seus próprios desafios de autenticação, migrar usuários entre o grupo de usuários e outro armazenamento de identidades, personalizar mensagens e modificar tokens JSON da web (JWTs).

Os gatilhos do Lambda podem personalizar a resposta que o Amazon Cognito fornece ao usuário depois que ele inicia uma ação em seu grupo de usuários. Por exemplo, é possível impedir o login de um usuário que, de outra forma, seria bem-sucedido. Eles também podem executar operações de runtime no ambiente da AWS, APIs externas, bancos de dados ou armazenamentos de identidades. O gatilho de migração de usuário, por exemplo, pode combinar uma ação externa com uma alteração no Amazon Cognito: você pode pesquisar informações do usuário em um diretório externo e definir atributos em um novo usuário com base nessas informações externas.

Quando você tem um gatilho do Lambda atribuído ao seu grupo de usuários, o Amazon Cognito interrompe seu fluxo padrão para solicitar informações de sua função. O Amazon Cognito gera um evento JSON e o transmite para sua função. O evento contém informações sobre a solicitação do usuário para criar uma conta de usuário, fazer login, redefinir uma senha ou atualizar um atributo. Sua função então tem a oportunidade de agir ou enviar o evento de volta sem modificações. Um evento retornado sem modificação notifica seu grupo de usuários para continuar com a ação padrão do evento. Por exemplo, seu acionador de pré-inscrição pode confirmar automaticamente os usuários para a origem do acionador PreSignUp_SignUp, mas retornar o evento inalterado para usuários externos e criados pelo administrador.

A tabela a seguir resume algumas das maneiras pelas quais os acionadores do Lambda são usados para personalizar operações do grupo de usuários:

O que é importante saber sobre acionadores do Lambda

Ao preparar os grupos de usuários para as funções do Lambda, considere o seguinte:

Adicionar um acionador do Lambda do grupo de usuários

Evento de acionador do Lambda do grupo de usuários

O Amazon Cognito transmite informações de evento para a função do Lambda. A função do Lambda retorna o mesmo objeto de evento para o Amazon Cognito, com as alterações na resposta. Se a sua função retornar o evento de entrada sem modificação, o Amazon Cognito continuará com o comportamento padrão. Veja a seguir os parâmetros comuns a todos os eventos de entrada do acionador do Lambda. Para obter a sintaxe de eventos específica do acionador, revise o esquema de eventos na seção deste guia para cada acionador.

JSON

{
    "version": "string",
    "triggerSource": "string",
    "region": AWSRegion,
    "userPoolId": "string",
    "userName": "string",
    "callerContext": 
        {
            "awsSdkVersion": "string",
            "clientId": "string"
        },
    "request":
        {
            "userAttributes": {
                "string": "string",
                ....
            }
        },
    "response": {}
}

Parâmetros comuns do acionador do Lambda do grupo de usuários

Metadados do cliente

Você pode enviar parâmetros personalizados para suas funções de acionador do Lambda em operações de API e solicitações de Endpoint de token. Com os metadados do cliente, sua aplicação pode coletar informações adicionais sobre o ambiente em que as solicitações se originam. Quando você transmite metadados do cliente para suas funções do Lambda, elas podem processar os dados adicionais e usá-los nos logs ou na personalização dos fluxos de autenticação. Os metadados do cliente são pares de strings de sua escolha e design em um formato de valor-chave JSON.

Este é um exemplo de transmissão de metadados do cliente para o acionador de pré-inscrição.

SignUp request

Veja a seguir um exemplo de solicitação SignUp com metadados do cliente que o Amazon Cognito transmite para um acionador de pré-inscrição.

POST HTTP/1.1
Host: cognito-idp.us-east-1.amazonaws.com
X-Amz-Date: 20230613T200059Z
Accept-Encoding: gzip, deflate, br
X-Amz-Target: AWSCognitoIdentityProviderService.SignUp
User-Agent: <UserAgentString>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>

{
    "ClientId": "1example23456789",
    "Username": "mary_major",
    "Password": "<Password>",
    "SecretHash": "<Secret hash>",
    "ClientMetadata": { 
        "IpAddress" : "192.0.2.252",
        "GeoLocation" : "Netherlands (Kingdom of the) [NL]"
    }
    "UserAttributes": [
        {
            "Name": "name",
            "Value": "Mary"
        },
        {
            "Name": "email",
            "Value": "mary_major@example.com"
        },
        {
            "Name": "phone_number",
            "Value": "+12065551212"
        }
    ],
}

Lambda trigger input event

A solicitação resulta no corpo de solicitação a seguir para sua função de pré-cadastro.

{
    "callerContext": {
        "awsSdkVersion": "aws-sdk-unknown-unknown",
        "clientId": "1example23456789"
    },
    "region": "us-west-2",
    "request": {
        "clientMetadata": {
            "GeoLocation": "Netherlands (Kingdom of the) [NL]",
            "IpAddress": "192.0.2.252"
        },
        "userAttributes": {
            "email": "mary_major@example.com",
            "name": "Mary",
            "phone_number": "+12065551212"
        },
        "validationData": null
    },
    "response": {
        "autoConfirmUser": false,
        "autoVerifyEmail": false,
        "autoVerifyPhone": false
    },
    "triggerSource": "PreSignUp_SignUp",
    "userName": "mary_major2",
    "userPoolId": "us-west-2_EXAMPLE",
    "version": "1"
}

Metadados do cliente para credenciais de cliente máquina-a-máquina (M2M)

Você pode transmitir metadados do cliente em solicitações de M2M. Os metadados do cliente são informações adicionais de um usuário ou ambiente de aplicação que podem contribuir para os resultados de um Acionador do Lambda antes da geração do token. Nas operações de autenticação com uma entidade principal de usuário, você pode transmitir metadados do cliente para o acionador de pré-geração de token no corpo das solicitações de API AdminRespondToAuthChallenge e RespondToAuthChallenge. Como as aplicações conduzem o fluxo de geração de tokens de acesso para M2M com solicitações diretas ao Endpoint de token, elas têm um modelo diferente. No corpo POST das solicitações de token para credenciais do cliente, transmita um parâmetro aws_client_metadata com o objeto de metadados do cliente codificado em URL (x-www-form-urlencoded) para string. Para ver um exemplo de solicitação, consulte Credenciais do cliente com autorização básica. Veja a seguir um exemplo de parâmetro que transmite os pares de chave-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

Atributos temporários do usuário: validationData

Algumas operações de autenticação também têm um parâmetro validationData. Assim como os metadados do cliente, essa é uma oportunidade de transmitir informações externas que o Amazon Cognito não coleta automaticamente para os acionadores do Lambda. O campo de dados de validação tem como objetivo fornecer à sua função do Lambda um contexto de usuário adicional nas operações de cadastro e login. SignUp e AdminCreateUser transmitem validationData ao acionador de pré-cadastro. InitiateAuth e AdminInitiateAuth transmitem ClientMetadata no corpo da solicitação da API como validationData no evento de entrada aos acionadores pré-autenticação e migrar usuário.

Para mapear as operações da API para as funções para as quais elas podem transmitir metadados do cliente, consulte as seções de origem do acionador a seguir.

Conectar operações de API a gatilhos do Lambda

As seções a seguir descrevem os gatilhos do Lambda que o Amazon Cognito invoca a partir da atividade em seu grupo de usuários.

Quando a aplicação conecta usuários pela API de grupos de usuários do Amazon Cognito, do login gerenciado ou de endpoints de grupo de usuários, o Amazon Cognito invoca suas funções do Lambda com base no contexto da sessão. Para ter mais informações sobre a API de grupos de usuários do Amazon Cognito e endpoints de grupo de usuários, consulte Noções básicas sobre a autenticação de API, OIDC e páginas de login gerenciado. As tabelas nas seções a seguir descrevem eventos que fazem com que o Amazon Cognito invoque uma função e a string triggerSource que o Amazon Cognito inclui na solicitação.

Gatilhos do Lambda na API do Amazon Cognito

A tabela a seguir descreve as strings de origem dos acionadores do Lambda que o Amazon Cognito pode invocar quando a aplicação cria, faz login ou atualiza um usuário local.

Acionadores do Lambda para usuários locais do Amazon Cognito no login gerenciado

A tabela a seguir descreve as strings de origem dos acionadores do Lambda que o Amazon Cognito pode invocar quando um usuário local faz login em seu grupo de usuários com o login gerenciado.

Acionadores do Lambda para usuários federados

Você pode usar os seguintes acionadores do Lambda para personalizar seus fluxos de trabalho do grupo de usuários para usuários que fazem login com um provedor federado.

O login federado não invoca nenhum Acionadores do Lambda de desafio personalizado de autenticação, Migrar o acionador do Lambda do usuário, Acionador do Lambda de mensagem personalizada ou Acionadores do Lambda remetente personalizado no grupo de usuários.

Conectar gatilhos do Lambda às operações funcionais do grupo de usuários

Cada gatilho do Lambda tem uma função em seu grupo de usuários. Por exemplo, um gatilho pode modificar seu fluxo de inscrição ou adicionar um desafio de autenticação personalizado. O evento que o Amazon Cognito envia para uma função do Lambda pode refletir uma das várias ações que compõem essa função. Por exemplo, o Amazon Cognito invoca um gatilho de pré-inscrição quando o usuário se inscreve e quando você cria um usuário. Cada um desses casos diferentes para a mesma função tem seu próprio valor triggerSource. Sua função do Lambda pode processar eventos recebidos de forma diferente com base na operação que a invocou.

O Amazon Cognito também invoca todas as funções atribuídas quando um evento corresponde a uma fonte de gatilhos. Por exemplo, quando um usuário faz login em um grupo de usuários ao qual você atribuiu gatilhos de migração de usuário e pré-autenticação, ele ativa ambos.