Como personalizar fluxos de trabalho do grupo de usuários com acionadores do Lambda - Amazon Cognito
Considerações importantesComo adicionar um acionador do grupo de usuáriosEvento de acionador do Lambda do grupo de usuáriosParâmetros comuns do acionador do Lambda do grupo de usuáriosFontes de gatilho do Lambda por eventoFontes de gatilhos do Lambda por função

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 API solicitações 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 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 realizar operações de tempo de execução em seu AWS ambiente externoAPIs, 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 JSON evento 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:

Fluxo de grupo de usuários Operation Descrição

Fluxo de autenticação personalizado

 Definir o desafio de autenticação Determina o próximo desafio em um fluxo de autenticação personalizado
Criar desafio de autenticação Cria um desafio em um fluxo de autenticação personalizado
Verificar a resposta do desafio de autenticação Determina se uma resposta está correta em um fluxo de autenticação personalizado
Eventos de autenticação Acionador do Lambda de pré-autenticação Validação personalizada para aceitar ou negar a solicitação de login
Acionador do Lambda de pós-autenticação Registra eventos para análise personalizada
Acionador do Lambda antes da geração do token Aumenta ou suprime solicitações de token
Cadastrar-se Acionador do Lambda de pré-cadastro Executa uma validação personalizada que aceita ou nega a solicitação de cadastro
Acionador do Lambda de pós-confirmação Adiciona mensagens de boas-vindas personalizadas ou registro de eventos para análise personalizada
Migrar o acionador do Lambda do usuário Migra um usuário de um diretório de usuário existente para grupos de usuários
Mensagens Acionador do Lambda de mensagem personalizada Realiza personalização avançada e localização de mensagens
Criação de token Acionador do Lambda antes da geração do token Adiciona ou remove atributos em tokens de ID
Provedores de e-mail e SMS terceiros Acionadores do Lambda remetente personalizado Usa um provedor terceirizado para enviar SMS e enviar mensagens por e-mail
Tópicos

Considerações importantes

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

  • Os eventos que o Amazon Cognito envia aos gatilhos do Lambda podem mudar com novos atributos. As posições dos elementos de resposta e solicitação na JSON hierarquia podem mudar ou os nomes dos elementos podem ser adicionados. Na função do Lambda, é possível esperar receber os pares de chave-valor do elemento de entrada descritos neste guia, mas uma validação de entrada mais rigorosa pode fazer com que as funções falhem.

  • É possível selecionar uma das várias versões dos eventos que o Amazon Cognito envia a alguns gatilhos. Algumas versões podem exigir que você aceite uma alteração nos preços do Amazon Cognito. Para obter mais informações sobre a definição de preços, consulte Definição de preço do Amazon Cognito. Para personalizar os tokens de acesso em um Acionador do Lambda antes da geração do token, é necessário configurar o grupo de usuários com atributos de segurança avançados e atualizar a configuração do gatilho do Lambda para usar a versão 2 do evento.

  • Exceto Acionadores do Lambda remetente personalizado, o Amazon Cognito invoca funções do Lambda de forma síncrona. Quando o Amazon Cognito chama sua função do Lambda, ela deve responder em até cinco segundos. Se isso não acontecer e a chamada puder ser repetida, o Amazon Cognito tentará novamente. Após três tentativas malsucedidas, a função encerra a sessão. Não é possível alterar esse valor de tempo limite de cinco segundos. Para obter mais informações, consulte o modelo de programação Lambda no Guia do AWS Lambda desenvolvedor.

    O Amazon Cognito não repete chamadas de função que retornam um erro de invocação com um código de HTTP status de 500-599. Esses códigos indicam um problema de configuração que faz com que o Lambda não consiga iniciar a função. Para obter mais informações, consulte Tratamento de erros e novas tentativas automáticas em AWS Lambda.

  • Você não pode declarar uma versão da função na configuração do acionador do Lambda. Os grupos de usuários do Amazon Cognito invocam a versão mais recente da função por padrão. No entanto, você pode associar uma versão da função a um alias e definir seu gatilho LambdaArn para o alias ARN em uma solicitação CreateUserPoolor UpdateUserPoolAPI. Essa opção não está disponível no AWS Management Console. Para obter mais informações sobre aliases, consulte Aliases de função do Lambda no Guia do desenvolvedor do AWS Lambda .

  • Se você excluir um acionador do Lambda, deverá atualizar o acionador correspondente no grupo de usuários. Por exemplo, se excluir o acionador pós-autenticação, você deverá definir o acionador Post authentication (Pós-autenticação) no grupo de usuários correspondente como none (nenhum).

  • Se a função do Lambda não retornar os parâmetros de solicitação e resposta para o Amazon Cognito ou retornar um erro, o evento de autenticação não será bem-sucedido. Você pode retornar um erro na função para impedir a inscrição, a autenticação, a geração de tokens ou qualquer outro estágio do fluxo de autenticação de um usuário que invoque o acionador do Lambda.

    A interface de usuário hospedada do Amazon Cognito retorna erros que os acionadores do Lambda geram como texto de erro acima da solicitação de login. Os grupos de usuários do Amazon Cognito API retornam erros de gatilho no formato. [trigger] failed with error [error text from response] Como prática recomendada, gerem apenas erros nas funções do Lambda que você deseja que seus usuários vejam. Use métodos de saída, como print() registrar qualquer informação confidencial ou de depuração no Logs. CloudWatch Para ver um exemplo, consulte Exemplo de pré-cadastro: negar cadastro se o nome de usuário tiver menos de cinco caracteres.

  • Você pode adicionar uma função Lambda em outra Conta da AWS como acionador para seu grupo de usuários. Você deve adicionar gatilhos entre contas com as UpdateUserPoolAPIoperações CreateUserPoole, ou seus equivalentes em e a. AWS CloudFormation AWS CLI Você não pode adicionar funções de várias contas no AWS Management Console.

  • Quando você inclui um acionador do Lambda no console do Amazon Cognito, o Amazon Cognito adiciona uma política baseada em recursos à sua função que permita que o grupo de usuários a invoque. Quando você cria um acionador do Lambda fora do console do Amazon Cognito, é necessário adicionar permissões à função do Lambda. Suas permissões adicionadas devem permitir que o Amazon Cognito invoque a função em nome do grupo de usuários. Você pode adicionar permissões do Lambda Console ou usar a operação Lambda. AddPermissionAPI

    Exemplo de política baseada em recursos do Lambda

    O seguinte exemplo de política baseada em recursos do Lambda concede ao Amazon Cognito uma capacidade limitada de invocar uma função do Lambda. O Amazon Cognito só pode invocar a função quando o fizer em nome do grupo de usuários na condição aws:SourceArn e da conta na condição aws:SourceAccount.

    {
    "Version": "2012-10-17",
    "Id": "default",
    "Statement": [
        {
            "Sid": "lambda-allow-cognito",
            "Effect": "Allow",
            "Principal": {
                "Service": "cognito-idp.amazonaws.com"
            },
            "Action": "lambda:InvokeFunction",
            "Resource": "<your Lambda function ARN>",
            "Condition": {
                "StringEquals": {
                    "AWS:SourceAccount": "<your account number>"
                },
                "ArnLike": {
                    "AWS:SourceArn": "<your user pool ARN>"
                }
            }
        }
    ]
}

Como adicionar um acionador do Lambda do grupo de usuários

Para adicionar um acionador do Lambda do grupo de usuários com o console

  1. Use o console do Lambda para criar uma função do Lambda. Para obter mais informações, sobre funções Lambda, consulte o Guia do desenvolvedor do AWS Lambda.

  2. Acesse o console do Amazon Cognito e escolha User Pools (Grupos de usuários).

  3. Escolha um grupo de usuários existente na lista ou crie um grupo de usuários.

  4. Escolha a guia User pool properties (Propriedades do grupo de usuários) e localize Lambda triggers (Acionadores do Lambda).

  5. Selecione Add a Lambda trigger (Adicionar um acionador do Lambda).

  6. Selecione uma Category (Categoria) de acionador do Lambda com base no estágio de autenticação que deseja personalizar.

  7. Selecione Atribuir função Lambda e selecione uma função no mesmo grupo Região da AWS de usuários.

    nota

    Se suas credenciais AWS Identity and Access Management (IAM) tiverem permissão para atualizar a função Lambda, o Amazon Cognito adicionará uma política baseada em recursos do Lambda. Com essa política, o Amazon Cognito pode invocar a função selecionada. Se as credenciais conectadas não tiverem IAM permissões suficientes, você deverá atualizar a política baseada em recursos separadamente. Para obter mais informações, consulte Considerações importantes.

  8. Selecione Save changes.

  9. Você pode usar CloudWatch no console do Lambda para registrar sua função do Lambda. Para obter mais informações, consulte Acessando CloudWatch registros para Lambda.

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. Esse evento mostra os parâmetros comuns do acionador do Lambda:

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

versionamento

O número da versão da função do Lambda.

triggerSource

O nome do evento que acionou a função do Lambda. Para obter uma descrição de cada um, triggerSource consulteConectar gatilhos do Lambda às operações funcionais do grupo de usuários.

região

O Região da AWS como uma AWSRegion instância.

userPoolId

O ID do grupo de usuários.

userName

O nome do usuário atual.

callerContext

Metadados sobre a solicitação e o ambiente de código. Ele contém os campos awsSdkVersionclientIde.

awsSdkVersion

A versão do AWS SDK que gerou a solicitação.

clientId

O ID do cliente da aplicação do grupo de usuários.

request

Detalhes da API solicitação do seu usuário. Ele inclui os seguintes campos e quaisquer parâmetros de solicitação específicos do gatilho. Por exemplo, um evento que o Amazon Cognito envia a um acionador de pré-autenticação também conterá um parâmetro userNotFound. Você pode processar o valor desse parâmetro para realizar uma ação personalizada quando o usuário tentar fazer login com um nome de usuário não registrado.

userAttributes

Um ou mais pares de chave-valor de nomes e valores de atributos, por exemplo, "email": "john@example.com".

Retorno

Esse parâmetro não contém nenhuma informação na solicitação original. Sua função do Lambda deve retornar todo o evento ao Amazon Cognito e adicionar quaisquer parâmetros de retorno à response. Para ver quais parâmetros de retorno sua função pode incluir, consulte a documentação do gatilho que você deseja usar.

Conectando API operações aos 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 dos grupos de usuáriosAPI, da interface do usuário hospedada ou dos endpoints do grupo de usuários do Amazon Cognito, o Amazon Cognito invoca suas funções do Lambda com base no contexto da sessão. Para obter mais informações sobre os grupos de usuários API e os endpoints do grupo de usuários do Amazon Cognito, consulte. Usando os grupos de usuários API e o servidor de autorização 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.

Acionadores Lambda no Amazon Cognito API

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.

Fontes locais de acionamento de usuários no Amazon Cognito API
APIoperação Gatilho do Lambda Fonte de gatilhos

AdminCreateUser

 Pré-cadastro

PreSignUp_AdminCreateUser
Geração de pré-token

TokenGeneration_NewPasswordChallenge
Mensagem personalizada

CustomMessage_AdminCreateUser
Remetente de e-mail personalizado

CustomEmailSender_AdminCreateUser
Remetente personalizado SMS

CustomSMSSender_AdminCreateUser

SignUp

 Pré-cadastro

PreSignUp_SignUp
Mensagem personalizada

CustomMessage_SignUp
Remetente de e-mail personalizado

CustomEmailSender_SignUp
Remetente personalizado SMS

CustomSMSSender_SignUp

ConfirmSignUp

AdminConfirmSignUp

 Pós-confirmação

PostConfirmation_ConfirmSignUp

InitiateAuth

AdminInitiateAuth

 Pre authentication

PreAuthentication_Authentication
Definir o desafio de autenticação

DefineAuthChallenge_Authentication
Criar o desafio de autenticação

CreateAuthChallenge_Authentication
Geração de pré-token

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens
Migração de usuário

UserMigration_Authentication
Mensagem personalizada

CustomMessage_Authentication
Remetente de e-mail personalizado

CustomEmailSender_AccountTakeOverNotification

CustomEmailSender_Authentication
Remetente personalizado SMS

CustomSMSSender_Authentication

ForgotPassword

 Migração de usuário

UserMigration_ForgotPassword
Mensagem personalizada

CustomMessage_ForgotPassword
Remetente de e-mail personalizado

CustomEmailSender_ForgotPassword
Remetente personalizado SMS

CustomSMSSender_ForgotPassword

ConfirmForgotPassword

 Pós-confirmação

PostConfirmation_ConfirmForgotPassword

UpdateUserAttributes

AdminUpdateUserAttributes

 Mensagem personalizada

CustomMessage_UpdateUserAttribute
Remetente de e-mail personalizado

CustomEmailSender_UpdateUserAttribute
Remetente personalizado SMS

CustomSMSSender_UpdateUserAttribute

VerifyUserAttributes

 Mensagem personalizada

CustomMessage_VerifyUserAttribute
Remetente de e-mail personalizado

CustomEmailSender_VerifyUserAttribute
Remetente personalizado SMS

CustomSMSSender_VerifyUserAttribute

Acionadores do Lambda para usuários locais do Amazon Cognito na interface do usuário hospedada

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 a interface do usuário hospedada.

Fontes locais de gatilho de usuário na interface do usuário hospedada
UI hospedada URI Gatilho do Lambda Fonte de gatilhos
/signup Pré-cadastro

PreSignUp_SignUp
Mensagem personalizada

CustomMessage_SignUp
Remetente de e-mail personalizado

CustomEmailSender_SignUp
Remetente personalizado SMS

CustomSMSSender_SignUp
/confirmuser Pós-confirmação

PostConfirmation_ConfirmSignUp
/login Pre authentication

PreAuthentication_Authentication
Definir o desafio de autenticação

DefineAuthChallenge_Authentication
Criar o desafio de autenticação

CreateAuthChallenge_Authentication
Geração de pré-token

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens
Migração de usuário

UserMigration_Authentication
Mensagem personalizada

CustomMessage_Authentication
Remetente de e-mail personalizado

CustomEmailSender_AccountTakeOverNotification

CustomEmailSender_Authentication
Remetente personalizado SMS

CustomSMSSender_Authentication
/forgotpassword Migração de usuário

UserMigration_ForgotPassword
Mensagem personalizada

CustomMessage_ForgotPassword
Remetente de e-mail personalizado

CustomEmailSender_ForgotPassword
Remetente personalizado SMS

CustomSMSSender_ForgotPassword
/confirmforgotpassword Pós-confirmação

PostConfirmation_ConfirmForgotPassword

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.

nota

Usuários federados podem usar a interface de usuário hospedada do Amazon Cognito para fazer login, ou você pode gerar uma solicitação para o Autorizar endpoint que os redireciona silenciosamente para a página de login do provedor de identidades. Você não pode cadastrar usuários federados com os grupos de usuários do Amazon Cognito. API

Fontes de acionador de usuário federado
Evento de login Gatilho do Lambda Fonte de gatilhos
Primeiro login Pré-cadastro

PreSignUp_ExternalProvider
Pós-confirmação

PostConfirmation_ConfirmSignUp
Geração de pré-token

TokenGeneration_HostedAuth
Logins subsequentes Pre authentication

PreAuthentication_Authentication
Post authentication

PostAuthentication_Authentication
Geração de pré-token

TokenGeneration_HostedAuth

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.

Acionadores de inscrição, confirmação e login (autenticação)
Trigger triggerSource valor Evento
Pré-cadastro PreSignUp_SignUp Pré-cadastro.
Pré-cadastro PreSignUp_AdminCreateUser Pré-cadastro quando um administrador cria um novo usuário.
Pré-cadastro PreSignUp_ExternalProvider Pré-cadastro para provedores de identidade externos.
Pós-confirmação PostConfirmation_ConfirmSignUp Confirmação pós-cadastro.
Pós-confirmação PostConfirmation_ConfirmForgotPassword Confirmação após esquecimento de senha.
Pre authentication PreAuthentication_Authentication Pré-autenticação.
Post authentication PostAuthentication_Authentication Pós-autenticação.
Acionadores de desafio de autenticação personalizado
Trigger triggerSource valor Evento
Definir o desafio de autenticação DefineAuthChallenge_Authentication Definir o desafio de autenticação.
Criar o desafio de autenticação CreateAuthChallenge_Authentication Criar desafio de autenticação.
Verificar desafio de autenticação VerifyAuthChallengeResponse_Authentication Verificar a resposta do desafio de autenticação.
Acionadores de geração de pré-token
Trigger triggerSource valor Evento
Geração de pré-token TokenGeneration_HostedAuth O Amazon Cognito autentica o usuário na página de login da interface do usuário hospedada.
Geração de pré-token TokenGeneration_Authentication Fluxos completos de autenticação do usuário.
Geração de pré-token TokenGeneration_NewPasswordChallenge O administrador cria o usuário. O Amazon Cognito invoca isso quando o usuário precisa alterar uma senha temporária.
Geração de pré-token TokenGeneration_AuthenticateDevice Final da autenticação do dispositivo de um usuário.
Geração de pré-token TokenGeneration_RefreshTokens O usuário tenta atualizar a identidade e acessar tokens.
Acionadores de migração do usuário
Trigger triggerSource valor Evento
Migração do usuário UserMigration_Authentication Migração de usuários no momento de fazer login.
Migração do usuário UserMigration_ForgotPassword Migração de usuários durante o fluxo de esquecimento de senha.
Acionadores de mensagem personalizada
Trigger triggerSource valor Evento
Mensagem personalizada CustomMessage_SignUp Mensagem personalizada quando um usuário se cadastra no grupo de usuários.
Mensagem personalizada CustomMessage_AdminCreateUser Mensagem personalizada quando você cria um usuário como administrador e o Amazon Cognito envia uma senha temporária.
Mensagem personalizada CustomMessage_ResendCode Mensagem personalizada quando o usuário existente solicita um novo código de confirmação.
Mensagem personalizada CustomMessage_ForgotPassword Mensagem personalizada quando o usuário solicita uma redefinição de senha.
Mensagem personalizada CustomMessage_UpdateUserAttribute Mensagem personalizada quando um usuário altera o endereço de e-mail ou número de telefone e o Amazon Cognito envia ]um código de verificação.
Mensagem personalizada CustomMessage_VerifyUserAttribute Mensagem personalizada quando um usuário adiciona um endereço de e-mail ou um número de telefone e o Amazon Cognito envia um código de verificação.
Mensagem personalizada CustomMessage_Authentication Mensagem personalizada quando um usuário que configurou faz SMS MFA login.