使用 Lambda 觸發程序來自訂使用者集區工作流程 - Amazon Cognito
重要考量新增使用者集區觸發程序使用者集區 Lambda 觸發程序事件使用者集區 Lambda 觸發程序的常用參數按照事件的 Lambda 觸發程序來源按照函數的 Lambda 觸發程序來源

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 Lambda 觸發程序來自訂使用者集區工作流程

Amazon Cognito 使用 AWS Lambda 函數來修改使用者集區的身分驗證行為。您可以將使用者集區設定為在首次註冊之前、完成驗證後以及介於兩者之間的幾個階段，自動調用 Lambda 函數。您的函數可以修改身分驗證流程的預設行為、提出修改使用者集區或其他 AWS 資源的API請求，以及與外部系統通訊。Lambda 函數中的程式碼是您自己的程式碼。Amazon Cognito 會將事件資料傳送到您的函數，等待函數處理資料，而且在大多數情況下會預期回應事件，反映您想要對工作階段進行的任何變更。

在請求和回應事件系統中，您可以介紹自己的身分驗證挑戰、在使用者集區和另一個身分存放區之間遷移使用者、自訂訊息，以及修改 JSON Web 權杖 （JWTs）。

Lambda 觸發程序可以自訂 Amazon Cognito 在您的使用者集區中啟動動作後，傳送給使用者的回應。例如，您可以阻止本來會成功的使用者登入。他們也可以針對您的 AWS 環境、外部 、APIs資料庫或身分存放區執行執行執行期操作。例如，遷移使用者觸發程序可以結合外部動作與 Amazon Cognito 中的變更：您可以查詢外部目錄中的使用者資訊，然後根據該外部資訊為新使用者設定屬性。

當您將 Lambda 觸發程序指派給使用者集區時，Amazon Cognito 會中斷其預設流程，從您的函數請求資訊。Amazon Cognito 會產生JSON事件並將其傳遞至您的函數。此事件包含使用者建立使用者帳戶、登入、重設密碼或更新屬性之請求的相關資訊。然後，您的函數有機會採取行動，或將事件原封不動地傳回。

下表摘錄一些使用 Lambda 觸發程序來自訂使用者集區操作的方法：

使用者集區流程 作業 描述

自訂身分驗證流程

 定義身分驗證挑戰 決定自訂身分驗證流程中的下一個挑戰
建立身分驗證挑戰 在自訂身分驗證流程中建立挑戰
確認身分驗證挑戰回應 判斷自訂身分驗證流程中的回應是否正確
身分驗證事件 身分驗證前 Lambda 觸發程序 自訂驗證接受或拒絕登入請求
身分驗證後 Lambda 觸發程序 記錄事件以進行自訂分析
產生權杖前 Lambda 觸發程序 增加或抑制權杖宣告
註冊 註冊前 Lambda 觸發程序 執行用於接受或拒絕註冊請求的自訂驗證
確認後 Lambda 觸發程序 新增自訂歡迎訊息或事件記錄以進行自訂分析
遷移使用者 Lambda 觸發程序 將使用者從現有的使用者目錄遷移到使用者集區
訊息 自訂訊息 Lambda 觸發程序 執行訊息的進階自訂及當地語系化
權杖建立 產生權杖前 Lambda 觸發程序 新增或移除 ID 權杖中的屬性
電子郵件和SMS第三方供應商 自訂寄件者 Lambda 觸發程序 使用第三方供應商來傳送SMS和傳送電子郵件訊息
主題

重要考量

準備用於 Lambda 函數的使用者集區時，請考慮下列事項：

  • Amazon Cognito 傳送給您的 Lambda 觸發程序的事件可能會隨著新功能而變更。JSON 階層中回應和請求元素的位置可能會變更，或者可能會新增元素名稱。在 Lambda 函數中，您可以期望收到本指南中所述的輸入元素鍵值對，但更嚴格的輸入驗證可能會導致函數失敗。

  • 您可以選擇 Amazon Cognito 傳送至某些觸發程序的多個版本事件之一。某些版本可能會要求您接受 Amazon Cognito 定價的變更。如需定價的詳細資訊，請參閱 Amazon Cognito 定價。若要在產生權杖前 Lambda 觸發程序中自訂存取權杖，您必須使用進階安全性功能設定使用者集區，並更新 Lambda 觸發程序組態以使用第 2 版事件。

  • 除了自訂寄件者 Lambda 觸發程序之外，Amazon Cognito 會同步叫用 Lambda 函數。當 Amazon Cognito 呼叫您的 Lambda 函數時，該函數必須在 5 秒內回應。若未回應，而可以重試呼叫，則 Amazon Cognito 會重試呼叫。嘗試失敗 3 次後，函數會發生逾時。您無法變更此 5 秒逾時值。如需詳細資訊，請參閱 AWS Lambda 開發人員指南中的 Lambda 程式設計模型。

    Amazon Cognito 不會重試傳回HTTP狀態碼為 500-599 的叫用錯誤之函數呼叫。這些代碼表示發生組態問題，導致 Lambda 無法啟動該函數。如需詳細資訊，請參閱 中的錯誤處理和自動重試 AWS Lambda。

  • 您無法在 Lambda 觸發程式組態中宣告函數版本。Amazon Cognito 使用者集區預設會調用最新版本的函數。不過，您可以將函數版本與別名建立關聯，並將觸發條件設定為 CreateUserPool或 LambdaArn UpdateUserPoolAPI請求ARN中的別名。此選項無法用於 AWS Management Console中。若要進一步了解別名，請參閱 AWS Lambda 開發人員指南中的 Lambda 函數別名。

  • 若刪除 Lambda 觸發程序，必須更新使用者集區內對應的觸發程序。例如，若您刪除驗證後觸發，便須在對應的使用者集區內，將 Post authentication (身分驗證後) 觸發設為 none (無)。

  • 如果您的 Lambda 函數未將請求和回應參數傳回至 Amazon Cognito，或傳回錯誤，則驗證事件不會成功。您可以在函數中傳回錯誤，以防止使用者註冊、驗證、產生權杖，或進行驗證流程中調用 Lambda 觸發程序的任何其他階段。

    Amazon Cognito 託管 UI 會在登入提示上方，以錯誤文字的形式傳回 Lambda 觸發程序產生的錯誤。Amazon Cognito 使用者集區會API傳回格式為 的觸發錯誤[trigger] failed with error [error text from response]。最佳實務是僅在您希望使用者看到的 Lambda 函數中產生錯誤。使用輸出方法print()，例如將任何敏感或偵錯資訊記錄到 CloudWatch Logs。如需範例，請參閱註冊前範例：如果使用者名稱少於五個字元，則拒絕註冊。

  • 您可以在另一個 中新增 Lambda 函數， AWS 帳戶 作為使用者集區的觸發條件。您必須使用 CreateUserPool和 UpdateUserPoolAPI操作新增跨帳戶觸發條件，或將其對等的新增至 AWS CloudFormation 和 AWS CLI。您無法在 中新增跨帳戶函數 AWS Management Console。

  • 當您在 Amazon Cognito 主控台中新增 Lambda 觸發程序時，Amazon Cognito 會在您的函數中新增以資源為基礎的政策，以允許您的使用者集區叫用該函數。在 Amazon Cognito 主控台外部建立 Lambda 觸發程序時，包括跨帳戶之間的函數，您必須為 Lambda 函數新增基於資源政策的許可。您新增的許可必須允許 Amazon Cognito 以代表您的使用者集區叫用函數。您可以從 Lambda 主控台新增許可或使用 Lambda AddPermissionAPI操作。

    以 Lambda 資源為基礎的政策範例

    下列 Lambda 資源型政策範例允許 Amazon Cognito 叫用 Lambda 函數的有限功能。執行此操作時，Amazon Cognito 只能代表 aws:SourceArn 條件中的使用者集區和 aws:SourceAccount 條件中的帳戶叫用函數。

    {
    "Version": "2012-10-17",
    "Id": "default",
    "Statement": [
        {
            "Sid": "lambda-allow-cognito",
            "Effect": "Allow",
            "Principal": {
                "Service": "cognito-idp.amazonaws.com"
            },
            "Action": "lambda:InvokeFunction",
            "Resource": "<your Lambda function ARN>",
            "Condition": {
                "StringEquals": {
                    "AWS:SourceAccount": "<your account number>"
                },
                "ArnLike": {
                    "AWS:SourceArn": "<your user pool ARN>"
                }
            }
        }
    ]
}

新增使用者集區 Lambda 觸發程序

使用主控台新增使用者集區 Lambda 觸發程序

  1. 使用 Lambda 主控台建立 Lambda 函數。如需 Lambda 函數的詳細資訊，請參閱《AWS Lambda 開發人員指南》。

  2. 前往 Amazon Cognito 主控台，然後選擇 User Pools (使用者集區)。

  3. 從清單中選擇現有的使用者集區，或建立使用者集區。

  4. 選擇 User pool properties (使用者集區屬性) 索引標籤並找到 Lambda triggers (Lambda 觸發程序)。

  5. 選擇 Add a Lambda trigger (新增 Lambda 觸發程序)。

  6. 根據您要自訂的身分驗證階段，選取 Lambda 觸發程序 Category (類別)。

  7. 選取指派 Lambda 函數，然後選取 AWS 區域 與使用者集區相同的函數。

    注意

    如果您的 AWS Identity and Access Management （IAM） 憑證具有更新 Lambda 函數的許可，Amazon Cognito 會新增 Lambda 資源型政策。使用此政策，Amazon Cognito 可以叫用您選取的函數。如果登入憑證沒有足夠的IAM許可，您必須分別更新資源型政策。如需詳細資訊，請參閱重要考量。

  8. 選擇 Save changes (儲存變更)。

  9. 您可以在 Lambda 主控台 CloudWatch 中使用 來記錄 Lambda 函數 。如需詳細資訊，請參閱存取 Lambda 的 CloudWatch 日誌。

使用者集區 Lambda 觸發程序事件

Amazon Cognito 會將事件資訊傳遞至您的 Lambda 函數。Lambda 函數會將相同事件物件傳回 Amazon Cognito，並在回應中附上任何變更。這個事件顯示 Lambda 觸發程序的常用參數：

JSON
{
    "version": "string",
    "triggerSource": "string",
    "region": AWSRegion,
    "userPoolId": "string",
    "userName": "string",
    "callerContext": 
        {
            "awsSdkVersion": "string",
            "clientId": "string"
        },
    "request":
        {
            "userAttributes": {
                "string": "string",
                ....
            }
        },
    "response": {}
}

使用者集區 Lambda 觸發程序的常用參數

version

Lambda 函數的版本編號。

triggerSource

觸發 Lambda 函數的事件名稱。如需每個 的說明， triggerSource 請參閱 將 Lambda 觸發程序連接至使用者集區功能操作。

region

AWS 區域 作為AWSRegion執行個體。

userPoolId

使用者集區的 ID。

userName

目前使用者的使用者名稱。

callerContext

有關請求和程式碼環境的中繼資料。它包含 欄位 awsSdkVersion和 clientId。

awsSdkVersion

產生請求的 AWS SDK版本。

clientId

使用者集區應用程式用戶端的 ID。

請求

使用者API請求的詳細資訊。它包括下列欄位，以及觸發程序特有的任何請求參數。例如，Amazon Cognito 傳送至預先身分驗證觸發程序的事件也會包含一個 userNotFound 參數。您可以處理此參數的值，以便在使用者嘗試使用未註冊的使用者名稱登入時採取自訂動作。

userAttributes

一或多組使用者屬性名稱和值的鍵/值對，例如 "email": "john@example.com"。

response

此參數不包含原始請求中的任何資訊。您的 Lambda 函數必須將整個事件傳回給 Amazon Cognito，並將任何傳回參數新增至 response。若要查看函數可以包含哪些傳回參數，請參閱您要使用之觸發程序的文件。

將API操作連接至 Lambda 觸發程序

以下各節說明 Amazon Cognito 從使用者集區中的活動呼叫的 Lambda 觸發程序。

當您的應用程式透過 Amazon Cognito 使用者集區 API、託管 UI 或使用者集區端點登入使用者時，Amazon Cognito 會根據工作階段內容叫用您的 Lambda 函數。如需 Amazon Cognito 使用者集區API和使用者集區端點的詳細資訊，請參閱 使用使用者集區API和授權伺服器。接下來各節中的表格描述了導致 Amazon Cognito 叫用函數的事件，以及 Amazon Cognito 在請求中包含的 triggerSource 字串。

Amazon Cognito 中的 Lambda 觸發程序 API

下表說明當您的應用程式建立、登入或更新本機使用者時，Amazon Cognito 可呼叫 Lambda 觸發程序的來源字串。

Amazon Cognito 中的本機使用者觸發來源 API
API 操作 Lambda 觸發程序 觸發程序來源

AdminCreateUser

 註冊前

PreSignUp_AdminCreateUser
產生權杖前

TokenGeneration_NewPasswordChallenge
自訂訊息

CustomMessage_AdminCreateUser
自訂電子郵件寄件者

CustomEmailSender_AdminCreateUser
自訂SMS寄件者

CustomSMSSender_AdminCreateUser

SignUp

 註冊前

PreSignUp_SignUp
自訂訊息

CustomMessage_SignUp
自訂電子郵件寄件者

CustomEmailSender_SignUp
自訂SMS寄件者

CustomSMSSender_SignUp

ConfirmSignUp

AdminConfirmSignUp

 確認後

PostConfirmation_ConfirmSignUp

InitiateAuth

AdminInitiateAuth

 身分驗證前

PreAuthentication_Authentication
定義驗證挑戰

DefineAuthChallenge_Authentication
建立驗證挑戰

CreateAuthChallenge_Authentication
產生權杖前

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens
遷移使用者

UserMigration_Authentication
自訂訊息

CustomMessage_Authentication
自訂電子郵件寄件者

CustomEmailSender_AccountTakeOverNotification

CustomEmailSender_Authentication
自訂SMS寄件者

CustomSMSSender_Authentication

ForgotPassword

 遷移使用者

UserMigration_ForgotPassword
自訂訊息

CustomMessage_ForgotPassword
自訂電子郵件寄件者

CustomEmailSender_ForgotPassword
自訂SMS寄件者

CustomSMSSender_ForgotPassword

ConfirmForgotPassword

 確認後

PostConfirmation_ConfirmForgotPassword

UpdateUserAttributes

AdminUpdateUserAttributes

 自訂訊息

CustomMessage_UpdateUserAttribute
自訂電子郵件寄件者

CustomEmailSender_UpdateUserAttribute
自訂SMS寄件者

CustomSMSSender_UpdateUserAttribute

VerifyUserAttributes

 自訂訊息

CustomMessage_VerifyUserAttribute
自訂電子郵件寄件者

CustomEmailSender_VerifyUserAttribute
自訂SMS寄件者

CustomSMSSender_VerifyUserAttribute

託管 UI 中 Amazon Cognito 本機使用者的 Lambda 觸發程序

下表說明當本機使用者透過託管 UI 登入您的使用者集區時，Amazon Cognito 可呼叫 Lambda 觸發程序的來源字串。

託管 UI 中的苯機使用者觸發程序來源
託管 UI URI Lambda 觸發程序 觸發程序來源
/signup 註冊前

PreSignUp_SignUp
自訂訊息

CustomMessage_SignUp
自訂電子郵件寄件者

CustomEmailSender_SignUp
自訂SMS寄件者

CustomSMSSender_SignUp
/confirmuser 確認後

PostConfirmation_ConfirmSignUp
/login 身分驗證前

PreAuthentication_Authentication
定義驗證挑戰

DefineAuthChallenge_Authentication
建立驗證挑戰

CreateAuthChallenge_Authentication
產生權杖前

TokenGeneration_Authentication

TokenGeneration_AuthenticateDevice

TokenGeneration_RefreshTokens
遷移使用者

UserMigration_Authentication
自訂訊息

CustomMessage_Authentication
自訂電子郵件寄件者

CustomEmailSender_AccountTakeOverNotification

CustomEmailSender_Authentication
自訂SMS寄件者

CustomSMSSender_Authentication
/forgotpassword 遷移使用者

UserMigration_ForgotPassword
自訂訊息

CustomMessage_ForgotPassword
自訂電子郵件寄件者

CustomEmailSender_ForgotPassword
自訂SMS寄件者

CustomSMSSender_ForgotPassword
/confirmforgotpassword 確認後

PostConfirmation_ConfirmForgotPassword

適用於聯合身分使用者的 Lambda 觸發程序

您可以使用以下 Lambda 觸發程序，為使用聯合身分提供者登入的使用者自訂使用者集區工作流程。

注意

聯合身分使用者可以使用 Amazon Cognito 託管 UI 登入，或者您也可以向 授權端點 產生請求，以無訊息方式將使用者重新導向至其身分提供者登入頁面。您無法使用 Amazon Cognito 使用者集區 登入聯合使用者API。

聯合身分使用者觸發程序來源
登入事件 Lambda 觸發程序 觸發程序來源
首次登入 註冊前

PreSignUp_ExternalProvider
確認後

PostConfirmation_ConfirmSignUp
產生權杖前

TokenGeneration_HostedAuth
後續登入 身分驗證前

PreAuthentication_Authentication
身分驗證後

PostAuthentication_Authentication
產生權杖前

TokenGeneration_HostedAuth

聯合身分登入不會叫用使用者集區中的任何 自訂身分驗證挑戰 Lambda 觸發程序、遷移使用者 Lambda 觸發程序、自訂訊息 Lambda 觸發程序 或 自訂寄件者 Lambda 觸發程序。

將 Lambda 觸發程序連接至使用者集區功能操作

每個 Lambda 觸發程序都在您的使用者集區中扮演一個功能角色。例如，觸發程序可以修改您的註冊流程，或新增自訂身分驗證挑戰。Amazon Cognito 傳送至 Lambda 函數的事件可反映組成該功能角色的多個動作之一。例如，Amazon Cognito 會在您的使用者註冊以及您建立使用者時，叫用預先註冊觸發程序。相同功能角色在這些不同情況中都有自己的 triggerSource 值。Lambda 函數可以根據呼叫它的操作，以不同的方式處理傳入事件。

當事件對應於觸發程序來源時，Amazon Cognito 也會叫用所有指派的函數。例如，當使用者登入您指派了遷移使用者和預先身分驗證觸發程序的使用者集區時，他們會同時啟動兩者。

註冊、確認和登入 (身分驗證) 觸發程序
觸發條件 triggerSource 值 事件
註冊前 PreSignUp_SignUp 註冊前。
註冊前 PreSignUp_AdminCreateUser 註冊前 (當管理員建立新使用者時)。
註冊前 PreSignUp_ExternalProvider 外部身分提供者註冊前。
確認後 PostConfirmation_ConfirmSignUp 註冊後確認。
確認後 PostConfirmation_ConfirmForgotPassword 忘記密碼後確認。
身分驗證前 PreAuthentication_Authentication 身分驗證前。
身分驗證後 PostAuthentication_Authentication 身分驗證後。
自訂身分驗證挑戰觸發程序
觸發條件 triggerSource 值 事件
定義驗證挑戰 DefineAuthChallenge_Authentication 定義驗證挑戰。
建立驗證挑戰 CreateAuthChallenge_Authentication 建立驗證挑戰。
確認驗證挑戰 VerifyAuthChallengeResponse_Authentication 確認驗證挑戰回應。
產生權杖前觸發程序
觸發條件 triggerSource 值 事件
產生權杖前 TokenGeneration_HostedAuth Amazon Cognito 從您的託管 UI 登入頁面對使用者進行身分驗證。
產生權杖前 TokenGeneration_Authentication 使用者身分驗證流程完成。
產生權杖前 TokenGeneration_NewPasswordChallenge 管理員建立使用者。當使用者必須變更臨時密碼時，Amazon Cognito 會叫用此功能。
產生權杖前 TokenGeneration_AuthenticateDevice 使用者裝置的身分驗證結束時。
產生權杖前 TokenGeneration_RefreshTokens 使用者嘗試重新整理身分和存取權杖時。
遷移使用者觸發程序
觸發條件 triggerSource 值 事件
使用者遷移 UserMigration_Authentication 在登入時的使用者遷移。
使用者遷移 UserMigration_ForgotPassword 忘記密碼流程時的使用者遷移。
自訂訊息觸發程序
觸發條件 triggerSource 值 事件
自訂訊息 CustomMessage_SignUp 當使用者在使用者集區註冊時的自訂訊息。
自訂訊息 CustomMessage_AdminCreateUser 當您以管理員身分建立使用者，而且 Amazon Cognito 向這些使用者發送臨時密碼時的自訂訊息。
自訂訊息 CustomMessage_ResendCode 當現有使用者請求新確認代碼時的自訂訊息。
自訂訊息 CustomMessage_ForgotPassword 當使用者請求密碼重設時的自訂訊息。
自訂訊息 CustomMessage_UpdateUserAttribute 當使用者變更其電子郵件地址或電話號碼，而且 Amazon Cognito 傳送驗證碼時的自訂訊息。
自訂訊息 CustomMessage_VerifyUserAttribute 當使用者新增電子郵件地址或電話號碼，而且 Amazon Cognito 傳送驗證碼的自訂訊息。
自訂訊息 CustomMessage_Authentication 已設定SMSMFA登入的使用者時的自訂訊息。