Acionador do Lambda de mensagem personalizada - Amazon Cognito

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 mensagem personalizada

O Amazon Cognito invoca esse acionador antes de enviar um e-mail, uma mensagem de verificação de telefone ou um código de autenticação multifator (MFA). Você pode personalizar a mensagem dinamicamente com o acionador de mensagem personalizado. É possível editar mensagens personalizadas estáticas na guia Message Customizations (Personalizações de mensagem) do console do Amazon Cognito.

A solicitação inclui codeParameter. Essa string funciona como espaço reservado no código que o Amazon Cognito fornece ao usuário. Insira a string codeParameter no corpo da mensagem, na posição em que você deseja que o código de verificação apareça. Quando o Amazon Cognito recebe essa resposta, ele substitui a string codeParameter pelo código de verificação real.

nota

Uma função do Lambda de mensagem personalizada com o acionador CustomMessage_AdminCreateUser retorna um nome de usuário e um código de verificação. Como um usuário criado pelo administrador deve receber tanto o nome de usuário quanto o código, a resposta da função deve incluir ambos, request.usernameParameter e request.codeParameter.

Fontes do acionador do Lambda de mensagem personalizada

Valor de triggerSource Evento
CustomMessage_SignUp Custom message – Para enviar o código de confirmação após cadastro.
CustomMessage_AdminCreateUser Custom message – Para enviar a senha temporária a um novo usuário.
CustomMessage_ResendCode Custom message – Para reenviar o código de confirmação a um usuário existente.
CustomMessage_ForgotPassword Custom message – Para enviar o código de confirmação da solicitação de esquecimento de senha.
CustomMessage_UpdateUserAttribute Custom message – Quando um e-mail ou número de telefone de um usuário for alterado, esse trigger enviará um código de verificação automaticamente ao usuário. Não pode ser usado para outros atributos.
CustomMessage_VerifyUserAttribute Mensagem personalizada – Este trigger envia um código de verificação ao usuário quando solicitado manualmente para um novo e-mail ou número de telefone.
CustomMessage_Authentication Custom message – Para enviar o código MFA durante a autenticação.

Parâmetros do acionador do Lambda de mensagem personalizada

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": { "userAttributes": { "string": "string", . . . } "codeParameter": "####", "usernameParameter": "string", "clientMetadata": { "string": "string", . . . } }, "response": { "smsMessage": "string", "emailMessage": "string", "emailSubject": "string" } }

Parâmetros de solicitação de mensagem personalizada

userAttributes

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

codeParameter

Uma string a ser usada como espaço reservado do código de verificação na mensagem personalizada.

usernameParameter

O nome do usuário. O Amazon Cognito inclui esse parâmetro em solicitações geradas por usuários criados pelo administrador.

clientMetadata

Um ou mais pares de chave-valor que você pode fornecer como entrada personalizada para a função Lambda especificada para o acionador de mensagem personalizada. A solicitação que invoca uma função de mensagem personalizada não inclui dados transmitidos no ClientMetadata parâmetro AdminInitiateAuthe operações de InitiateAuthAPI. Para passar esses dados para sua função Lambda, você pode usar o ClientMetadata parâmetro nas seguintes ações de API:

Parâmetros de resposta de mensagem personalizada

Na resposta, especifique o texto personalizado a ser usado em mensagens para seus usuários. Para as restrições de string que o Amazon Cognito aplica a esses parâmetros, consulte. MessageTemplateType

smsMessage

A mensagem SMS personalizada a ser enviada a seus usuários. Deve incluir o valor de codeParameter recebido na solicitação.

emailMessage

A mensagem de e-mail personalizada a ser enviada a seus usuários. Você pode usar a formatação HTML no parâmetro emailMessage. Deve incluir o valor de codeParameter recebido na solicitação como a variável {####}. O Amazon Cognito pode usar o parâmetro emailMessage somente se o atributo EmailSendingAccount do grupo de usuários for DEVELOPER. Se o atributo EmailSendingAccount do grupo de usuários não for DEVELOPER e um parâmetro emailMessage for retornado, o Amazon Cognito vai gerar um código de erro 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. Ao escolher o Amazon Simple Email Service (Amazon SES) para enviar mensagens de e-mail, o atributo EmailSendingAccount de um grupo de usuários é DEVELOPER. Do contrário, o valor será COGNITO_DEFAULT.

emailSubject

A linha de assunto da mensagem personalizada. Você só pode usar o emailSubject parâmetro se o EmailSendingAccount atributo do grupo de usuários forDEVELOPER. Se o atributo EmailSendingAccount do grupo de usuários não for DEVELOPER e o Amazon Cognito retornar um parâmetro emailSubject, o Amazon Cognito vai gerar um código de erro 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. O atributo EmailSendingAccount de um grupo de usuários é DEVELOPER ao escolher o Amazon Simple Email Service (Amazon SES) para enviar mensagens de e-mail. Do contrário, o valor será COGNITO_DEFAULT.

Exemplo de mensagem personalizada de cadastro

Esse exemplo de função do Lambda personaliza um e-mail ou mensagem SMS quando o serviço requer que uma aplicação envie um código de verificação ao usuário.

O Amazon Cognito pode invocar um acionador do Lambda em vários eventos: no pós-registro, ao reenviar um código de verificação, ao recuperar uma senha esquecida ou ao verificar um atributo de usuário. A resposta inclui mensagens para SMS e e-mail. A mensagem deve incluir o parâmetro de código "####". Esse parâmetro é o espaço reservado do código de verificação que o usuário recebe.

A mensagem de e-mail tem um comprimento máximo de 20 mil caracteres UTF-8. Esse tamanho inclui o código de verificação. Você pode usar etiquetas HTML nessas mensagens de e-mail.

A mensagem SMS tem um comprimento máximo de 140 caracteres UTF-8. Esse tamanho inclui o código de verificação.

Node.js
const handler = async (event) => { if (event.triggerSource === "CustomMessage_SignUp") { const message = `Thank you for signing up. Your confirmation code is ${event.request.codeParameter}.`; event.response.smsMessage = message; event.response.emailMessage = message; event.response.emailSubject = "Welcome to the service."; } return event; }; export { handler };

O Amazon Cognito transmite informações de evento para a função do Lambda. A função retorna o mesmo objeto de evento para o Amazon Cognito, com as alterações na resposta. No console do Lambda, você pode configurar um evento de teste com dados relevantes para o acionador do Lambda. A seguir, é mostrado um evento de teste para esse exemplo de código:

JSON
{ "version": 1, "triggerSource": "CustomMessage_SignUp/CustomMessage_ResendCode/CustomMessage_ForgotPassword/CustomMessage_VerifyUserAttribute", "region": "<region>", "userPoolId": "<userPoolId>", "userName": "<userName>", "callerContext": { "awsSdk": "<calling aws sdk with version>", "clientId": "<apps client id>", ... }, "request": { "userAttributes": { "phone_number_verified": false, "email_verified": true, ... }, "codeParameter": "####" }, "response": { "smsMessage": "<custom message to be sent in the message with code parameter>" "emailMessage": "<custom message to be sent in the message with code parameter>" "emailSubject": "<custom email subject>" } }

Exemplo de mensagem personalizada para criação de usuário pelo administrador

A solicitação que o Amazon Cognito enviou para este exemplo de mensagem personalizada da função Lambda tem um triggerSource valor e um nome de usuário CustomMessage_AdminCreateUser e uma senha temporária. A função é preenchida a ${event.request.codeParameter} partir da senha temporária na solicitação e ${event.request.usernameParameter} do nome de usuário na solicitação.

Suas mensagens personalizadas devem inserir os valores de codeParameter e usernameParameter dentro smsMessage e emailMessage no objeto de resposta. Neste exemplo, a função grava a mesma mensagem nos campos de resposta event.response.smsMessage event.response.emailMessage e.

A mensagem de e-mail tem um comprimento máximo de 20 mil caracteres UTF-8. Esse tamanho inclui o código de verificação. Você pode usar etiquetas HTML nesses e-mails. A mensagem SMS tem um comprimento máximo de 140 caracteres UTF-8. Esse tamanho inclui o código de verificação.

A resposta inclui mensagens para SMS e e-mail.

Node.js
const handler = async (event) => { if (event.triggerSource === "CustomMessage_AdminCreateUser") { const message = `Welcome to the service. Your user name is ${event.request.usernameParameter}. Your temporary password is ${event.request.codeParameter}`; event.response.smsMessage = message; event.response.emailMessage = message; event.response.emailSubject = "Welcome to the service"; } return event; }; export { handler }

O Amazon Cognito transmite informações de evento para a função do Lambda. A função retorna o mesmo objeto de evento para o Amazon Cognito, com as alterações na resposta. No console do Lambda, você pode configurar um evento de teste com dados relevantes para o acionador do Lambda. A seguir, é mostrado um evento de teste para esse exemplo de código:

JSON
{ "version": 1, "triggerSource": "CustomMessage_AdminCreateUser", "region": "<region>", "userPoolId": "<userPoolId>", "userName": "<userName>", "callerContext": { "awsSdk": "<calling aws sdk with version>", "clientId": "<apps client id>", ... }, "request": { "userAttributes": { "phone_number_verified": false, "email_verified": true, ... }, "codeParameter": "####", "usernameParameter": "username" }, "response": { "smsMessage": "<custom message to be sent in the message with code parameter and username parameter>" "emailMessage": "<custom message to be sent in the message with code parameter and username parameter>" "emailSubject": "<custom email subject>" } }