カスタムメッセージの Lambda トリガー - Amazon Cognito
カスタムメッセージの Lambda トリガーのソースカスタムメッセージの Lambda トリガーのパラメータサインアップのカスタムメッセージの例管理者作成ユーザーのカスタムメッセージの例

カスタムメッセージの Lambda トリガー

Amazon Cognito は、E メールまたは電話による確認メッセージ、または多要素認証 (MFA) コードを送信する前にこのトリガーを呼び出して、メッセージを動的にカスタマイズできるようにします。静的なカスタムメッセージは、Amazon Cognito コンソールの [Message Customizations] (メッセージのカスタマイズ) タブで編集できます。

リクエストには、ユーザーに配信するコードのプレースホルダーとなる文字列 codeParameter が含まれます。メッセージ本文で検証コードを挿入する位置に codeParameter の文字列を挿入します。このレスポンスを受信すると、Amazon Cognito サービスが codeParameter 文字列を実際の検証コードに置き換えます。

注記

カスタムメッセージの Lambda 関数と CustomMessage_AdminCreateUser トリガーはユーザー名と検証コードを返すため、リクエストには request.usernameParameter と request.codeParameter の両方が含まれている必要があります。

カスタムメッセージの Lambda トリガーのソース

triggerSource 値 トリガーイベント
CustomMessage_SignUp カスタムメッセージ - サインアップ後に確認コードを送信するため.
CustomMessage_AdminCreateUser カスタムメッセージ – 新規ユーザーに一時パスワードを送信するため.
CustomMessage_ResendCode カスタムメッセージ – 既存ユーザーに確認コードを再送するため.
CustomMessage_ForgotPassword カスタムメッセージ - 忘れたパスワードのリクエスト用の確認コードを送信するため.
CustomMessage_UpdateUserAttribute カスタムメッセージ - ユーザーの E メールまたは電話番号が変更されると、このトリガーは検証コードをそのユーザーに自動的に送信します。他の属性には使用できません。
CustomMessage_VerifyUserAttribute カスタムメッセージ – ユーザーが手動で新しい E メールや電話番号の認証コードをリクエストすると、このトリガーからユーザーに認証コードが送信されます。
CustomMessage_Authentication カスタムメッセージ - 認証時に MFA コードを送信するため.

カスタムメッセージの Lambda トリガーのパラメータ

これらは、一般的なパラメータに加えて、この Lambda 関数で必要となるパラメータです。

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

カスタムメッセージリクエストパラメータ

userAttributes

ユーザー属性を表す 1 つ以上の名前 - 値ペア。

codeParameter

カスタムメッセージで、検証コードのプレースホルダーとして使用する文字列。

usernameParameter

ユーザー名パラメータ。これは、管理者がユーザーフローを作成するために必要なリクエストパラメータです。

clientMetadata

カスタムメッセージのトリガーに指定する Lambda 関数へのカスタム入力として提供できる 1 つ、または複数のキー/値ペア。このデータは、以下の API アクションで ClientMetadata パラメータを使用することによって Lambda 関数に渡すことができます。

カスタムメッセージレスポンスパラメータ

レスポンスで、ユーザーへのメッセージに使用するカスタムテキストを指定します。

smsMessage

ユーザーに送信されるカスタム SMS メッセージ。リクエストで受信される codeParameter 値を含める必要があります。

emailMessage

ユーザーに送信されるカスタム E メールメッセージ。リクエストで受信される codeParameter 値を含める必要があります。EmailSendingAccount が DEVELOVER ではなく、emailMessage が返された場合は、400 エラーコード com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException がスローされます。emailMessage は、UserPool の EmailSendingAccount が DEVELOVER の場合にのみ許可されます。

emailSubject

カスタムメッセージの件名。EmailSendingAccount が DEVELOVER ではなく、emailMessage が返された場合は、400 エラーコード com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException がスローされます。emailSubject は、UserPool の emailSendingAccount が DEVELOVER の場合にのみ許可されます。

サインアップのカスタムメッセージの例

この Lambda 関数は、サービスでアプリによるユーザーへの検証コードの送信が必要とされる場合に、E メールまたは SMS メッセージをカスタマイズするために呼び出されます。

Lambda トリガーは、登録後、検証コードの再送信時、パスワードを忘れた場合、またはユーザー属性の検証時といった複数の時点で呼び出すことができます。レスポンスには、SMS と E メールの両方のメッセージが含まれます。メッセージには、ユーザーに配信する検証コードのプレースホルダーとなるコードパラメータ "####" を含める必要があります。

E メールの場合、メッセージの最大長は検証コードを含めて UTF-8 で 20,000 文字です。これらの E メールでは HTML タグを使用できます。

SMS の場合、最大長は検証コードを含めて UTF-8 で 140 文字です。

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 は Lambda 関数にイベント情報を渡します。Lambda 関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。

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

管理者作成ユーザーのカスタムメッセージの例

カスタムメッセージの Lambda 関数と CustomMessage_AdminCreateUser トリガーはユーザー名と検証コードを返すため、メッセージ本文に request.usernameParameter と request.codeParameter の両方を含めてください。

コードのパラメータ値 "####" は、の一時パスワードのプレースホルダーであり、「username」はユーザーに提供されるユーザー名のプレースホルダーです。

E メールの場合、メッセージの最大長は検証コードを含めて UTF-8 で 20,000 文字です。これらの E メールでは HTML タグを使用できます。SMS の場合、最大長は検証コードを含めて UTF-8 で 140 文字です。

レスポンスには、SMS と E メールの両方のメッセージが含まれます。

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 は Lambda 関数にイベント情報を渡します。Lambda 関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。

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