Déclencheur Lambda message personnalisé

Amazon Cognito appelle ce déclencheur avant d'envoyer un message de vérification ou un code d'authentification multifacteur (MFA) par e-mail ou par téléphone. Vous pouvez personnaliser le message de manière dynamique avec votre déclencheur de message personnalisé. Vous pouvez modifier les messages personnalisés statiques sous l'onglet Message Customizations (Personnalisation des messages) de la console Amazon Cognito.

La demande inclut codeParameter. Il s'agit d'une chaîne qui sert d'espace réservé pour le code remis par Amazon Cognito à l'utilisateur. Insérez la chaîne codeParameter dans le corps du message, à l'emplacement où vous souhaitez que le code de vérification apparaisse. Quand il reçoit cette réponse, Amazon Cognito remplace la chaîne codeParameter par le code de vérification réel.

Note

Une fonction Lambda de message personnalisé avec la source du déclencheur CustomMessage_AdminCreateUser renvoie un nom d'utilisateur et un code de vérification. Étant donné qu'un utilisateur créé par l'administrateur doit recevoir à la fois son nom d'utilisateur et son code, la réponse de votre fonction doit inclure à la fois request.usernameParameter et request.codeParameter.

Sources du déclencheur Lambda message personnalisé

Valeur triggerSource	Événement
CustomMessage_SignUp	Message personnalisé – Pour envoyer le code de confirmation après l'inscription.
CustomMessage_AdminCreateUser	Message personnalisé – Pour envoyer le mot de passe temporaire à un nouvel utilisateur.
CustomMessage_ResendCode	Message personnalisé – Pour renvoyer le code de confirmation à un utilisateur existant.
CustomMessage_ForgotPassword	Message personnalisé – Pour envoyer le code de confirmation suite à une demande de mot de passe oublié.
CustomMessage_UpdateUserAttribute	Message personnalisé – En cas de modification de l'e-mail ou du numéro de téléphone, ce déclencheur envoie automatiquement un code de vérification à l'utilisateur. Impossible à utiliser pour d'autres attributs.
CustomMessage_VerifyUserAttribute	Message personnalisé – Ce déclencheur envoie un code de vérification à l'utilisateur lorsque ce dernier en fait manuellement la demande concernant une nouvelle adresse e-mail ou un nouveau numéro de téléphone.
CustomMessage_Authentication	Message personnalisé – Pour envoyer le code MFA lors de l'authentification.

Paramètres du déclencheur Lambda message personnalisé

La demande qu'Amazon Cognito transmet à cette fonction Lambda est une combinaison des paramètres ci-dessous et des paramètres courants qu'Amazon Cognito ajoute à toutes les demandes.

JSON

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        }
        "codeParameter": "####",
        "usernameParameter": "string",
        "clientMetadata": {
            "string": "string",
            . . .
        }
    },
    "response": {
        "smsMessage": "string",
        "emailMessage": "string",
        "emailSubject": "string"
    }
}

Paramètres de demande de message personnalisé

userAttributes

Une ou plusieurs paires nom-valeur représentant des attributs utilisateur.

codeParameter

Chaîne que vous pouvez utiliser comme espace réservé pour le code de vérification dans le message personnalisé.

usernameParameter

Nom de l'utilisateur. Amazon Cognito inclut ce paramètre dans les demandes provenant d'utilisateurs créés par l'administrateur.

clientMetadata

Une ou plusieurs paires clé-valeur que vous pouvez fournir en tant qu'entrée personnalisée à la fonction Lambda que vous spécifiez pour le déclencheur de message personnalisé. La demande qui invoque une fonction de message personnalisée n'inclut pas les données transmises dans le ClientMetadata paramètre ni dans AdminInitiateAuthles opérations InitiateAuthd'API. Pour transmettre ces données à votre fonction Lambda, vous pouvez utiliser le ClientMetadata paramètre dans les actions d'API suivantes :

• AdminResetUserPassword

• AdminRespondToAuthChallenge

• AdminUpdateUserAttributes

• ForgotPassword

• GetUserAttributeVerificationCode

• ResendConfirmationCode

• SignUp

• UpdateUserAttributes

Paramètres de réponse de message personnalisé

Dans la réponse, spécifiez le texte personnalisé à utiliser dans les messages à vos utilisateurs. Pour connaître les contraintes de chaîne appliquées par Amazon Cognito à ces paramètres, consultez. MessageTemplateType

smsMessage

Message SMS personnalisé à envoyer à vos utilisateurs. Il doit inclure la valeur codeParameter que vous avez reçue dans la demande.

emailMessage

Message électronique personnalisé à envoyer à vos utilisateurs. Vous pouvez utiliser le formatage HTML dans le paramètre emailMessage. Il doit inclure la valeur codeParameter que vous avez reçue dans la demande en tant que variable {####}. Amazon Cognito peut utiliser le paramètre emailMessage seulement si l'attribut EmailSendingAccount du groupe d'utilisateurs est DEVELOPER. Si l'attribut EmailSendingAccount du groupe d'utilisateurs n'est pas DEVELOPER et qu'un paramètre emailMessage est renvoyé, Amazon Cognito génère un code d'erreur 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. Lorsque vous choisissez d'utiliser Amazon Simple Email Service (Amazon SES) pour envoyer des messages électroniques, l'attribut EmailSendingAccount d'un groupe d'utilisateurs est DEVELOPER. Sinon, la valeur est COGNITO_DEFAULT.

emailSubject

Ligne d'objet pour le message personnalisé. Vous ne pouvez utiliser le emailSubject paramètre que si l' EmailSendingAccountattribut du groupe d'utilisateurs estDEVELOPER. Si l'attribut EmailSendingAccount du groupe d'utilisateurs n'est pas DEVELOPER et qu'Amazon Cognito renvoie un paramètre emailSubject, Amazon Cognito génère un code d'erreur 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. L'attribut EmailSendingAccount d'un groupe d'utilisateurs est DEVELOPER quand vous choisissez d'utiliser Amazon Simple Email Service (Amazon SES) pour envoyer des messages électroniques. Sinon, la valeur est COGNITO_DEFAULT.

Exemple de message personnalisé pour l'inscription

Cette exemple de fonction Lambda personnalise un e-mail ou un SMS quand le service nécessite qu'une application envoie un code de vérification à l'utilisateur.

Amazon Cognito peut appeler un déclencheur Lambda lors de plusieurs événements : après l'inscription, lors du renvoi d'un code de vérification, lors de la récupération d'un mot de passe oublié ou lors de la vérification d'un attribut utilisateur. La réponse inclut des messages par SMS et e-mail. Le message doit inclure le paramètre de code "####". Ce paramètre est l'espace réservé pour le code de vérification que l'utilisateur reçoit.

La longueur maximale d'un message électronique est de 20 000 caractères UTF-8. Cette longueur inclut le code de vérification. Vous pouvez utiliser des balises HTML dans ces messages électroniques.

La longueur maximale d'un SMS est de 140 caractères UTF-8. Cette longueur inclut le code de vérification.

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 };

Amazon Cognito transmet les informations d’événement à votre fonction Lambda. Cette fonction renvoie alors le même objet d’événement à Amazon Cognito, avec d’éventuelles modifications dans la réponse. Dans la console Lambda, vous pouvez configurer un événement de test avec des données pertinentes pour votre déclencheur Lambda. Voici un événement de test pour cet exemple de code :

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>"
  }
}

Exemple de message personnalisé pour la création d'utilisateurs par les administrateurs

La demande envoyée par Amazon Cognito à cet exemple de fonction Lambda de message personnalisé comporte une triggerSource valeur, un nom d'utilisateur CustomMessage_AdminCreateUser et un mot de passe temporaire. La fonction est renseignée ${event.request.codeParameter} à partir du mot de passe temporaire de la demande et ${event.request.usernameParameter} du nom d'utilisateur de la demande.

Vos messages personnalisés doivent insérer les valeurs de codeParameter et usernameParameter dans smsMessage et emailMessage dans l'objet de réponse. Dans cet exemple, la fonction écrit le même message dans les champs de réponse event.response.smsMessage etevent.response.emailMessage.

La longueur maximale d'un message électronique est de 20 000 caractères UTF-8. Cette longueur inclut le code de vérification. Vous pouvez utiliser des balises HTML dans ces e-mails. La longueur maximale d'un SMS est de 140 caractères UTF-8. Cette longueur inclut le code de vérification.

La réponse inclut des messages par SMS et 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 }

Amazon Cognito transmet les informations d’événement à votre fonction Lambda. Cette fonction renvoie alors le même objet d’événement à Amazon Cognito, avec d’éventuelles modifications dans la réponse. Dans la console Lambda, vous pouvez configurer un événement de test avec des données pertinentes pour votre déclencheur Lambda. Voici un événement de test pour cet exemple de code :

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>"
  }
}