本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 產生權杖前 Lambda 觸發程序
由於 Amazon Cognito 會在產生權杖之前叫用此觸發程序，因此您可以自訂使用者集區的權杖宣告。透過第一版或 `V1_0` 預先產生權杖觸發事件的**基本功能**，您可以自訂身份 (ID) 權杖。在具有 Essentials 或 Plus 功能計劃的使用者集區中，您可以使用存取權杖自訂產生第 2 版或`V2_0`觸發事件，以及針對machine-to-machine(M2M) 用戶端憑證授予使用存取權杖自訂產生第 3 版或`V3_0`觸發事件。
Amazon Cognito 會將 `V1_0` 事件作為請求傳送至您的函數，其中包含會寫入 ID 權杖的資料。`V2_0` 或 `V3_0`事件是單一請求，其中包含 Amazon Cognito 將寫入身分和存取字符的資料。若要自訂這兩個權杖，您必須更新函數以使用觸發程序第 2 版或第 3 版，並在相同的回應中傳送這兩個權杖的資料。
Amazon Cognito 會將第 2 版事件回應套用至從使用者身分驗證存取字符，其中人工使用者已將登入資料提供給您的使用者集區。第 3 版事件回應適用於來自使用者身分驗證和機器身分驗證的存取權杖，其中自動化系統會使用應用程式用戶端秘密授權存取權杖請求。除了產生的存取權杖之外，第 2 版和第 3 版的事件是相同的。
在 Amazon Cognito 將權杖發佈到您的應用程式之前，此 Lambda 觸發程序可以新增、移除和修改身分與存取權杖中的某些宣告。若要使用此功能，請從 Amazon Cognito 使用者集區主控台來連結一個 Lambda 函數，或是透過 AWS Command Line Interface (AWS CLI) 來更新您的使用者集區 `LambdaConfig`。
## 活動版本
您的使用者集區可以將不同版本的權杖產生前觸發事件交付至 Lambda 函數。`V1_0` 觸發會交付參數以修改 ID 字符。`V2_0` 或 `V3_0`觸發器會交付下列項目的參數。
1. `V1_0` 觸發的函數。
1. 自訂存取權杖的功能。
1. 將複雜資料類型傳遞至 ID 和存取權杖宣告值的能力：
+ String
+ 數字
+ Boolean
+ 字串、數字、布林值或任何這些值的組合陣列
+ JSON
**注意**
在 ID 字符中，您可以將複雜的物件填入宣告值，但 `phone_number_verified`、`updated_at`、 `email_verified`和 除外`address`。
使用者集區預設會交付`V1_0`事件。若要將使用者集區設定為傳送`V2_0`事件，請在 Amazon Cognito 主控台中設定觸發時，為使用者身分選擇基本功能的觸發**事件版本** \$1 存取權杖自訂。 ****若要產生`V3_0`事件，請選擇****基本功能 \$1 使用者和機器身分的存取權杖自訂****。您也可以在 [UpdateUserPool ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) 或 [CreateUserPool ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API 請求`LambdaVersion`的 [LambdaConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-LambdaConfig) 參數中設定 的值。事件版本 1、2 和 3 可在 **Essentials** 和 **Plus** 功能計劃中使用。第 3 版事件的 M2M 操作具有與每月作用中使用者 (MAU) 公式不同的定價結構。如需詳細資訊，請參閱 [Amazon Cognito 定價](https://aws.amazon.com/cognito/pricing/)。
**注意**
在 2024 年 11 月 22 日或之前在 1800 GMT 使用**進階安全功能**選項操作的使用者集區，以及保留在 **Lite** 功能層的使用者集區，可以存取事件版本一和兩個產生權杖前觸發。此舊版中*沒有*進階安全功能的使用者集區可存取事件版本 1。第 3 版*僅適用於* Essentials 和 Plus。
## 宣告和範圍參考
Amazon Cognito 限制您可以在存取權和身分權杖中新增、修改或隱藏的宣告和範圍。下表說明 Lambda 函數可以和無法修改的宣告，以及影響宣告存在或值的觸發事件參數。
| 取得 | 預設字符類型 | 可以新增 嗎？ | 可以修改嗎？ | 可以隱藏嗎？ | 事件參數 - 新增或修改 | 事件參數 - 抑制 | 身分類型 | 事件版本 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 不在使用者集區字符結構描述中的任何宣告 | 無 | 是 | 是 | N/A | claimsToAddOrOverride | claimsToSuppress | 使用者、機器[1](#cognito-pretoken-machine-ids-tier-note) | 全部[2](#cognito-pretoken-id-access-versions-note) |
| scope | 存取 | 是 | 是 | 是 | scopesToAdd | scopesToSuppress | 使用者、機器[1](#cognito-pretoken-machine-ids-tier-note) | v2\$10, v3\$10 |
| cognito:groups | ID、存取 | 是 | 是 | 是 | groupsToOverride | claimsToSuppress | 使用者 | 全部[2](#cognito-pretoken-id-access-versions-note) |
| cognito:preferred\$1role | ID | 是 | 是 | 是 | preferredRole | claimsToSuppress[3](#cognito-pretoken-suppress-groups-note) | 使用者 | 全部 |
| cognito:roles | ID | 是 | 是 | 是 | iamRolesToOverride | claimsToSuppress[3](#cognito-pretoken-suppress-groups-note) | 使用者 | 全部 |
| cognito:username | ID | 否 | 否 | 否 | N/A | N/A | 使用者 | N/A |
| 具有cognito:字首的任何其他宣告 | 無 | 否 | 否 | 否 | N/A | N/A | N/A | N/A |
| username | 存取 | 否 | 否 | 否 | N/A | N/A | 使用者 | v2\$10, v3\$10 |
| sub | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者 | N/A |
| 標準 OIDC 屬性 | ID | 是 | 是 | 是 | claimsToAddOrOverride | claimsToSuppress | 使用者 | 全部 |
| custom: 屬性 | ID | 是 | 是 | 是 | claimsToAddOrOverride | claimsToSuppress | 使用者 | 全部 |
| dev: 屬性 | ID | 否 | 否 | 是 | N/A | claimsToSuppress | 使用者 | 全部 |
| identities | ID | 否 | 否 | 否 | N/A | N/A | 使用者 | N/A |
| aud[4](#cognito-pretoken-aud-note) | ID | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| client\$1id | 存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| event\$1id | 存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| device\$1key | 存取 | 否 | 否 | 否 | N/A | N/A | 使用者 | N/A |
| version | 存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| acr | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| amr | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| at\$1hash | ID | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| auth\$1time | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| azp | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| exp | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| iat | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| iss | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| jti | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| nbf | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| nonce | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| origin\$1jti | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
| token\$1use | ID、存取 | 否 | 否 | 否 | N/A | N/A | 使用者、機器 | N/A |
1 機器身分的存取字符僅適用於觸發器輸入事件`v3_0`的 。事件第 3 版僅適用於 **Essentials** 和 **Plus** 功能層。**Lite** 層上的使用者集區可以接收`v1_0`事件。**Lite** 層上具有進階安全功能的使用者集區可以接收 `v1_0`和 `v2_0`事件。
2 將您的權杖產生前觸發條件設定為僅限 `v1_0` ID 權杖的事件版本，`v2_0`適用於 ID 和存取權杖，`v3_0`適用於具有機器身分功能的 ID 和存取權杖。
3 若要隱藏 `cognito:preferred_role`和 `cognito:roles`宣告，請將 `cognito:groups`新增至 `claimsToSuppress`。
4 您可以新增 `aud`宣告來存取字符，但其值必須符合目前工作階段的應用程式用戶端 ID。您可以從 `event.callerContext.clientId` 的請求事件中中衍生出用戶端 ID。
## 自訂身分權杖
透過產生字符前 Lambda 觸發程序的所有事件版本，您可以從使用者集區自訂身分 (ID) 字符的內容。ID 權杖提供來自受信任身分來源的使用者屬性，以便登入 Web 或行動應用程式。如需 ID 權杖的詳細資訊，請參閱 [了解身分 (ID) 字符](amazon-cognito-user-pools-using-the-id-token.md)。
產生權杖前 Lambda 觸發程序搭配 ID 權杖的使用方式如下。
+ 在執行階段變更您的使用者從身分集區請求的 IAM 角色。
+ 從外部來源新增使用者屬性。
+ 新增或取代現有的使用者屬性值。
+ 禁止披露使用者屬性，因為使用者的授權範圍以及您授予應用程式用戶端的屬性的讀取存取權限，這些屬性可能會傳遞給您的應用程式。
## 自訂存取權杖
使用事件版本 2 和三個產生權杖前 Lambda 觸發程序，您可以從使用者集區自訂存取權杖的內容。存取權杖授權使用者從受存取保護的資源 (例如 Amazon Cognito 權杖授權的 API 操作和第三方 API) 擷取資訊。對於具有用戶端憑證授予的machine-to-machine(M2M) 授權，Amazon Cognito 只會在您的使用者集區設定為第 3 版 (`V3_0`) 事件時調用權杖產生前觸發。如需存取權杖的詳細資訊，請參閱 [了解存取權杖](amazon-cognito-user-pools-using-the-access-token.md)。
產生權杖前 Lambda 觸發程序搭配存取權杖的使用方式包括下列項目。
+ 在`scope`宣告中新增或隱藏範圍。例如，您可以將範圍新增至僅指派範圍 `aws.cognito.signin.user.admin` 的 Amazon Cognito 使用者集區 API 身份驗證所產生的存取權杖。
+ 變更使用者集區群組中的使用者成員資格。
+ 新增尚未存在於 Amazon Cognito 存取權杖中的宣告。
+ 禁止披露宣告，否則宣告會傳遞給您的應用程式。
若要支援使用者集區中的存取自訂，您必須設定使用者集區以產生觸發請求的更新版本。更新您的使用者集區，如下列流程所示。
------
#### [ AWS 管理主控台 ]
**若要支援產生權杖前 Lambda 觸發程序中的存取權杖自訂**
1. 前往 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)，然後選擇 **User Pools** (使用者集區)。
1. 從清單中選擇現有的使用者集區，或[建立使用者集區](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 選擇**延伸項目**功能表並尋找 **Lambda 觸發**條件。
1. 新增或編輯**產生權杖前觸發程序**。
1. 在**指派 Lambda 函數**下選擇一個 Lambda 函數。
1. 為**使用者身分選擇基本功能 \$1 存取權杖自訂**的**觸發事件版本**，或**為使用者和機器身分選擇基本功能 \$1 存取權杖自訂**。此設定會更新 Amazon Cognito 傳送至您函數的請求參數，以包含用於存取權杖自訂的欄位。
------
#### [ User pools API ]
**若要支援產生權杖前 Lambda 觸發程序中的存取權杖自訂**
產生 [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) 或 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API 請求。您必須為不想設定為預設值的所有參數指定一個值。如需詳細資訊，請參閱[更新使用者集區和應用程式用戶端組態](cognito-user-pool-updating.md)。
在請求的 `LambdaVersion` 參數中包含以下內容。`LambdaVersion` 值 `V2_0`會導致您的使用者集區新增參數，並將變更套用至存取權杖。`LambdaVersion` 的值`V3_0`會產生與 相同的事件`V2_0`，但也會導致您的使用者集區將變更**套用至 M2M 存取權杖。若要叫用特定函數版本，請使用 Lambda 函數 ARN，並將函數版本作為 `LambdaArn` 的值。
```
"PreTokenGenerationConfig": {
"LambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:MyFunction",
"LambdaVersion": "V3_0"
},
```
------
**machine-to-machine(M2M) 用戶端登入資料的用戶端中繼資料**
您可以在 M2M 請求中傳遞[用戶端中繼資料](cognito-user-pools-working-with-lambda-triggers.md#working-with-lambda-trigger-client-metadata)。用戶端中繼資料是來自使用者或應用程式環境的其他資訊，有助於 的結果[產生權杖前 Lambda 觸發程序](#user-pool-lambda-pre-token-generation)。在使用者主體的身分驗證操作中，您可以將用戶端中繼資料傳遞至 [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) 和 [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) API 請求內文中的權杖產生前觸發器。由於應用程式會透過對 的直接請求，為 M2M 執行產生存取字符的流程[權杖端點](token-endpoint.md)，因此具有不同的模型。在用戶端登入資料的字符請求 POST 內文中，將具有用戶端中繼資料物件 URL 編碼 (`x-www-form-urlencoded`) 的 `aws_client_metadata` 參數傳遞至字串。如需請求範例，請參閱 [具有基本授權的用戶端憑證具有 POST 內文授權的用戶端憑證](token-endpoint.md#exchanging-client-credentials-for-an-access-token-in-request-body)。以下是傳遞鍵/值對 的範例參數`{"environment": "dev", "language": "en-US"}`。
```
aws_client_metadata=%7B%22environment%22%3A%20%22dev%22,%20%22language%22%3A%20%22en-US%22%7D
```
**其他資源**
+ [如何在 Amazon Cognito 使用者集區中自訂存取權杖](https://aws.amazon.com/blogs/security/how-to-customize-access-tokens-in-amazon-cognito-user-pools/)
**Topics**
+ [活動版本](#user-pool-lambda-pre-token-generation-event-versions)
+ [宣告和範圍參考](#user-pool-lambda-pre-token-generation-excluded-claims)
+ [自訂身分權杖](#user-pool-lambda-pre-token-generation-idtoken)
+ [自訂存取權杖](#user-pool-lambda-pre-token-generation-accesstoken)
+ [產生權杖前 Lambda 觸發程序來源](#user-pool-lambda-pre-token-generation-trigger-source)
+ [產生權杖前 Lambda 觸發程序參數](#cognito-user-pools-lambda-trigger-syntax-pre-token-generation)
+ [觸發權杖前事件版本二範例：新增和抑制宣告，範圍和群組](#aws-lambda-triggers-pre-token-generation-example-version-2-overview)
+ [權杖產生前事件第 2 版範例：使用複雜物件新增宣告](#aws-lambda-triggers-pre-token-generation-example-version-2-complex-objects)
+ [產生權杖前事件版本一範例：新增宣告及抑制現有宣告](#aws-lambda-triggers-pre-token-generation-version-1-add-claim)
+ [產生權杖前事件版本一範例：修改使用者的群組成員資格](#aws-lambda-triggers-pre-token-generation-version-1-change-group)
## 產生權杖前 Lambda 觸發程序來源
| triggerSource 值 | 事件 |
| --- | --- |
| TokenGeneration\$1HostedAuth | 從 Amazon Cognito 受管登入頁面進行身分驗證期間呼叫。 |
| TokenGeneration\$1Authentication | 在使用者身分驗證流程完成之後呼叫。 |
| TokenGeneration\$1NewPasswordChallenge | 在管理員建立使用者之後呼叫。當使用者必須變更臨時密碼時，會叫用此流程。 |
| TokenGeneration\$1ClientCredentials | 在 M2M 用戶端憑證授予後呼叫。您的使用者集區只會在您的事件版本為 時傳送此事件V3\$10。 |
| TokenGeneration\$1AuthenticateDevice | 在使用者裝置的身分驗證結束時呼叫。 |
| TokenGeneration\$1RefreshTokens | 當使用者嘗試重新整理身分和存取權杖時呼叫。 |
## 產生權杖前 Lambda 觸發程序參數
Amazon Cognito 傳遞至此 Lambda 函數的請求，是以下參數和 Amazon Cognito 新增至所有請求的[常用參數](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html#cognito-user-pools-lambda-trigger-syntax-shared)之組合。當您將產生權杖前 Lambda 觸發程序新增至使用者集區時，您可以選擇觸發程序版本。此版本決定 Amazon Cognito 是否將請求傳遞至您的 Lambda 函數 以及用於存取權杖自訂的其他參數。
------
#### [ Version one ]
第 1 版權杖可以在 ID 權杖中設定群組成員資格、IAM 角色和新宣告。群組成員資格覆寫也適用於存取權杖中的`cognito:groups`宣告。
```
{
"request": {
"userAttributes": {"string": "string"},
"groupConfiguration": {
"groupsToOverride": [
"string",
"string"
],
"iamRolesToOverride": [
"string",
"string"
],
"preferredRole": "string"
},
"clientMetadata": {"string": "string"}
},
"response": {
"claimsOverrideDetails": {
"claimsToAddOrOverride": {"string": "string"},
"claimsToSuppress": [
"string",
"string"
],
"groupOverrideDetails": {
"groupsToOverride": [
"string",
"string"
],
"iamRolesToOverride": [
"string",
"string"
],
"preferredRole": "string"
}
}
}
}
```
------
#### [ Versions two and three ]
第 2 版和第 3 版請求事件會新增自訂存取權杖的欄位。使用者集區會套用第 3 版事件的變更，以存取機器身分的字符。這些版本也新增對回應物件中複雜`claimsToOverride`資料類型的支援。您的 Lambda 函數可以傳回值為 的下列資料類型`claimsToOverride`：
+ String
+ 數字
+ Boolean
+ 字串、數字、布林值或任何這些值的組合陣列
+ JSON
```
{
"request": {
"userAttributes": {
"string": "string"
},
"scopes": ["string", "string"],
"groupConfiguration": {
"groupsToOverride": ["string", "string"],
"iamRolesToOverride": ["string", "string"],
"preferredRole": "string"
},
"clientMetadata": {
"string": "string"
}
},
"response": {
"claimsAndScopeOverrideDetails": {
"idTokenGeneration": {
"claimsToAddOrOverride": {
"string": [accepted datatype]
},
"claimsToSuppress": ["string", "string"]
},
"accessTokenGeneration": {
"claimsToAddOrOverride": {
"string": [accepted datatype]
},
"claimsToSuppress": ["string", "string"],
"scopesToAdd": ["string", "string"],
"scopesToSuppress": ["string", "string"]
},
"groupOverrideDetails": {
"groupsToOverride": ["string", "string"],
"iamRolesToOverride": ["string", "string"],
"preferredRole": "string"
}
}
}
}
```
------
### 產生權杖前請求參數
| 名稱 | 描述 | 最小觸發事件版本 |
| --- |--- |--- |
| userAttributes | 您的使用者在使用者集區中的設定檔屬性。 | 1 |
| groupConfiguration | 包含目前群組組態的輸入物件。物件包含 `groupsToOverride`、`iamRolesToOverride` 和 `preferredRole`。 | 1 |
| groupsToOverride | 您的用戶所屬的[使用者集區](cognito-user-pools-user-groups.md#cognito-user-pools-user-groups.title)。 | 1 |
| iamRolesToOverride | 您可以將使用者集區群組與 AWS Identity and Access Management (IAM) 角色建立關聯。此元素是使用者所屬群組中所有 IAM 角色的清單。 | 1 |
| preferredRole | 您可以為使用者集區群組設定[優先順序](cognito-user-pools-user-groups.md#assigning-precedence-values-to-groups.title)。此元素包含 `groupsToOverride` 元素中優先度最高之群組的 IAM 角色名稱。 | 1 |
| clientMetadata | 針對權杖產生前觸發程序，您可以做為 Lambda 函數的自訂輸入來指定與提供的一個或多個鍵值組。 若要將此資料傳遞至您的 Lambda 函數，您可以使用 [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) 和 [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) API 操作中的 ClientMetadata 參數。Amazon Cognito 不包含來自其傳遞至權杖產生前函數的請求中的 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) 和 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 操作中的 `ClientMetadata` 參數的資料。 | 1 |
| scopes | 存取字符範圍。存取權杖中存在的範圍是使用者請求的使用者集區標準範圍和自訂範圍，以及您授權應用程式用戶端發佈的範圍。 | 2 |
### 產生權杖前回應參數
| 名稱 | 描述 | 最小觸發事件版本 |
| --- |--- |--- |
| claimsOverrideDetails | A container for all elements in a V1\$10 trigger event. | 1 |
| claimsAndScopeOverrideDetails | 或 `V2_0``V3_0`觸發事件中所有元素的容器。 | 2 |
| idTokenGeneration | 您要在使用者 ID 權杖中覆寫、新增或抑制的宣告。此 ID 字符的父項自訂值只會出現在事件版本 2 及更高版本中，但子元素會出現在版本 1 事件中。 | 2 |
| accessTokenGeneration | 您想要在使用者的存取權杖中覆寫、新增或抑制的宣告和範圍。此存取字符自訂值的父項只會出現在事件版本 2 及更高版本中。 | 2 |
| claimsToAddOrOverride | 您要新增或修改的一或多個宣告及其值的映射。對於與群組相關的宣告，請改用 `groupOverrideDetails`。 在事件版本 2 和更新版本中，此元素會出現在 `accessTokenGeneration`和 下`idTokenGeneration`。 | 1[*](#cognito-pretoken-complex-objects-note) |
| claimsToSuppress | 您希望 Amazon Cognito 抑制的宣告清單。如果您的函數抑制並取代了宣告值，則 Amazon Cognito 將抑制宣告。 在事件版本 2 和更新版本中，此元素會出現在 `accessTokenGeneration`和 下`idTokenGeneration`。 | 1 |
| groupOverrideDetails | 包含目前群組組態的輸出物件。物件包含 `groupsToOverride`、`iamRolesToOverride` 和`preferredRole`。 您的函數將使用您提供的物件取代 `groupOverrideDetails` 物件。如果您在回應中提供空的或空物件，則 Amazon Cognito 會抑制這些群組。若要將現有群組組態保留原狀，請將請求的 `groupConfiguration` 物件值複製到回應中的 `groupOverrideDetails` 物件。然後將其傳回服務。 Amazon Cognito ID 權杖和存取權杖都包含 `cognito:groups` 宣告。您的 `groupOverrideDetails` 物件取代存取權杖以及 ID 權杖中的 `cognito:groups` 宣告。群組覆寫是第 1 版事件可以對存取字符進行的唯一變更。 | 1 |
| scopesToAdd | 您要新增至使用者存取字符中`scope`宣告的範圍清單。您無法新增包含一或多個空白字元的範圍值。 | 2 |
| scopesToSuppress | 您要從使用者存取權杖中的`scope`宣告中移除的範圍清單。 | 2 |
\$1 第一版事件的回應物件可以傳回字串。第 2 版和第 3 版事件的回應物件可能會傳回[複雜的物件](#user-pool-lambda-pre-token-generation-event-versions)。
## 觸發權杖前事件版本二範例：新增和抑制宣告，範圍和群組
此範例會對使用者的權杖進行下列修改。
1. 在 ID 權杖中將其 `family_name` 設置為 `Doe`。
1. 防止 `email` 和 `phone_number` 宣告出現在 ID 權杖中。
1. 將其 ID 權杖 `cognito:roles` 宣告設置為 `"arn:aws:iam::123456789012:role\/sns_callerA","arn:aws:iam::123456789012:role\/sns_callerC","arn:aws:iam::123456789012:role\/sns_callerB"`。
1. 將其 ID 權杖 `cognito:preferred_role` 宣告設置為 `arn:aws:iam::123456789012:role/sns_caller`。
1. 將範圍 `openid`、`email` 和 `solar-system-data/asteroids.add` 新增到存取權杖。
1. 抑制存取權杖的範圍 `phone_number` 和 `aws.cognito.signin.user.admin`。移除 `phone_number` 可防止從 `userInfo` 中擷取使用者的電話號碼。移除 `aws.cognito.signin.user.admin` 可防止使用者透過 Amazon Cognito 使用者集區 API 讀取和修改自身設定檔的 API 請求。
**注意**
如存取權杖中的剩餘範圍包含 `openid` 與至少一個標準範圍，從範圍中刪除 `phone_number` 僅會防止擷取用戶的電話號碼。如需詳細資訊，請參閱[關於範圍](cognito-user-pools-define-resource-servers.md#cognito-user-pools-define-resource-servers-about-scopes)。
1. 將其 ID 和存取權杖 `cognito:groups` 宣告設置為 `"new-group-A","new-group-B","new-group-C"`。
------
#### [ JavaScript ]
```
export const handler = function(event, context) {
event.response = {
"claimsAndScopeOverrideDetails": {
"idTokenGeneration": {
"claimsToAddOrOverride": {
"family_name": "Doe"
},
"claimsToSuppress": [
"email",
"phone_number"
]
},
"accessTokenGeneration": {
"scopesToAdd": [
"openid",
"email",
"solar-system-data/asteroids.add"
],
"scopesToSuppress": [
"phone_number",
"aws.cognito.signin.user.admin"
]
},
"groupOverrideDetails": {
"groupsToOverride": [
"new-group-A",
"new-group-B",
"new-group-C"
],
"iamRolesToOverride": [
"arn:aws:iam::123456789012:role/new_roleA",
"arn:aws:iam::123456789012:role/new_roleB",
"arn:aws:iam::123456789012:role/new_roleC"
],
"preferredRole": "arn:aws:iam::123456789012:role/new_role",
}
}
};
// Return to Amazon Cognito
context.done(null, event);
};
```
------
Amazon Cognito 會將事件資訊傳遞至您的 Lambda 函數。此函數會將相同事件物件傳回 Amazon Cognito，並在回應中附上任何變更。在 Lambda 主控台中，您可使用與 Lambda 觸發程序相關聯的資料來設定測試事件。下列是此程式碼範例的測試事件：
------
#### [ JSON ]
```
{
"version": "2",
"triggerSource": "TokenGeneration_Authentication",
"region": "us-east-1",
"userPoolId": "us-east-1_EXAMPLE",
"userName": "JaneDoe",
"callerContext": {
"awsSdkVersion": "aws-sdk-unknown-unknown",
"clientId": "1example23456789"
},
"request": {
"userAttributes": {
"sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"cognito:user_status": "CONFIRMED",
"email_verified": "true",
"phone_number_verified": "true",
"phone_number": "+12065551212",
"family_name": "Zoe",
"email": "Jane.Doe@example.com"
},
"groupConfiguration": {
"groupsToOverride": ["group-1", "group-2", "group-3"],
"iamRolesToOverride": ["arn:aws:iam::123456789012:role/sns_caller1", "arn:aws:iam::123456789012:role/sns_caller2", "arn:aws:iam::123456789012:role/sns_caller3"],
"preferredRole": ["arn:aws:iam::123456789012:role/sns_caller"]
},
"scopes": [
"aws.cognito.signin.user.admin", "openid", "email", "phone"
]
},
"response": {
"claimsAndScopeOverrideDetails": []
}
}
```
------
## 權杖產生前事件第 2 版範例：使用複雜物件新增宣告
此範例會對使用者的權杖進行下列修改。
1. 將數字、字串、布林值和 JSON 類型的宣告新增至 ID 字符。這是第 2 版觸發事件提供給 ID 字符的唯一變更。
1. 將數字、字串、布林值和 JSON 類型的宣告新增至存取權杖。
1. 將三個範圍新增至存取權杖。
1. 隱藏 ID 和存取權杖中的`email`宣告。
1. 隱藏存取字符中的`aws.cognito.signin.user.admin`範圍。
------
#### [ JavaScript ]
```
export const handler = function(event, context) {
var scopes = ["MyAPI.read", "MyAPI.write", "MyAPI.admin"]
var claims = {}
claims["aud"]= event.callerContext.clientId;
claims["booleanTest"] = false;
claims["longTest"] = 9223372036854775807;
claims["exponentTest"] = 1.7976931348623157E308;
claims["ArrayTest"] = ["test", 9223372036854775807, 1.7976931348623157E308, true];
claims["longStringTest"] = "\{\
\"first_json_block\": \{\
\"key_A\": \"value_A\",\
\"key_B\": \"value_B\"\
\},\
\"second_json_block\": \{\
\"key_C\": \{\
\"subkey_D\": [\
\"value_D\",\
\"value_E\"\
],\
\"subkey_F\": \"value_F\"\
\},\
\"key_G\": \"value_G\"\
\}\
\}";
claims["jsonTest"] = {
"first_json_block": {
"key_A": "value_A",
"key_B": "value_B"
},
"second_json_block": {
"key_C": {
"subkey_D": [
"value_D",
"value_E"
],
"subkey_F": "value_F"
},
"key_G": "value_G"
}
};
event.response = {
"claimsAndScopeOverrideDetails": {
"idTokenGeneration": {
"claimsToAddOrOverride": claims,
"claimsToSuppress": ["email"]
},
"accessTokenGeneration": {
"claimsToAddOrOverride": claims,
"claimsToSuppress": ["email"],
"scopesToAdd": scopes,
"scopesToSuppress": ["aws.cognito.signin.user.admin"]
}
}
};
console.info("EVENT response\n" + JSON.stringify(event, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2))
console.info("EVENT response size\n" + JSON.stringify(event, (_, v) => typeof v === 'bigint' ? v.toString() : v).length)
// Return to Amazon Cognito
context.done(null, event);
};
```
------
Amazon Cognito 會將事件資訊傳遞至您的 Lambda 函數。此函數會將相同事件物件傳回 Amazon Cognito，並在回應中附上任何變更。在 Lambda 主控台中，您可使用與 Lambda 觸發程序相關聯的資料來設定測試事件。下列是此程式碼範例的測試事件：
------
#### [ JSON ]
```
{
"version": "2",
"triggerSource": "TokenGeneration_HostedAuth",
"region": "us-west-2",
"userPoolId": "us-west-2_EXAMPLE",
"userName": "JaneDoe",
"callerContext": {
"awsSdkVersion": "aws-sdk-unknown-unknown",
"clientId": "1example23456789"
},
"request": {
"userAttributes": {
"sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"cognito:user_status": "CONFIRMED"
"email_verified": "true",
"phone_number_verified": "true",
"phone_number": "+12065551212",
"email": "Jane.Doe@example.com"
},
"groupConfiguration": {
"groupsToOverride": ["group-1", "group-2", "group-3"],
"iamRolesToOverride": ["arn:aws:iam::123456789012:role/sns_caller1"],
"preferredRole": ["arn:aws:iam::123456789012:role/sns_caller1"]
},
"scopes": [
"aws.cognito.signin.user.admin",
"phone",
"openid",
"profile",
"email"
]
},
"response": {
"claimsAndScopeOverrideDetails": []
}
}
```
------
## 產生權杖前事件版本一範例：新增宣告及抑制現有宣告
此範例使用版本 1 觸發事件和「產生權杖前 Lambda 函數」來新增宣告及抑制現有宣告。
------
#### [ Node.js ]
```
const handler = async (event) => {
event.response = {
claimsOverrideDetails: {
claimsToAddOrOverride: {
my_first_attribute: "first_value",
my_second_attribute: "second_value",
},
claimsToSuppress: ["email"],
},
};
return event;
};
export { handler };
```
------
Amazon Cognito 會將事件資訊傳遞至您的 Lambda 函數。此函數會將相同事件物件傳回 Amazon Cognito，並在回應中附上任何變更。在 Lambda 主控台中，您可使用與 Lambda 觸發程序相關聯的資料來設定測試事件。下列是此程式碼範例的測試事件：由於程式碼 範例 會處理任何請求參數，因此可以使用具有空白請求的測試事件。如需有關常見請求參數的詳細資訊，請參閱 [使用者集區 Lambda 觸發程序事件](cognito-user-pools-working-with-lambda-triggers.md#cognito-user-pools-lambda-trigger-event-parameter-shared)。
------
#### [ JSON ]
```
{
"request": {},
"response": {}
}
```
------
## 產生權杖前事件版本一範例：修改使用者的群組成員資格
此範例使用版本 1 觸發事件和「產生權杖前 Lambda 函數」來修改使用者的群組成員資格。
------
#### [ Node.js ]
```
const handler = async (event) => {
event.response = {
claimsOverrideDetails: {
groupOverrideDetails: {
groupsToOverride: ["group-A", "group-B", "group-C"],
iamRolesToOverride: [
"arn:aws:iam::XXXXXXXXXXXX:role/sns_callerA",
"arn:aws:iam::XXXXXXXXX:role/sns_callerB",
"arn:aws:iam::XXXXXXXXXX:role/sns_callerC",
],
preferredRole: "arn:aws:iam::XXXXXXXXXXX:role/sns_caller",
},
},
};
return event;
};
export { handler };
```
------
Amazon Cognito 會將事件資訊傳遞至您的 Lambda 函數。此函數會將相同事件物件傳回 Amazon Cognito，並在回應中附上任何變更。在 Lambda 主控台中，您可使用與 Lambda 觸發程序相關聯的資料來設定測試事件。下列是此程式碼範例的測試事件：
------
#### [ JSON ]
```
{
"request": {},
"response": {}
}
```
------