自定义消息 Lambda 触发器

Amazon Cognito 会在发送电子邮件或电话验证消息或多重身份验证 () 代码之前调用此触发器。MFA您可以使用自定义消息触发器动态自定义消息。您可以在 Amazon Cognito 控制台的 Message Customizations（消息自定义）选项卡中编辑静态自定义消息。

该请求包括 codeParameter。这是一个字符串，用作 Amazon Cognito 传递给用户的代码的占位符。将 codeParameter 字符串插入消息正文中用于显示验证码的位置。Amazon Cognito 在收到此响应后，Amazon Cognito 将 codeParameter 字符串替换为实际验证码。

注意

具有 CustomMessage_AdminCreateUser 触发器源的自定义消息 Lambda 函数将返回用户名和验证码。由于管理员创建的用户必须同时收到其用户名和代码，因此来自您的函数的响应必须同时包含 request.usernameParameter 和 request.codeParameter。

自定义消息 Lambda 触发器源

triggerSource 价值	事件
CustomMessage_SignUp	自定义消息 – 在注册后发送确认代码。
CustomMessage_AdminCreateUser	自定义消息 – 向新用户发送临时密码。
CustomMessage_ResendCode	自定义消息 – 向现有用户重新发送确认代码。
CustomMessage_ForgotPassword	自定义消息 – 针对“忘记密码”请求发送确认代码。
CustomMessage_UpdateUserAttribute	自定义消息 – 当用户的电子邮件或电话号码发生更改时，此触发器自动向用户发送验证码。不可用于其他属性。
CustomMessage_VerifyUserAttribute	自定义消息 – 当用户针对新的电子邮件或电话号码手动请求验证码时，此触发器向用户发送验证码。
CustomMessage_Authentication	自定义消息-用于在身份验证期间发送MFA代码。

自定义消息 Lambda 触发器参数

Amazon Cognito 传递给此 Lambda 函数的请求是以下参数和 Amazon Cognito 添加到所有请求中的常用参数的组合。

JSON

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

自定义消息请求参数

userAttributes

表示用户属性的一个或多个名称/值对。

codeParameter

一个字符串，用作自定义消息中验证码的占位符。

usernameParameter

用户名。Amazon Cognito 在管理员创建的用户发出的请求中包含此参数。

clientMetadata

一个或多个键值对，您可以将其作为自定义输入内容提供给为自定义消息触发器指定的 Lambda 函数。调用自定义消息函数的请求不包括在 and 操作中的 ClientMetadata 参数中AdminInitiateAuth传递的数据。InitiateAuthAPI要将此数据传递给您的 Lambda 函数，您可以在以下操作API中使用该 ClientMetadata 参数：

• AdminResetUserPassword

• AdminRespondToAuthChallenge

• AdminUpdateUserAttributes

• ForgotPassword

• GetUserAttributeVerificationCode

• ResendConfirmationCode

• SignUp

• UpdateUserAttributes

自定义消息响应参数

在响应中，指定要在发送给用户的消息中使用的自定义文本。有关 Amazon Cognito 适用于这些参数的字符串限制，请参阅。MessageTemplateType

smsMessage

要发送给用户的自定义SMS消息。必须包含您在请求中收到的 codeParameter 值。

emailMessage

发送给用户的自定义电子邮件。可以在emailMessage参数中使用HTML格式。必须包含您在请求中收到的 codeParameter 值作为变量 {####}。只有在用户池的 EmailSendingAccount 属性为 DEVELOPER 时，Amazon Cognito 才可以使用emailMessage 参数。如果用户池的 EmailSendingAccount 属性不是 DEVELOPER 且返回了 emailMessage 参数，Amazon Cognito 会生成 400 错误代码 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException。当您选择亚马逊简单电子邮件服务 (AmazonSES) 发送电子邮件时，用户池的EmailSendingAccount属性为DEVELOPER。否则，该值为 COGNITO_DEFAULT。

emailSubject

自定义消息的主题行。只有当用户池的 EmailSendingAccount属性为时，您才能使用该emailSubject参数DEVELOPER。如果用户池的 EmailSendingAccount 属性不是 DEVELOPER 且 Amazon Cognito 返回了 emailSubject 参数，Amazon Cognito 会生成 400 错误代码 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException。用户池的EmailSendingAccount属性是您选择使用亚马逊简单电子邮件服务 (AmazonSES) 发送电子邮件DEVELOPER时。否则，该值为 COGNITO_DEFAULT。

用于注册的自定义消息示例

此示例 Lambda 函数可在服务要求应用程序向用户发送验证码时自定义电子邮件或SMS消息。

Amazon Cognito 可以在多个事件中调用 Lambda 触发器：注册后、重新发送验证码时、恢复忘记的密码时或验证用户属性时。回复包括两者的消息SMS和电子邮件。该消息必须包含代码参数 "####"。此参数是用户收到的验证码的占位符。

电子邮件的最大长度为 20,000 UTF -8 个字符，。此长度包括验证码。您可以在这些电子邮件中使用HTML标签。

SMS消息的最大长度为 140 UTF -8 个字符。此长度包括验证码。

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 将事件信息传递给 Lambda 函数。随后，该函数将相同事件对象随同响应中的任何更改返回给 Amazon Cognito。在 Lambda 控制台中，您可以设置一个测试事件，该事件包含与您的 Lambda 触发器相关的数据。以下是此代码示例的一个测试事件：

JSON

{
	"version": "1",
	"region": "us-west-2",
	"userPoolId": "us-west-2_EXAMPLE",
	"userName": "test-user",
	"callerContext": {
		"awsSdkVersion": "aws-sdk-unknown-unknown",
		"clientId": "1example23456789"
	},
	"triggerSource": "CustomMessage_SignUp",
	"request": {
		"userAttributes": {
			"sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
			"cognito:user_status": "CONFIRMED",
			"email_verified": "true",
			"phone_number_verified": "true",
			"phone_number": "[phone]",
			"email": "[e-mail]"
		},
		"codeParameter": "{####}",
		"linkParameter": "{##Click Here##}",
		"usernameParameter": "None"
	},
	"response": {
		"smsMessage": "None",
		"emailMessage": "None",
		"emailSubject": "None"
	}
}

管理员创建用户的自定义消息示例

Amazon Cognito 向此示例自定义消息 Lambda 函数发送的请求的triggerSource值为，用户名CustomMessage_AdminCreateUser和临时密码均为。该函数${event.request.codeParameter}从请求中的临时密码和${event.request.usernameParameter}请求中的用户名填充。

您的自定义消息必须在响应对象codeParameter和emailMessage中usernameParameter插入smsMessage和的值。在此示例中，该函数将相同的消息写入响应字段event.response.smsMessage和event.response.emailMessage。

电子邮件的最大长度为 20,000 UTF -8 个字符。此长度包括验证码。你可以在这些电子邮件中使用HTML标签。SMS消息的最大长度为 140 UTF -8 个字符。此长度包括验证码。

回复包括两者的消息SMS和电子邮件。

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 将事件信息传递给 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>"
  }
}