產生權杖前 Lambda 觸發程序

由於 Amazon Cognito 會在產生權杖之前叫用此觸發程序，因此您可以自訂使用者集區的權杖宣告。透過第一版或 V1_0 預先產生權杖觸發事件的基本功能，您可以自訂身份 (ID) 權杖。在具有高級安全功能活動的使用者集區中，您可以通過存取權杖自訂生成版本 2 或 V2_0 觸發事件。

Amazon Cognito 會將 V1_0 事件作為請求傳送至您的函數，其中包含會寫入 ID 權杖的資料。V2_0 事件是單一請求，其中包含 Amazon Cognito 將寫入身分和存取權杖的資料。若要自訂兩個權杖，您必須更新您的函數以使用最新的觸發程序版本，並在相同的回應中傳送兩個權杖的資料。

在 Amazon Cognito 將權杖發佈到您的應用程式之前，此 Lambda 觸發程序可以新增、移除和修改身分與存取權杖中的某些宣告。若要使用此功能，請從 Amazon Cognito 使用者集區主控台來連結一個 Lambda 函數，或是透過 AWS Command Line Interface (AWS CLI) 來更新您的使用者集區 LambdaConfig。

活動版本

您的使用者集區可以向 Lambda 函數傳遞不同版本的權杖產生觸發器事件。V1_0觸發器提供用於修改 ID 令牌的參數。V2_0觸發器提供以下參數。

1. V1_0觸發器的功能。

2. 自定義訪問令牌的能力。

3. 將複雜數據類型傳遞給 ID 和訪問令牌聲明值的能力：

   • 字串

   • Number

   • Boolean

   • 字符串，數字，布爾值或任何這些組合的數組

   • JSON

注意

在 ID 令牌中，您可以將複雜對象填充為聲明的值 phone_number_verifiedemail_verified，除了updated_at，和address。

依預設，使用者集區會傳送V1_0事件。若要設定使用者集區以傳送V2_0事件，請在 Amazon Cognito 主控台中設定觸發器時，選擇基本功能 + 存取權杖自訂的觸發事件版本。您也可以在UpdateUserPool 或 CreateUserPool API 請求LambdaVersion的LambdaConfig參數中設定的值。使用V2_0事件自訂存取權杖需支付額外費用。如需詳細資訊，請參閱 Amazon Cognito 定價。

排除宣告和範圍

Amazon Cognito 限制您可以在存取權和身分權杖中新增、修改或隱藏的宣告和範圍。如果您的 Lambda 函數嘗試為這些宣告中的任何一個設定值，Amazon Cognito 會發出具有原始宣告值的權杖 (如果請求中存在該權杖的話)。

共用宣告

• acr

• amr

• at_hash

• auth_time

• azp

• exp

• iat

• iss

• jti

• nbf

• nonce

• origin_jti

• sub

• token_use

ID 令牌宣告

• identities

• aud

• cognito:username

存取權杖宣告

• username

• client_id

• scope

  注意

  您可以使用 scopesToAdd 和 scopesToSuppress 回應值變更存取權杖中的範圍，但不能直接修改 scope 宣告。您無法新增開頭為 aws.cognito 的範圍，包括使用者集區保留的範圍 aws.cognito.signin.user.admin。

• device_key

• event_id

• version

您無法使用以下字首新增或覆寫宣告，但可以隱藏它們，或阻止其出現在權杖中。

• dev:

• cognito:

您可以新增 aud 宣告以存取權杖，但其值必須與目前工作階段的應用程式用戶端 ID 相符。您可以從 event.callerContext.clientId 的請求事件中中衍生出用戶端 ID。

自訂身分權杖

透過產生權杖前 Lambda 觸發程序，您可以自訂使用者集區中身分 (ID) 權杖的內容。ID 權杖提供來自受信任身分來源的使用者屬性，以便登入 Web 或行動應用程式。如需 ID 權杖的詳細資訊，請參閱 使用 ID 權杖。

產生權杖前 Lambda 觸發程序搭配 ID 權杖的使用方式如下。

• 在執行階段變更您的使用者從身分集區請求的 IAM 角色。

• 從外部來源新增使用者屬性。

• 新增或取代現有的使用者屬性值。

• 禁止披露使用者屬性，因為使用者的授權範圍以及您授予應用程式用戶端的屬性的讀取存取權限，這些屬性可能會傳遞給您的應用程式。

自訂存取權杖

透過產生權杖前 Lambda 觸發程序，您可以自訂使用者集區中存取權杖的內容。存取權杖授權使用者從受存取保護的資源 (例如 Amazon Cognito 權杖授權的 API 操作和第三方 API) 擷取資訊。雖然您可以使用用戶端登入資料授與 Amazon Cognito 產生 machine-to-machine (M2M) 授權的存取權杖，但 M2M 請求不會叫用權杖產生前觸發器函數，也無法發出自訂存取權杖。如需存取權杖的詳細資訊，請參閱 使用存取權杖。

產生權杖前 Lambda 觸發程序搭配存取權杖的使用方式包括下列項目。

• 在 scope 宣告中新增或隱藏 OAuth 2.0 範圍。例如，您可以將範圍新增至僅指派範圍 aws.cognito.signin.user.admin 的 Amazon Cognito 使用者集區 API 身份驗證所產生的存取權杖。

• 變更使用者集區群組中的使用者成員資格。

• 新增尚未存在於 Amazon Cognito 存取權杖中的宣告。

• 禁止披露宣告，否則宣告會傳遞給您的應用程式。

若要支援使用者集區中的存取自訂，您必須設定使用者集區以產生觸發請求的更新版本。更新您的使用者集區，如下列流程所示。

AWS Management Console

若要支援產生權杖前 Lambda 觸發程序中的存取權杖自訂

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

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

3. 如果您尚未啟用，請從應用程式整合標籤啟用進階安全性功能。

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

5. 新增或編輯產生權杖前觸發程序。

6. 在指派 Lambda 函數下選擇一個 Lambda 函數。

7. 選擇基本功能 + 存取權杖自訂的觸發事件版本。此設定會更新 Amazon Cognito 傳送至您函數的請求參數，以包含用於存取權杖自訂的欄位。

User pools API

若要支援產生權杖前 Lambda 觸發程序中的存取權杖自訂

產生CreateUserPool或 UpdateUserPoolAPI 要求。您必須為不想設定為預設值的所有參數指定一個值。如需詳細資訊，請參閱 更新使用者集區組態。

在請求的 LambdaVersion 參數中包含以下內容。V2_0 的 LambdaVersion 值會導致您的使用者集區新增參數以進行存取權杖自訂。若要叫用特定函數版本，請使用 Lambda 函數 ARN，並將函數版本作為 LambdaArn 的值。

"PreTokenGenerationConfig": { 
   "LambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:MyFunction",
   "LambdaVersion": "V2_0"
},

其他 資源

• 如何在 Amazon Cognito 用戶池中自定義訪問令牌

產生權杖前 Lambda 觸發程序來源

triggerSource 值	事件
TokenGeneration_HostedAuth	在身分驗證期間，從 Amazon Cognito 託管的 UI 登入頁面呼叫。
TokenGeneration_Authentication	在使用者身分驗證流程完成之後呼叫。
TokenGeneration_NewPasswordChallenge	在管理員建立使用者之後呼叫。當使用者必須變更臨時密碼時，會叫用此流程。
TokenGeneration_AuthenticateDevice	在使用者裝置的身分驗證結束時呼叫。
TokenGeneration_RefreshTokens	當使用者嘗試重新整理身分和存取權杖時呼叫。

產生權杖前 Lambda 觸發程序參數

Amazon Cognito 傳遞至此 Lambda 函數的請求，是以下參數和 Amazon Cognito 新增至所有請求的常用參數之組合。當您將產生權杖前 Lambda 觸發程序新增至使用者集區時，您可以選擇觸發程序版本。此版本決定 Amazon Cognito 是否將請求傳遞至您的 Lambda 函數 以及用於存取權杖自訂的其他參數。

Version 1

版本 1 令牌可以在 ID 令牌中設置組成員資格，IAM 角色和新聲明。

{
    "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"
            }
        }
    }
}

Version 2

版本 2 請求事件添加了自定義訪問令牌的字段。它還增加了對響應對象複雜claimsToOverride數據類型的支持。您的 Lambda 函數可以傳回下列類型的資料值claimsToOverride：

• 字串

• Number

• 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	您的用戶所屬的使用者集區。	1
iamRolesTo覆寫	您可以將使用者集區群組與 AWS Identity and Access Management (IAM) 角色建立關聯。此元素是使用者所屬群組中所有 IAM 角色的清單。	1
preferredRole	您可以為使用者集區群組設定優先順序。此元素包含 groupsToOverride 元素中優先度最高之群組的 IAM 角色名稱。	1
clientMetadata	針對權杖產生前觸發程序，您可以做為 Lambda 函數 的自訂輸入來指定與 提供的一個或多個鍵值組。 若要將此資料傳遞至 Lambda 函數，請在AdminRespondToAuthChallenge和 RespondToAuthChallengeAPI 作業中使用 ClientMetadata參數。Amazon Cognito 不會在傳遞給預先權杖產生函ClientMetadata數的請求中包含來自參數AdminInitiateAuth和 InitiateAuthAPI 操作的資料。	1
範圍	您的使用者的 OAuth 2.0 範圍。存取權杖中存在的範圍是使用者請求的使用者集區標準範圍和自訂範圍，以及您授權應用程式用戶端發佈的範圍。	2

產生權杖前回應參數

名稱	描述	最小觸發事件版本
claimsOverrideDetails	V1_0 觸發事件中所有元素的容器。	1
claimsAndScopeOverrideDetails	V2_0 觸發事件中所有元素的容器。	2
idTokenGeneration	您要在使用者 ID 權杖中覆寫、新增或抑制的宣告。ID 權杖自訂值的父元素僅出現在版本 2 事件中，但子元素出現在版本 1 事件中。	2
accessTokenGeneration	您想要在使用者的存取權杖中覆寫、新增或抑制的宣告和範圍。此存取權杖自訂值的父元素僅出現在版本 2 事件中。	2
claimsToAddOrOverride	您要新增或修改的一或多個宣告及其值的映射。對於與群組相關的宣告，請改用 groupOverrideDetails。 在版本 2 事件中，此元素顯示於 accessTokenGeneration 和 idTokenGeneration 之下。	1*
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
scopesToAdd	您想要新增至使用者存取權杖中 scope 宣告的 OAuth 2.0 範圍清單。您無法新增包含一或多個空白字元的範圍值。	2
scopesToSuppress	您想要從使用者存取權杖的 scope 宣告中移除的 OAuth 2.0 範圍清單。	2

^* 版本 1 事件的回應物件可傳回字串。對版本 2 事件的響應對象可以返回複雜的對象。

觸發權杖前事件版本二範例：新增和抑制宣告，範圍和群組

此範例會對使用者的權杖進行下列修改。

1. 在 ID 權杖中將其 family_name 設置為 Doe。

2. 防止 email 和 phone_number 宣告出現在 ID 權杖中。

3. 將其 ID 權杖 cognito:roles 宣告設置為 "arn:aws:iam::123456789012:role\/sns_callerA","arn:aws:iam::123456789012:role\/sns_callerC","arn:aws:iam::123456789012:role\/sns_callerB"。

4. 將其 ID 權杖 cognito:preferred_role 宣告設置為 arn:aws:iam::123456789012:role/sns_caller。

5. 將範圍 openid、email 和 solar-system-data/asteroids.add 新增到存取權杖。

6. 抑制存取權杖的範圍 phone_number 和 aws.cognito.signin.user.admin。移除 phone_number 可防止從 userInfo 中擷取使用者的電話號碼。移除 aws.cognito.signin.user.admin 可防止使用者透過 Amazon Cognito 使用者集區 API 讀取和修改自身設定檔的 API 請求。

   注意

   如存取權杖中的剩餘範圍包含 openid 與至少一個標準範圍，從範圍中刪除 phone_number 僅會防止擷取用戶的電話號碼。如需詳細資訊，請參閱 關於範圍。

7. 將其 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": "[phone]",
            "family_name": "Zoe",
            "email": "[e-mail]"
        },
        "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": []
    }
}

前令牌生成事件版本二示例：添加具有複雜對象的聲明

此範例會對使用者的權杖進行下列修改。

1. 將數字，字符串，布爾和 JSON 類型的聲明添加到 ID 令牌。這是第二版觸發器事件對 ID 令牌可用的唯一更改。

2. 將數字，字符串，布爾和 JSON 類型的聲明添加到訪問令牌。

3. 將三個範圍添加到訪問令牌。

4. 隱藏 ID email 和存取權杖中的和sub宣告。

5. 隱藏存取權杖中的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","sub"]
            },
            "accessTokenGeneration": {
                "claimsToAddOrOverride": claims,
                "claimsToSuppress": ["email","sub"],
                "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": "[phone]",
            "email": "[e-mail]"
        },
        "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 觸發程序事件。

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": {}
}