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 le déclencheur CustomMessage_AdminCreateUser renvoie un nom d'utilisateur et un code de vérification. La demande doit inclure à la fois request.usernameParameter et request.codeParameter.

Sources du déclencheur Lambda message personnalisé

Valeur triggerSource	Événement déclencheur
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é

Il s'agit des paramètres qu'Amazon Cognito transmet à cette fonction Lambda avec les informations d'événements figurant dans les paramètres communs.

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

Paramètre du nom d'utilisateur. Il s'agit d'un paramètre de demande obligatoire pour que l'administrateur puisse créer le flux d'utilisateur.

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 appelle une fonction de message personnalisé n'inclut pas les données transmises dans le paramètre ClientMetadata dans les opérations d'API AdminInitiateAuth et InitiateAuth. Pour transmettre ces données à votre fonction Lambda, vous pouvez utiliser le paramètre ClientMetadata 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.

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 pouvez utiliser le paramètre emailSubject 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'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

exports.handler = (event, context, callback) => {
    //
    if(event.userPoolId === "theSpecialUserPool") {
        // Identify why was this function invoked
        if(event.triggerSource === "CustomMessage_SignUp") {
            // Ensure that your message contains event.request.codeParameter. This is the placeholder for code that will be sent
            event.response.smsMessage = "Welcome to the service. Your confirmation code is " + event.request.codeParameter;
            event.response.emailSubject = "Welcome to the service";
            event.response.emailMessage = "Thank you for signing up. " + event.request.codeParameter + " is your verification code";
        }
        // Create custom message for other events
    }
    // Customize messages for other user pools

    // Return to Amazon Cognito
    callback(null, event);
};

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

Une fonction Lambda de message personnalisé avec le déclencheur CustomMessage_AdminCreateUser renvoie un nom d'utilisateur et un code de vérification. Pour cette raison, incluez à la fois request.usernameParameter et request.codeParameter dans le corps du message.

La valeur du paramètre de code #### est un espace réservé pour le mot de passe temporaire, et « username » est un espace réservé pour le nom d'utilisateur que votre 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 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

exports.handler = (event, context, callback) => {
    //
    if(event.userPoolId === "theSpecialUserPool") {
        // Identify why was this function invoked
        if(event.triggerSource === "CustomMessage_AdminCreateUser") {
            // Ensure that your message contains event.request.codeParameter event.request.usernameParameter. This is the placeholder for the code and username that will be sent to your user.
            event.response.smsMessage = "Welcome to the service. Your user name is " + event.request.usernameParameter + " Your temporary password is " + event.request.codeParameter;
            event.response.emailSubject = "Welcome to the service";
            event.response.emailMessage = "Welcome to the service. Your user name is " + event.request.usernameParameter + " Your temporary password is " + event.request.codeParameter;
        }
        // Create custom message for other events
    }
    // Customize messages for other user pools

    // Return to Amazon Cognito
    callback(null, event);
};

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