As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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

O Amazon Cognito trabalha com AWS Lambda funções para modificar o comportamento de autenticação do seu 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. Suas funções podem modificar o comportamento padrão do seu fluxo de autenticação, fazer solicitações de API para modificar seu grupo de usuários ou outros AWS recursos 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 seu grupo de usuários e outro repositório de identidades, personalizar mensagens e modificar tokens web JSON ()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 realizar operações de tempo de execução em seu AWS ambiente externo APIs, bancos de dados ou repositórios de identidade. 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.

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:

Coisas que você deve saber sobre os gatilhos Lambda

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

Adicionar um acionador 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 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 que são 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 gatilho do Lambda em operações e Endpoint de token solicitações de API. Com os metadados do cliente, seu aplicativo pode coletar informações adicionais sobre o ambiente de origem das solicitações. Quando você passa metadados do cliente para suas funções do Lambda, eles podem processar os dados adicionais e usá-los no registro 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.

Aqui está um exemplo de transmissão de metadados do cliente para o gatilho de pré-inscrição.

SignUp request

Veja a seguir um exemplo de SignUpsolicitação com metadados do cliente que o Amazon Cognito passa para um gatilho 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 seguinte corpo de solicitação para sua função de pré-inscrição.

{
    "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 do cliente machine-to-machine (M2M)

Você pode passar metadados do cliente em solicitações M2M. Os metadados do cliente são informações adicionais de um ambiente de usuário ou aplicativo que podem contribuir para os resultados de umAcionador do Lambda antes da geração do token. Em operações de autenticação com um usuário principal, você pode passar metadados do cliente para o gatilho de pré-geração de token no corpo das solicitações AdminRespondToAuthChallengede RespondToAuthChallengeAPI. Como os aplicativos conduzem o fluxo de geração de tokens de acesso para M2M com solicitações diretas aoEndpoint de token, eles têm um modelo diferente. No corpo POST das solicitações de token para credenciais do cliente, passe um aws_client_metadata parâmetro com o objeto de metadados do cliente codificado em URL () para string. x-www-form-urlencoded 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 passa os pares de valores-chave. {"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 validationData parâmetro. Assim como os metadados do cliente, essa é uma oportunidade de transmitir informações externas que o Amazon Cognito não coleta automaticamente para os gatilhos do Lambda. O campo de dados de validação tem como objetivo fornecer à sua função Lambda um contexto de usuário adicional nas operações de inscrição e login. SignUpe AdminCreateUserpasse validationData para o gatilho de pré-inscrição. InitiateAuthe AdminInitiateAuthpasse ClientMetadata o corpo da solicitação da API como validationData no evento de entrada para os gatilhos do usuário de pré-autenticação e migração.

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 gatilho 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 seu aplicativo registra usuários por meio da API de grupos de usuários do Amazon Cognito, login gerenciado ou endpoints do 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 Compreendendo a autenticação de API, OIDC e páginas de login gerenciadas. 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 Lambda para usuários locais do Amazon Cognito em login gerenciado

A tabela a seguir descreve as cadeias de caracteres de origem dos gatilhos Lambda que o Amazon Cognito pode invocar quando um usuário local faz login no seu grupo de usuários com 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.