Acionador do Lambda de remetente personalizado de SMS - Amazon Cognito
Parâmetros do acionador do Lambda de remetente personalizado de SMSAtivar o acionador do Lambda de remetente personalizado de SMSExemplo de códigoAvaliar os recursos de mensagem SMS com uma função de remetente personalizado de SMSFontes de acionador do Lambda remetente personalizado de SMS

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 personalizado de SMS

Quando você atribui um acionador de remetente de SMS 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 SMS. Com um gatilho de remetente personalizado, sua AWS Lambda função pode enviar notificações por SMS 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 SMS do grupo de usuários.

nota

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

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, que são senhas temporárias, códigos de verificação e códigos de autorização, e usa essa chave do KMS para criptografá-los. Depois, você pode usar a operação Descriptografar da API na função do 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 permissões kms:Decrypt para a chave do KMS ao perfil da função do 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. A entidade principal do IAM que atualiza ou cria um grupo de usuários com um acionador de remetente personalizado deve ter permissão para criar uma concessão para a chave do KMS. O trecho LambdaConfig a seguir atribui funções personalizadas de remetente de SMS e 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 SMS

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

Parâmetros de solicitação do remetente personalizado de SMS

type

A versão da solicitação. Para um evento de remetente personalizado de SMS, o valor dessa string é sempre customSMSSenderRequestV1.

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 ao acionador da função do Lambda de remetente personalizado de SMS. Para passar esses dados para sua função Lambda, você pode usar o ClientMetadata parâmetro nas ações AdminRespondToAuthChallengee da RespondToAuthChallengeAPI. O Amazon Cognito não inclui dados do ClientMetadata parâmetro AdminInitiateAuthe operações de InitiateAuthAPI na solicitação que ele passa para a função de pós-autenticação.

userAttributes

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

Parâmetros de resposta do remetente personalizado de SMS

O Amazon Cognito não espera nenhuma outra informação de retorno na resposta. Sua função pode usar operações de API para consultar e modificar seus recursos ou registrar metadados de eventos em um sistema externo.

Ativar o acionador do Lambda de remetente personalizado de SMS

É possível configurar um acionador de remetente personalizado de e-mail que usa lógica personalizada para enviar mensagens de SMS ao grupo de usuários. O procedimento a seguir atribui um acionador de SMS personalizado, um acionador de e-mail personalizado ou ambos ao seu grupo de usuários. Depois de adicionar o acionador de remetente de SMS personalizado, o Amazon Cognito sempre envia atributos do usuário, incluindo o número de telefone e o código único para a função do Lambda, em vez do comportamento padrão que envia uma mensagem SMS com o Amazon Simple Notification Service.

Importante

O Amazon Cognito faz escapes de caracteres reservados de HTML < (&lt;) e > (&gt;) na senha temporária do 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 acesso à entidade principal cognito-idp.amazonaws.com do serviço Amazon Cognito para criptografar códigos com a chave do KMS.

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

    {
    "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 o SDK de criptografia da AWS para criptografar os segredos, as senhas temporárias e os códigos que autorizam as solicitações de API dos usuários.

    1. Atribua um perfil do IAM à função do Lambda que tenha, no mínimo, as permissões kms:Decrypt para a chave do KMS.

  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. Depois, envie o código, sua própria mensagem personalizada e o número de telefone de destino para a API personalizada que entrega a mensagem.

  6. Adicione o AWS Encryption SDK à sua função Lambda. Para ter mais informações, consulte Linguagens de programação do AWS  Encryption SDK. 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 a função com as dependências do SDK e faça upload da função para o 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 parâmetro CustomSMSSender ou CustomEmailSender em uma solicitação de API do UpdateUserPool. A operação de API UpdateUserPool exige todos os parâmetros do grupo de usuários e os parâmetros que você deseja modificar. 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 ter 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 acionador do Lambda de remetente personalizado com uma solicitação da API UpdateUserPool, omita o parâmetro CustomSMSSender ou CustomEmailSender do corpo da solicitação que contém o restante da configuração do grupo de usuários.

Exemplo de código

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

KEY_ALIAS

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

KEY_ARN

O nome do recurso da Amazon (ARN) da chave do KMS que você deseja usar para criptografar e descriptografar os códigos dos 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 == 'CustomSMSSender_SignUp'){
		//Send an SMS message to your user via a custom provider.
		//Include the temporary password in the message.
	}
	else if(event.triggerSource == 'CustomSMSSender_ResendCode'){
	}
	else if(event.triggerSource == 'CustomSMSSender_ForgotPassword'){
	}
	else if(event.triggerSource == 'CustomSMSSender_UpdateUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_VerifyUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AdminCreateUser'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AccountTakeOverNotification'){
	}
	return;
};

Avaliar os recursos de mensagem SMS com uma função de remetente personalizado de SMS

Uma função do Lambda de remetente personalizado de SMS aceitará as mensagens SMS que seu grupo de usuários enviar e fornecerá o conteúdo com base em sua lógica personalizada. O Amazon Cognito envia o Parâmetros do acionador do Lambda de remetente personalizado de SMS para sua função. Sua função pode fazer o que você quiser com essas informações. Por exemplo, você pode enviar o código a um tópico do Amazon Simple Notification Service (Amazon SNS). Um assinante de tópicos do Amazon SNS pode ser uma mensagem SMS, um endpoint HTTPS ou um endereço de e-mail.

Para criar um ambiente de teste para mensagens SMS do Amazon Cognito com uma função Lambda personalizada do remetente de SMS, amazon-cognito-user-poolconsulte development-and-testing-with - sms-redirected-to-email - na biblioteca aws-samples em. GitHub O repositório contém AWS CloudFormation modelos que podem criar um novo grupo de usuários ou trabalhar com um grupo de usuários que você já tem. Esses modelos criam funções do Lambda e um tópico do Amazon SNS. A função do Lambda que o modelo atribui como um acionador de remetente personalizado de SMS redireciona para o tópico do Amazon SNS as mensagens SMS que você envia aos assinantes.

Quando você implanta essa solução em um grupo de usuários, todas as mensagens que o Amazon Cognito geralmente envia pelo sistema de mensagens SMS são enviadas pela função do Lambda a um endereço de e-mail central. Use essa solução para personalizar e visualizar mensagens SMS e testar os eventos do grupo de usuários que fazem com que o Amazon Cognito envie uma mensagem SMS. Depois de concluir seus testes, reverta a CloudFormation pilha ou remova a atribuição personalizada da função de remetente de SMS do seu grupo de usuários.

Importante

Não use os modelos em amazon-cognito-user-pool- development-and-testing-with - sms-redirected-to-email para criar um ambiente de produção. A função do Lambda de remetente personalizado de SMS na solução simula mensagens SMS, mas envia todas elas a um único endereço de e-mail central. Antes de enviar mensagens SMS em um grupo de usuários do Amazon Cognito de produção, você deve preencher os requisito s mostrados em SMSconfigurações de mensagem para grupos de usuários do Amazon Cognito.

Fontes de acionador do Lambda remetente personalizado de SMS

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

TriggerSource value Evento
CustomSMSSender_SignUp Um usuário se cadastra e o Amazon Cognito envia uma mensagem de boas-vindas.
CustomSMSSender_ForgotPassword Um usuário solicita um código para redefinir a senha.
CustomSMSSender_ResendCode Um usuário solicita um novo código para confirmar seu registro.
CustomSMSSender_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.
CustomSMSSender_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.
CustomSMSSender_Authentication Um usuário configurado com autenticação multifator (MFA) de SMS faz login.
CustomSMSSender_AdminCreateUser Você cria um usuário em seu grupo de usuários e o Amazon Cognito envia uma senha temporária.