自定义电子邮件发件人 Lambda 触发器 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

自定义电子邮件发件人 Lambda 触发器

Amazon Cognito 调用自定义电子邮件发件人触发器,以便第三方提供商可以从您的 Amazon Lambda 函数代码向您的用户发送电子邮件通知。Amazon Cognito 将电子邮件消息事件作为请求发送到 Lambda 函数。然后,您的函数的自定义代码必须处理和传递消息。

注意

目前,您无法在 Amazon Cognito 控制台中分配自定义电子邮件发件人触发器。您可以在 CreateUserPoolUpdateUserPool API 请求中使用 LambdaConfig 参数分配触发器。

如下所示设置自定义电子邮件发件人触发器:

  1. 创建一个您要分配为自定义电子邮件发件人触发器的 Lambda 函数。

  2. 在 Amazon Key Management Service (Amazon KMS) 中创建加密密钥。Amazon Cognito 生成密钥(临时密码和授权代码),然后使用此密钥对其进行加密。然后,您可以在 Lambda 函数中使用 Amazon Encryption SDK 来解密代码并以明文形式将其发送给用户。

  3. 授予 Amazon Cognito 服务主体调用 Lambda 函数的 cognito-idp.amazonaws.com 权限。

  4. 编写 Lambda 函数代码,将您的电子邮件消息定向到自定义传递方法或第三方提供商。

  5. 更新用户池,使其使用自定义发件人 Lambda 触发器。

重要

当您为用户池配置自定义电子邮件发件人或自定义 SMS 发件人功能时,请配置对称 Amazon KMS key 以提高安全性。Amazon Cognito 使用您配置的 KMS 密钥加密代码或临时密码。Amazon Cognito 将 base64 编码的密文发送到您的 Lambda 函数。有关更多信息,请参阅对称 KMS 密钥

自定义电子邮件发件人 Lambda 触发器参数

这些是 Amazon Cognito 随同常见参数中的事件信息一起传递给此 Lambda 函数的参数。

JSON
{ "request": { "type": "customEmailSenderRequestV1", "code": "string", "clientMetadata": { "string": "string", . . . }, "userAttributes": { "string": "string", . . . } }

自定义电子邮件发件人请求参数

type

请求版本。对于自定义电子邮件发件人事件,此字符串的值始终为 customEmailSenderRequestV1

code

您的函数可以解密并发送给您的用户的加密代码。

clientMetadata

一个或多个键值对,您可以将它们作为自定义输入提供给自定义电子邮件发件人 Lambda 函数触发器。要将此数据传递给 Lambda 函数,您可以在 AdminRespondToAuthChallengeRespondToAuthChallenge API 操作中使用 ClientMetadata 参数。在传递到身份验证后函数的请求中,Amazon Cognito 不包括 AdminInitiateAuthInitiateAuth API 操作的 ClientMetadata 参数中传递的数据。

userAttributes

表示用户属性的一个或多个键值对。

自定义电子邮件发件人响应参数

Amazon Cognito 不需要自定义电子邮件发件人响应中有任何其他返回信息。您的函数可以使用 API 操作来查询和修改资源,或者将事件元数据记录到外部系统。

激活自定义电子邮件发件人 Lambda 触发器

要设置使用自定义逻辑为您的用户池发送电子邮件消息的自定义电子邮件发件人触发器,请按如下方式激活触发器。

步骤 1:创建 Lambda 函数

为自定义电子邮件发件人触发器创建 Lambda 函数。Amazon Cognito 使用 Amazon Encryption SDK 加密密钥(临时密码或授权代码)。

步骤 2:在 Amazon KMS 中创建加密密钥

在 Amazon KMS 中创建加密密钥。Amazon Cognito 使用此密钥加密 Amazon Cognito 生成的临时密码和授权代码。然后,您可以在自定义发件人 Lambda 函数中解密这些密钥,以明文形式将其发送给用户。

步骤 3:授予 Amazon Cognito 权限,以调用 Lambda 函数

使用以下命令:

aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com

步骤 4:编辑代码以使用自定义发件人

Amazon Cognito 使用 Amazon Encryption SDK 加密密钥(临时密码和授权代码),然后 Amazon Cognito 会将密钥发送给自定义发件人 Lambda 函数。请先解密这些密钥,然后再将它们发送给用户。您可以选择自定义提供商来发送电子邮件。要将 Amazon Encryption SDK 与您的 Lambda 函数结合使用,您需要将该 SDK 与函数打包在一起。有关信息,请参阅安装 Amazon Encryption SDK for JavaScript。您也可以如下所示更新 Lambda 包:

  1. 从控制台导出 Lambda 函数包。

  2. 解压缩程序包。

  3. 将 Amazon Encryption SDK 添加到该包。例如,如果您使用的是 Node.js,请添加 node_modules 目录,并包含 @aws-crypto/client-node 中的库。

  4. 重新创建包。

  5. 从修改后的目录更新 Lambda 函数代码。

步骤 5:更新用户池,添加自定义发件人 Lambda 触发器

UpdateUserPool API 操作中使用 CustomEmailSender 参数更新用户群体。UpdateUserPool 需要用户群体的所有参数以及您希望更改的参数。如果您没有提供所有相关参数,Amazon Cognito 会将任何缺失参数的值设置为其原定设置。有关更多信息,请参阅更新用户群体配置

#Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, along with any existing user pool configurations. --lambda-config "CustomEmailSender={LambdaVersion=V1_0,LambdaArn= lambda-arn },KMSKeyID= key-id"

要使用 Amazon CLI 删除自定义电子邮件发件人 Lambda 触发器,请从 --lambda-config 中省略 CustomEmailSender 参数,并包括要与用户群体结合使用的所有其他触发器。要使用 UpdateUserPool API 请求删除自定义电子邮件发件人 Lambda 触发器,请从包含其余用户群体配置的请求正文中删除 CustomemailSender。有关更多信息,请参阅使用 Amazon Cognito API 或 Amazon CLI 更新用户群体

以下 Node.js 示例显示了如何在您的自定义电子邮件发件人 Lambda 函数中处理电子邮件消息事件。此示例假设您的函数定义了两个环境变量。

KEY_ALIAS

要用于加密和解密用户代码的 KMS 密钥的别名

KEY_ARN

要用于加密和解密用户代码的 KMS 密钥的 Amazon 资源名称 (ARN)。

const AWS = require('aws-sdk'); const b64 = require('base64-js'); const encryptionSdk = require('@aws-crypto/client-node'); #Configure the encryption SDK client with the KMS key from the environment variables. const { encrypt, decrypt } = encryptionSdk.buildClient(encryptionSdk.CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT); const generatorKeyId = process.env.KEY_ALIAS; const keyIds = [ process.env.KEY_ARN ]; const keyring = new encryptionSdk.KmsKeyringNode({ generatorKeyId, keyIds }) exports.handler = async (event) => { #Decrypt the secret code using encryption SDK. let plainTextCode; if(event.request.code){ const { plaintext, messageHeader } = await decrypt(keyring, b64.toByteArray(event.request.code)); plainTextCode = plaintext } #PlainTextCode now has the decrypted secret. if(event.triggerSource == 'CustomEmailSender_SignUp'){ #Send email to end-user using custom or 3rd party provider. #Include temporary password in the email. }else if(event.triggerSource == 'CustomEmailSender_ResendCode'){ }else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){ }else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){ }else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){ }else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){ }else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){ } return; };

自定义电子邮件发件人 Lambda 触发器源

下表显示了 Lambda 代码中自定义电子邮件触发器源的触发事件。

TriggerSource value 触发事件
CustomEmailSender_SignUp 用户注册,Amazon Cognito 随即发送欢迎消息。
CustomEmailSender_ForgotPassword 用户请求代码以重置其密码。
CustomEmailSender_ResendCode 用户请求更换代码以重置其密码。
CustomEmailSender_UpdateUserAttribute 用户更新电子邮件地址或电话号码属性,而 Amazon Cognito 将发送代码用于验证该属性。
CustomEmailSender_VerifyUserAttribute 用户创建新电子邮件地址或电话号码属性,而 Amazon Cognito 将发送代码用于验证该属性。
CustomEmailSender_AdminCreateUser 您在用户池中创建新用户,而 Amazon Cognito 向其发送临时密码。
CustomEmailSender_AccountTakeOverNotification Amazon Cognito 检测到接管用户账户的尝试并向用户发送通知。