本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 自訂寄件者 Lambda 觸發程序
Lambda 會在使用者集區中觸發`CustomEmailSender`和`CustomSMSSender`支援第三方電子郵件和簡訊通知。您可以選擇簡訊和電子郵件供應商，傳送通知給 Lambda 函數程式碼中的使用者。當 Amazon Cognito 傳送邀請、MFA 代碼、確認碼、驗證碼和臨時密碼給使用者時，事件會啟用您設定的 Lambda 函數。Amazon Cognito 會將代碼和臨時密碼 (秘密) 傳送至您啟用的 Lambda 函數。Amazon Cognito 會使用 AWS KMS 客戶受管金鑰和 來加密這些秘密 AWS Encryption SDK。 AWS Encryption SDK 是用戶端加密程式庫，可協助您加密和解密一般資料。
**[CustomEmailSender](user-pool-lambda-custom-email-sender.md)**
Amazon Cognito 會叫用此觸發程序，傳送電子郵件通知給使用者。
**[CustomSMSSender](user-pool-lambda-custom-sms-sender.md)**
Amazon Cognito 會叫用此觸發，傳送簡訊通知給使用者。
## 加密概念
Amazon Cognito 不會在傳送至自訂寄件者觸發條件的事件中以純文字傳送使用者的代碼。Lambda 函數必須解密事件中的程式碼。下列概念是您的函數必須用來取得可交付給使用者的程式碼的加密架構。
**AWS KMS**
AWS KMS 是一項受管服務，可用來建立和控制 AWS KMS 金鑰。這些金鑰可加密您的資料。如需詳細資訊，請參閱[什麼是 AWS Key Management Service？](/kms/latest/developerguide/overview.html)。
**KMS 金鑰**
KMS 金鑰是密碼編譯金鑰的邏輯表示。KMS 金鑰包含金鑰 ID、建立日期、說明和金鑰狀態等中繼資料。KMS 金鑰也包含可用來加密和解密資料的金鑰材料。如需詳細資訊，請參閱刪除 [AWS KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys)。
**對稱 KMS 金鑰**
對稱 KMS 金鑰是 256 位元的加密金鑰，不會在未加密的情況下退出 AWS KMS 。若要使用對稱 KMS 金鑰，您必須呼叫 AWS KMS。Amazon Cognito 使用對稱金鑰。相同的金鑰可用於加密和解密。如需詳細資訊，請參閱[對稱 KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#symmetric-cmks)。
## 自訂寄件者 Lambda 觸發程序的須知事項
+ 若要使用這些 Lambda 觸發程序設定使用者集區，您可以使用 AWS CLI 或 SDK。無法透過 Amazon Cognito 主控台使用這些組態。
`UpdateUserPool` 操作會設定 Lambda 組態。請求此操作需要使用者集區的所有參數，*以及*您要變更的參數。如果您未提供所有相關的參數，Amazon Cognito 會將任何遺漏參數的值設定為其預設值。如以下 CLI AWS 範例所示，包含您要新增至使用者集區或保留在使用者集區中的所有 Lambda 函數的項目。如需詳細資訊，請參閱[更新使用者集區和應用程式用戶端組態](cognito-user-pool-updating.md)。
```
#Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing
#user pool configurations. This snippet also includes a pre sign-up trigger for syntax reference. The pre sign-up trigger
#doesn't have a role in custom sender triggers.
--lambda-config "PreSignUp=lambda-arn, \
CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
KMSKeyID=key-id"
```
對於使用`UpdateUserPool`下列程式碼片段的 JSON `LambdaConfig` 內文的請求， 會指派自訂簡訊和電子郵件寄件者函數。
```
"LambdaConfig": {
"KMSKeyID": "arn:aws:kms:us-east-1:111122223333:key/a6c4f8e2-0c45-47db-925f-87854bc9e357",
"CustomEmailSender": {
"LambdaArn": "arn:aws:lambda:us-east-1:111122223333:function:MyFunction",
"LambdaVersion": "V1_0"
},
"CustomSMSSender": {
"LambdaArn": "arn:aws:lambda:us-east-1:111122223333:function:MyFunction",
"LambdaVersion": "V1_0"
}
```
+ 若要使用 `update-user-pool` AWS CLI 命令移除自訂寄件者 Lambda 觸發條件，請從 省略 `CustomSMSSender`或 `CustomEmailSender` 參數`--lambda-config`，並包含您想要與使用者集區搭配使用的所有其他觸發條件。
若要使用 `UpdateUserPool` API 請求移除自訂寄件者 Lambda 觸發條件，請從包含其他使用者集區組態的請求內文省略 `CustomSMSSender` 或 `CustomEmailSender` 參數。
+ Amazon Cognito 會在使用者臨時密碼中逸出 HTML 預留字元，例如 `<` (`<`) 和 `>` (`>`)。這些字元可能會出現在 Amazon Cognito 傳送至您自訂電子郵件寄件者功能的臨時密碼中，但不會出現在臨時驗證碼中。若要傳送臨時密碼，您的 Lambda 函數必須在解密密碼後以及將訊息傳送給使用者之前取消逸出這些字元。
## 啟用自訂寄件者 Lambda 觸發條件
若要使用自訂邏輯來傳送使用者集區的簡訊或電子郵件訊息，請設定自訂寄件者觸發條件。接下來的程序會將自訂 SMS 觸發器、自訂電子郵件觸發器或兩者指派給您的使用者集區。新增自訂寄件者觸發條件後，Amazon Cognito 一律會傳送使用者屬性，包括電話號碼和一次性程式碼到您的 Lambda 函數，而不是傳送簡訊或電子郵件訊息的預設行為。
1. 在 AWS Key Management Service () 中建立[對稱加密金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#symmetric-cmks)AWS KMS。Amazon Cognito 會產生秘密，包括暫時密碼、驗證碼、身分驗證一次性密碼和確認碼，然後使用此 KMS 金鑰透過 加密秘密[AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html)。然後，您可以使用 Lambda 函數 AWS Encryption SDK 中的 來解密秘密，並以純文字傳送給使用者。
1. 建立或更新使用者集區的 IAM 主體會針對 Amazon Cognito 用來加密程式碼的 KMS 金鑰建立一次性授權。為您的 KMS 金鑰授予此主體`CreateGrant`許可。若要讓此範例 KMS 金鑰政策有效，更新使用者集區的管理員必須使用 IAM 角色 的擔任角色工作階段登入`arn:aws:iam::111222333444:role/my-example-administrator-role`。
將下列針對您環境修改的資源型政策套用至您的 KMS 金鑰。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/my-example-administrator-role"
},
"Action": "kms:CreateGrant",
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1example-2222-3333-4444-999example",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:userpool-id": "us-west-2_EXAMPLE"
}
}
},
{
"Sid": "Allow Lambda to decrypt",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/my-lambda-function-role"
},
"Action": "kms:Decrypt",
"Resource": "*"
}]
}
```
------
1. 為自訂寄件者觸發程序建立 Lambda 函數。Amazon Cognito 使用 [AWS 加密 SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html) 來加密授權使用者 API 請求的秘密、臨時密碼和授權碼。
1. 指派至少具有 KMS 金鑰`kms:Decrypt`許可的 [Lambda 執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)。
1. 編寫 Lambda 函數程式碼來傳送訊息。函數的輸入事件包含秘密。在您的函數中，使用 解密秘密， AWS Encryption SDK 並處理任何相關的中繼資料。然後將代碼、您自己的自訂訊息和目的地電話號碼傳送到遞送訊息的自訂 API。
1. 將 AWS Encryption SDK 新增至 Lambda 函數。如需詳細資訊，請參閱 [AWS 加密軟體 SDK 程式設計語言](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/programming-languages.html)。若要更新 Lambda 套件，請完成下列步驟。
1. 將 Lambda 函數在 AWS 管理主控台匯出為 .zip 檔案。
1. 開啟您的 函數並新增 AWS Encryption SDK。如需詳細資訊和下載連結，請參閱 *AWS Encryption SDK 開發人員指南*中的 [AWS Encryption SDK 程式設計語言](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/programming-languages.html)。
1. 使用 SDK 相依性壓縮您的函數，然後將函數上傳至 Lambda。如需詳細資訊，請參閱 *AWS Lambda 開發人員指南*中的[以 .zip 封存檔形式部署 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/configuration-function-zip.html#configuration-function-create)。
1. 授予 Amazon Cognito 服務委託人 `cognito-idp.amazonaws.com` 存取權，以叫用 Lambda 函數。
下列 AWS CLI 命令會授予 Amazon Cognito 叫用 Lambda 函數的許可：
```
aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com
```
1. 使用新增自訂寄件者 Lambda 觸發條件的`LambdaConfig`參數產生 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API 請求。您無法在 Amazon Cognito 主控台中新增此類型的觸發條件。自訂寄件者觸發條件需要 `KMSKeyID`和 `CustomSMSSender`或 `CustomEmailSender`（或兩者） 的`LambdaConfig`參數。