Acionador do Lambda de remetente de e-mail personalizado - Amazon Cognito
Parâmetros do acionador do Lambda de remetente personalizado de e-mailAtivar o acionador do Lambda de remetente personalizado de e-mailFontes do acionador de remetente de e-mail personalizado

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á.

Acionador do Lambda de remetente de e-mail personalizado

Quando você atribui um acionador de remetente de e-mail personalizado ao grupo de usuários, o Amazon Cognito invoca uma função do Lambda em vez do comportamento padrão quando um evento do usuário exige que ele envie uma mensagem de e-mail. Com um gatilho de remetente personalizado, sua AWS Lambda função pode enviar notificações por e-mail para seus usuários por meio de um método e provedor de sua escolha. O código personalizado da função deve processar e entregar todas as mensagens de e-mail do grupo de usuários.

Esse gatilho serve para cenários em que talvez você queira ter maior controle sobre como seu grupo de usuários envia mensagens de e-mail. Sua função Lambda pode personalizar a chamada para as SES API operações da Amazon, por exemplo, quando você deseja gerenciar várias identidades verificadas ou cruzar. Regiões da AWS Sua função também pode redirecionar mensagens para outro meio de entrega ou serviço de terceiros.

nota

No momento, não é possível atribuir acionadores de remetente personalizados no console do Amazon Cognito. Você pode atribuir um gatilho com o LambdaConfig parâmetro em uma UpdateUserPool API solicitação CreateUserPool or.

Para configurar esse acionador, execute as seguintes etapas:

  1. Crie uma chave de criptografia simétrica em AWS Key Management Service (AWS KMS). O Amazon Cognito gera segredos — senhas temporárias, códigos de verificação e códigos de confirmação — e usa essa chave para criptografar os segredos. KMS Em seguida, você pode usar a API operação Decrypt em sua função Lambda para descriptografar os segredos e enviá-los ao usuário em texto simples. AWS Encryption SDKÉ uma ferramenta útil para AWS KMS operações em sua função.

  2. Crie uma função do Lambda que você deseja atribuir como acionador de remetente personalizado. Conceda kms:Decrypt permissões para sua KMS chave para a função Lambda.

  3. Conceda à entidade principal cognito-idp.amazonaws.com do serviço do Amazon Cognito acesso para invocar a função do Lambda.

  4. Escreva um código da função do Lambda que direcione suas mensagens para métodos de entrega personalizados ou provedores de terceiros. Para entregar o código de verificação ou confirmação do usuário, o Base64 decodifica e descriptografa o valor do parâmetro code na solicitação. Essa operação produz um código ou senha em texto simples que você deve incluir na mensagem.

  5. Atualize o grupo de usuários para que ele use um acionador do Lambda de remetente personalizado. O IAM diretor que atualiza ou cria um grupo de usuários com um gatilho de remetente personalizado deve ter permissão para criar uma concessão para sua KMS chave. O LambdaConfig trecho a seguir atribui funções personalizadas SMS e de remetente de e-mail.

    "LambdaConfig": {
   "KMSKeyID": "arn:aws:kms:us-east-1:123456789012:key/a6c4f8e2-0c45-47db-925f-87854bc9e357",
   "CustomEmailSender": {
      "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
      "LambdaVersion": "V1_0"
   },
   "CustomSMSSender": {
      "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
      "LambdaVersion": "V1_0"
   }

Parâmetros do acionador do Lambda de remetente personalizado de e-mail

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
{
    "request": {
        "type": "customEmailSenderRequestV1",
        "code": "string",
        "clientMetadata": {
            "string": "string",
             . . .
            },
        "userAttributes": {
            "string": "string",
            . . .
         }
}

Parâmetros de solicitação do remetente personalizado de e-mail

tipo

A versão da solicitação. Para um evento de remetente personalizado de e-mail, o valor dessa string é sempre customEmailSenderRequestV1.

Código

O código criptografado que sua função pode descriptografar e enviar ao usuário.

clientMetadata

Um ou mais pares de chave-valor que você pode fornecer como entrada personalizada à função do Lambda para o acionador de migração do usuário. Para passar esses dados para sua função Lambda, você pode usar o ClientMetadata parâmetro nas ações AdminRespondToAuthChallengee. RespondToAuthChallengeAPI O Amazon Cognito não inclui dados do ClientMetadata parâmetro AdminInitiateAuthe InitiateAuthAPIoperações na solicitação que ele passa para a função de pós-autenticação.

nota

O Amazon Cognito envia ClientMetadata para funções personalizadas de gatilho de e-mail em eventos com as seguintes fontes de gatilho:

  • CustomEmailSender_ForgotPassword

  • CustomEmailSender_SignUp

O Amazon Cognito não envia ClientMetadata eventos de gatilho com a fonte. CustomEmailSender_AccountTakeOverNotification

userAttributes

Um ou mais pares de chave-valor que representam atributos de usuário.

Parâmetros de resposta do remetente personalizado de e-mail

O Amazon Cognito não espera nenhuma outra informação de retorno na resposta do remetente personalizado de e-mail. Sua função Lambda deve interpretar o evento, descriptografar o código e, em seguida, entregar o conteúdo da mensagem. Uma função típica reúne uma mensagem de e-mail e a direciona para um retransmissor de terceirosSMTP.

Ativar o acionador do Lambda de remetente personalizado de e-mail

Para configurar um acionador de remetente personalizado de e-mail que usa lógica personalizada para enviar mensagens de e-mail ao grupo de usuários, ative-o da maneira a seguir. O procedimento a seguir atribui um gatilho de e-mail personalizado, um SMS gatilho personalizado ou ambos ao seu grupo de usuários. Depois de adicionar o gatilho de remetente de e-mail personalizado, o Amazon Cognito sempre envia atributos do usuário, incluindo o endereço de e-mail e o código único para a função do Lambda, quando, de outra forma, enviaria uma mensagem de e-mail com o Amazon Simple Email Service.

Importante

Amazon Cognito HTML - escapa caracteres reservados como < (&lt;) e > (&gt;) na senha temporária do seu usuário. Esses caracteres podem aparecer em senhas temporárias que o Amazon Cognito envia para à função personalizada de remetente de e-mail, mas não aparecem nos códigos de verificação temporários. Para enviar senhas temporárias, a função do Lambda deve liberar esses caracteres depois de decifrar a senha e antes de enviar a mensagem ao usuário.

  1. Crie uma chave de criptografia no AWS KMS. Essa chave criptografa senhas temporárias e códigos de autorização gerados pelo Amazon Cognito. Depois, é possível descriptografar esses segredos na função do Lambda de remetente personalizado para enviá-los ao usuário em texto não criptografado.

  2. Conceda cognito-idp.amazonaws.com acesso principal ao serviço Amazon Cognito para criptografar códigos com a chave. KMS

    Aplique a seguinte política baseada em recursos à sua KMS chave.

    {
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {
            "Service": "cognito-idp.amazonaws.com"
        },
        "Action": "kms:CreateGrant",
        "Resource": "arn:aws:kms:us-west-2:111222333444:key/1example-2222-3333-4444-999example",
        "Condition": {
            "StringEquals": {
                "aws:SourceAccount": "111222333444"
            },
            "ArnLike": {
                "aws:SourceArn": "arn:aws:cognito-idp:us-west-2:111222333444:userpool/us-east-1_EXAMPLE"
            }
        }
    }]
}

  3. Crie uma função do Lambda para o acionador de remetente personalizado. O Amazon Cognito usa a AWS criptografia SDK para criptografar os segredos, as senhas temporárias e os códigos que autorizam as solicitações dos seus usuários. API

    1. Atribua uma IAM função à sua função Lambda que tenha, no mínimo, kms:Decrypt permissões para sua KMS chave.

  4. Conceda à entidade principal cognito-idp.amazonaws.com do serviço do Amazon Cognito acesso para invocar a função do Lambda.

    O AWS CLI comando a seguir concede ao Amazon Cognito permissão para invocar sua função Lambda:

    
        aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com

  5. Componha o código da função do Lambda para enviar as mensagens. O Amazon Cognito usa para AWS Encryption SDK criptografar segredos antes que o Amazon Cognito envie os segredos para a função Lambda personalizada do remetente. Em sua função, decifre o segredo e processe todos os metadados relevantes. Em seguida, envie o código, sua própria mensagem personalizada e o número de telefone de destino para a API pessoa que entrega sua mensagem.

  6. Adicione o AWS Encryption SDK à sua função Lambda. Para obter mais informações, consulte SDKLinguagens AWS de programação de criptografia. Para atualizar o pacote do Lambda, conclua as etapas a seguir.

    1. Exporte a função do Lambda como um arquivo .zip no AWS Management Console.

    2. Abra sua função e adicione AWS Encryption SDK o. Para ter mais informações e links de download, consulte Linguagens de programação do AWS Encryption SDK no Guia do desenvolvedor do AWS Encryption SDK .

    3. Compacte sua função com suas SDK dependências e carregue a função no Lambda. Para obter mais informações, consulte Implantar funções do Lambda como arquivos .zip no Guia do desenvolvedor do AWS Lambda .

  7. Atualize o grupo de usuários para adicionar acionadores do Lambda de remetente personalizado. Inclua um CustomEmailSender parâmetro CustomSMSSender or em uma UpdateUserPool API solicitação. A UpdateUserPool API operação requer todos os parâmetros do seu grupo de usuários e os parâmetros que você deseja alterar. Se você não fornecer todos os parâmetros relevantes, o Amazon Cognito assumirá os valores padrão para todos os parâmetros ausentes. Conforme demonstrado no exemplo a seguir, inclua entradas para todas as funções do Lambda que você deseja adicionar ou manter no grupo de usuários. Para obter mais informações, consulte Atualizar a configuração do grupo de usuários.

    
    #Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing 
    #user pool configurations.
              
      --lambda-config "PreSignUp=lambda-arn, \
                       CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                       CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                       KMSKeyID=key-id"

Para remover um gatilho Lambda personalizado do remetente com update-user-pool AWS CLI um, omita CustomSMSSender o parâmetro CustomEmailSender --lambda-config or e inclua todos os outros gatilhos que você deseja usar com seu grupo de usuários.

Para remover um gatilho Lambda personalizado do remetente com UpdateUserPool API uma solicitação, omita CustomSMSSender o parâmetro CustomEmailSender or do corpo da solicitação que contém o restante da configuração do seu grupo de usuários.

Exemplo de código

O exemplo de Node.js a seguir processa um evento de mensagem de e-mail na função do Lambda de remetente personalizado de e-mail. Esse exemplo pressupõe que a função tenha duas variáveis de ambiente definidas.

KEY_ALIAS

O alias da KMS chave que você deseja usar para criptografar e descriptografar os códigos dos seus usuários.

KEY_ARN

O Amazon Resource Name (ARN) da KMS chave que você deseja usar para criptografar e descriptografar os códigos dos seus usuários.

const AWS = require('aws-sdk');
const b64 = require('base64-js');
const encryptionSdk = require('@aws-crypto/client-node');
//Configure the encryption SDK client with the KMS key from the environment variables.
const { encrypt, decrypt } = encryptionSdk.buildClient(encryptionSdk.CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT);
const generatorKeyId = process.env.KEY_ALIAS;
const keyIds = [ process.env.KEY_ARN ];
const keyring = new encryptionSdk.KmsKeyringNode({ generatorKeyId, keyIds })
exports.handler = async (event) => {
	//Decrypt the secret code using encryption SDK.
	let plainTextCode;
	if(event.request.code){
		const { plaintext, messageHeader } = await decrypt(keyring, b64.toByteArray(event.request.code));
		plainTextCode = plaintext
	}
	//PlainTextCode now contains the decrypted secret.
	if(event.triggerSource == 'CustomEmailSender_SignUp'){
		//Send an email message to your user via a custom provider.
		//Include the temporary password in the message.
	}
	else if(event.triggerSource == 'CustomEmailSender_Authentication'){
         //Send an MFA message.
	}
	else if(event.triggerSource == 'CustomEmailSender_ResendCode'){
         //Send a message with next steps for password reset.
	}
	else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){
         //Send a message with next steps for password reset.
	}
	else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){
         //Send a message with next steps for confirming the new attribute.
	}
	else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){
         //Send a message with next steps for confirming the new attribute.
	}
	else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){
         //Send a message with next steps for signing in with a new user profile.
	}
	else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){
         //Send a message describing the threat protection event and next steps.
	}
	return;
};

Fontes do acionador do Lambda de remetente de e-mail personalizado

A tabela a seguir mostra o evento de acionamento de fontes de acionadores de e-mail personalizado no código do Lambda.

TriggerSource value Evento
CustomEmailSender_SignUp Um usuário se cadastra e o Amazon Cognito envia uma mensagem de boas-vindas.
CustomEmailSender_Authentication Um usuário faz login e o Amazon Cognito envia um código de autenticação multifatorial ()MFA.
CustomEmailSender_ForgotPassword Um usuário solicita um código para redefinir a senha.
CustomEmailSender_ResendCode Um usuário solicita um código de substituição para redefinir a senha.
CustomEmailSender_UpdateUserAttribute Um usuário atualiza um endereço de e-mail ou um atributo de número de telefone e o Amazon Cognito envia um código para verificar o atributo.
CustomEmailSender_VerifyUserAttribute Um usuário cria um endereço de e-mail ou um atributo de número de telefone e o Amazon Cognito envia um código para verificar o atributo.
CustomEmailSender_AdminCreateUser Você cria um usuário em seu grupo de usuários e o Amazon Cognito envia uma senha temporária.
CustomEmailSender_AccountTakeOverNotification O Amazon Cognito detecta uma tentativa de tomada de controle de uma conta de usuário e envia uma notificação ao usuário.