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.

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	Operação	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 terceiros de e-mail e SMS	Acionadores do Lambda remetente personalizado	Usa um provedor de terceiros para enviar mensagens de e-mail e SMS

Tópicos

• Considerações importantes
• Como adicionar um acionador do Lambda do grupo de usuários
• Evento de acionador do Lambda do grupo de usuários
• Parâmetros comuns do acionador do Lambda do grupo de usuários
• Conectar operações de API a gatilhos do Lambda
• Conectar gatilhos do Lambda às operações funcionais do grupo de usuários
• Acionador do Lambda de pré-cadastro
• Acionador do Lambda de pós-confirmação
• Acionador do Lambda de pré-autenticação
• Acionador do Lambda de pós-autenticação
• Acionadores do Lambda de desafio personalizado de autenticação
• Acionador do Lambda antes da geração do token
• Migrar o acionador do Lambda do usuário
• Acionador do Lambda de mensagem personalizada
• Acionadores do Lambda remetente personalizado

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 hierarquia JSON 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 Modelo de programação do Lambda no Guia do desenvolvedor do AWS Lambda.

  O Amazon Cognito não repete chamadas de função que retornam um erro de invocação com um código de status HTTP de 500 a 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 Lidar com erros e novas tentativas automáticas no 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, é possível associar uma versão da função a um alias e definir o acionador LambdaArn para o ARN do alias em uma solicitação de API CreateUserPool ou UpdateUserPool. 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. A API de grupos de usuários do Amazon Cognito retorna erros do acionador 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() para registrar qualquer informação confidencial ou de depuração no CloudWatch Logs. 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 do Lambda a outra Conta da AWS como um acionador para seu grupo de usuários. Você deve adicionar acionadores entre contas com as operações da API CreateUserPool e UpdateUserPool ou seus equivalentes no AWS CloudFormation e na AWS CLI. Você não pode adicionar funções entre 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. É possível adicionar permissões do console do Lambda ou usar a operação de API AddPermission do Lambda.

  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 Assign Lambda function (Atribuir função do Lambda) e selecione uma função na mesma Região da AWS do seu grupo de usuários.

   nota

   Se suas credenciais do AWS Identity and Access Management (IAM) tiverem permissão para atualizar a função do 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 permissões suficientes do IAM, 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 o CloudWatch no console do Lambda para registrar sua função do Lambda. Para obter mais informações, consulte Acessar o CloudWatch Logs 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 uma descrição de cada triggerSource, consulte Conectar gatilhos do Lambda às operações funcionais do grupo de usuários.

region

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

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 awsSdkVersion e clientId.

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 solicitação de API do 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": "[e-mail]".

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.

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 por meio da API de grupos de usuários do Amazon Cognito, da interface do usuário hospedada 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 Usar a API de grupos de usuários e endpoints de grupo de usuários do Amazon Cognito. 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.

Fontes locais de gatilho de usuário na API do Amazon Cognito
Operação de API	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 de SMS personalizado	CustomSMSSender_AdminCreateUser
SignUp	Pré-cadastro	PreSignUp_SignUp
	Mensagem personalizada	CustomMessage_SignUp
	Remetente de e-mail personalizado	CustomEmailSender_SignUp
	Remetente de SMS personalizado	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
	Remetente de SMS personalizado	CustomSMSSender_Authentication
ForgotPassword	Migração de usuário	UserMigration_ForgotPassword
	Mensagem personalizada	CustomMessage_ForgotPassword
	Remetente de e-mail personalizado	CustomEmailSender_ForgotPassword
	Remetente de SMS personalizado	CustomSMSSender_ForgotPassword
ConfirmForgotPassword	Pós-confirmação	PostConfirmation_ConfirmForgotPassword
UpdateUserAttributes AdminUpdateUserAttributes	Mensagem personalizada	CustomMessage_UpdateUserAttribute
	Remetente de e-mail personalizado	CustomEmailSender_UpdateUserAttribute
	Remetente de SMS personalizado	CustomSMSSender_UpdateUserAttribute
VerifyUserAttributes	Mensagem personalizada	CustomMessage_VerifyUserAttribute
	Remetente de e-mail personalizado	CustomEmailSender_VerifyUserAttribute
	Remetente de SMS personalizado	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
URI de interface hospedada	Gatilho do Lambda	Fonte de gatilhos
/signup	Pré-cadastro	PreSignUp_SignUp
	Mensagem personalizada	CustomMessage_SignUp
	Remetente de e-mail personalizado	CustomEmailSender_SignUp
	Remetente de SMS personalizado	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
	Remetente de SMS personalizado	CustomSMSSender_Authentication
/forgotpassword	Migração de usuário	UserMigration_ForgotPassword
	Mensagem personalizada	CustomMessage_ForgotPassword
	Remetente de e-mail personalizado	CustomEmailSender_ForgotPassword
	Remetente de SMS personalizado	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. Não é possível fazer login de usuários federados com a API de grupos de usuários do Amazon Cognito.

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	Valor função do LambdaSource	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	Valor função do LambdaSource	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	Valor função do LambdaSource	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	Valor função do LambdaSource	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	Valor função do LambdaSource	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 a MFA SMS faz login.