事件版本声明和范围参考 ID 令牌自定义访问令牌自定义触发源参数示例：添加和隐藏索赔示例：复杂对象示例：添加和隐藏索赔 V1 示例：更改群组和角色 V1

令牌生成前 Lambda 触发器

由于 Amazon Cognito 会在令牌生成之前调用此触发器，您可以自定义用户池令牌中的声明。使用版本 1 或 V1_0 令牌生成前触发器事件的基本功能，可以自定义身份（ID）令牌。在具有 Essentials 或 Plus 功能计划的用户池中，您可以使用访问令牌自定义生成版本二或V2_0触发事件，以及通过 machine-to-machine (M2M) 客户端凭证授予的访问令牌自定义来生成版本三或V3_0触发事件。

Amazon Cognito 将向您的函数发送 V1_0 请求，其中包含将写入 ID 令牌的数据。V2_0或V3_0事件是指包含由 Amazon Cognito 写入身份令牌和访问令牌的数据的单个请求。要自定义这两个令牌，您必须更新函数以使用触发器版本二或三，并在同一个响应中发送两个令牌的数据。

Amazon Cognito 将版本二的事件响应应用于通过用户身份验证获得的访问令牌，其中人类用户已向您的用户池出示了证书。第三版事件响应适用于来自用户身份验证和计算机身份验证的访问令牌，其中自动化系统使用应用程序客户端密钥来授权访问令牌请求。除了生成的访问令牌的情况外，版本二和版本三的事件是相同的。

在 Amazon Cognito 向您的应用程序发布身份和访问令牌之前，此 Lambda 触发器可以添加、删除和修改这些令牌中的某些声明。要使用此功能，可以从 Amazon Cognito 用户池控制台关联 Lambda 函数或通过 Amazon Command Line Interface （Amazon CLI）更新用户池 LambdaConfig。

事件版本

您的用户池可以向您的 Lambda 函数提供不同版本的令牌生成前触发事件。V1_0 触发器提供用于修改 ID 令牌的参数。V2_0或V3_0触发器提供以下各项的参数。

V1_0 触发器的功能。
能够自定义访问令牌。
能够将复杂的数据类型传递给 ID 令牌和访问令牌声明值：
- 字符串
- 数字
- 布尔值
- 由字符串、数字、布尔值或它们的组合构成的数组
- JSON

注意

在 ID 令牌中，您可以将复杂对象填充到除了 phone_number_verified、email_verified、updated_at 和 address 之外的声明值。

默认情况下，用户池传送 V1_0 事件。要将您的用户池配置为发送V2_0事件，请在 Amazon Cognito 控制台中配置触发器时，选择基本功能的触发事件版本 +用户身份访问令牌自定义。要生成V3_0事件，请选择基本功能 + 用户和计算机身份的访问令牌自定义。您也可以在UpdateUserPool 或 CreateUserPool API 请求的LambdaVersionLambdaConfig参数中设置的值。活动版本一、二和三在 E ssential s 和 Plus 功能计划中可用。第三版活动的 M2M 操作的定价结构与月活跃用户 (MAU) 公式分开。有关更多信息，请参阅 Amazon Cognito 定价。

注意

在 2024 年 11 月 22 日 18:00（格林威治标准时间）当天或之前使用 “高级安全功能” 选项运行且仍处于精简版功能层的用户池可以访问令牌生成前触发器的第一和第二版事件版本。此传统级别中没有高级安全功能的用户池可以访问事件版本一。第三版仅在 Essentials 和 Plus 中可用。

声明和范围参考

Amazon Cognito 限制了您可以在访问令牌和身份令牌中添加、修改或隐藏的声明和范围。下表描述了您的 Lambda 函数可以修改和不能修改的声明，以及影响声明存在或价值的触发事件参数。

Claim	默认令牌类型	可以添加吗？	可以修改吗？	可以抑制吗？	事件参数-添加或修改	事件参数-抑制	身份类型	活动版本
任何不在用户池令牌架构中的声明	无	支持	是	不适用	`claimsToAddOrOverride`	`claimsToSuppress`	用户、机器 ¹	全部 ²
`scope`	访问	支持	是	是	`scopesToAdd`	`scopesToSuppress`	用户、机器 ¹	`v2_0`, `v3_0`
`cognito:groups`	身份证、访问权限	支持	是	是	`groupsToOverride`	`claimsToSuppress`	用户	全部 ²
`cognito:preferred_role`	ID	支持	是	是	`preferredRole`	`claimsToSuppress`³	用户	全部
`cognito:roles`	ID	支持	是	是	`iamRolesToOverride`	`claimsToSuppress`³	用户	全部
`cognito:username`	ID	否	否	否	不适用	不适用	用户	不适用
任何其他带有`cognito:`前缀的索赔	无	否	否	否	不适用	不适用	不适用	不适用
`username`	访问	否	否	否	不适用	不适用	用户	`v2_0`, `v3_0`
`sub`	身份证、访问权限	否	否	否	不适用	不适用	用户	不适用
标准 OIDC 属性	ID	支持	是	是	`claimsToAddOrOverride`	`claimsToSuppress`	用户	全部
`custom:` 属性	ID	支持	是	是	`claimsToAddOrOverride`	`claimsToSuppress`	用户	全部
`dev:` 属性	ID	否	否	是	不适用	`claimsToSuppress`	用户	全部
`identities`	ID	否	否	否	不适用	不适用	用户	不适用
`aud`⁴	ID	否	否	否	不适用	不适用	用户、机器	不适用
`client_id`	访问	否	否	否	不适用	不适用	用户、机器	不适用
`event_id`	访问	否	否	否	不适用	不适用	用户、机器	不适用
`device_key`	访问	否	否	否	不适用	不适用	用户	不适用
`version`	访问	否	否	否	不适用	不适用	用户、机器	不适用
`acr`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`amr`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`at_hash`	ID	否	否	否	不适用	不适用	用户、机器	不适用
`auth_time`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`azp`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`exp`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`iat`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`iss`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`jti`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`nbf`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`nonce`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`origin_jti`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用
`token_use`	身份证、访问权限	否	否	否	不适用	不适用	用户、机器	不适用

¹ 机器身份的访问令牌仅适用于触v3_0发器输入事件。活动版本三仅在 E ssential s 和 Plus 功能层中可用。精简版级别的用户池可以接收v1_0事件。具有高级安全功能的精简版用户池可以接收v1_0和v2_0事件。

² 将令牌生成前触发器配置v1_0为事件版本，仅适用v2_0于 ID 令牌、ID 和访问令牌、v3_0具有机器身份功能的 ID 和访问令牌。

³ 要取消cognito:preferred_role和cognito:roles声明，请添加cognito:groups到claimsToSuppress。

⁴ 您可以为访问令牌添加aud声明，但其值必须与当前会话的应用程序客户端 ID 相匹配。您可以从 event.callerContext.clientId 获取请求事件中的客户端 ID。

自定义身份令牌

使用令牌生成前 Lambda 触发器的所有事件版本，您可以自定义用户池中的身份 (ID) 令牌的内容。ID 令牌提供来自可信身份源的用户属性，用于登录 Web 或移动应用程序。有关 ID 令牌的更多信息，请参阅了解身份（ID）令牌。

将令牌生成前 Lambda 触发器与 ID 令牌结合使用，可实现以下目的。

在运行时更改您的用户从身份池中请求的 IAM 角色。
从外部来源添加用户属性。
添加或替换现有用户属性值。
隐藏用户属性，否则这些属性由于用户获得的授权范围以及您授予应用程序客户端的属性读取权限，会传递给您的应用程序。

自定义访问令牌

使用令牌生成前 Lambda 触发器的第二和第三个事件版本，您可以自定义用户池中访问令牌的内容。访问令牌授权用户从受访问保护的资源（例如 Amazon Cognito 令牌授权的 API 操作和第三方）中检索信息。 APIs对于使用客户凭证授予的 machine-to-machine（M2M）授权，Amazon Cognito 仅在您的用户池配置为版本三 () 事件时才会调用令牌生成前触发器。V3_0有关访问令牌的更多信息，请参阅了解访问令牌。

将令牌生成前 Lambda 触发器与访问令牌结合使用，可实现以下目的。

在scope声明中添加或隐藏作用域。例如，您可以将范围添加到由 Amazon Cognito 用户池 API 身份验证生成的访问令牌中，该身份验证仅分配范围 aws.cognito.signin.user.admin。
更改用户在用户池组中的成员资格。
添加尚不存在于 Amazon Cognito 访问令牌中的声明。
隐藏原本会传递到应用程序的声明。

要在用户池中支持访问自定义，必须将用户池配置为生成触发器请求的更新版本。请按照如下所示的过程更新用户池。

machine-to-machine(M2M) 客户端凭证的客户端元数据

您可以在 M2M 请求中传递客户端元数据。客户机元数据是来自用户或应用程序环境的其他信息，这些信息可能有助于实现的结果令牌生成前 Lambda 触发器。在使用用户委托人的身份验证操作中，您可以将客户端元数据传递给 RespondToAuthChallengeAPI 请求正文中的令牌生成前触发器。AdminRespondToAuthChallenge由于应用程序通过直接向 M2M 请求来执行生成访问令牌的流程令牌端点，因此它们的模型不同。在客户端凭证令牌请求的 POST 正文中，将带有客户端元数据对象 URL-encoded (x-www-form-urlencoded) 的aws_client_metadata参数传递给字符串。有关示例请求，请参阅具有基本授权的客户凭证。以下是传递键值对的示例参数。{"environment": "dev", "language": "en-US"}


aws_client_metadata=%7B%22environment%22%3A%20%22dev%22,%20%22language%22%3A%20%22en-US%22%7D

令牌生成前 Lambda 触发器源

triggerSource 值	活动
`TokenGeneration_HostedAuth`	在身份验证期间从 Amazon Cognito 托管的登录登录页面调用。
`TokenGeneration_Authentication`	用户身份验证流完成之后调用。
`TokenGeneration_NewPasswordChallenge`	管理员创建用户之后调用。当用户必须更改临时密码时调用此流。
`TokenGeneration_ClientCredentials`	在 M2M 客户端凭证授予后调用。只有当您的活动版本为时，您的用户池才会发送此事件`V3_0`。
`TokenGeneration_AuthenticateDevice`	用户设备身份验证结束时调用。
`TokenGeneration_RefreshTokens`	用户尝试刷新身份和令牌时调用。

令牌生成前 Lambda 触发器参数

Amazon Cognito 传递给此 Lambda 函数的请求是以下参数和 Amazon Cognito 添加到所有请求中的常用参数的组合。在向用户池添加令牌生成前 Lambda 触发器时，您可以选择触发器版本。此版本决定 Amazon Cognito 是否将请求以及用于自定义访问令牌的附加参数传递给您的 Lambda 函数。

Version one

版本一令牌可以设置群组成员资格、IAM 角色和 ID 令牌中的新声明。群组成员资格优先权也适用于访问令牌中的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

版本二和版本三的请求事件添加了自定义访问令牌的字段。用户池将版本三事件的更改应用于计算机身份的访问令牌。这些版本还增加了对响应对象中复杂claimsToOverride数据类型的支持。您的 Lambda 函数可以在 claimsToOverride 值中返回以下类型的数据：

字符串
数字
布尔值
由字符串、数字、布尔值或它们的组合构成的数组
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覆盖	您可以将用户池组与 Amazon Identity and Access Management (IAM) 角色关联。此元素是您的用户所属组中的所有 IAM 角色的列表。	1
preferredRole	您可以为用户池组设置一个优先级。此元素包含 `groupsToOverride` 元素中具有最高优先级组中的 IAM 角色的名称。	1
clientMetadata	一个或多个键值对，您可以指定它们并将它们作为自定义输入提供给 Lambda 函数以用于令牌生成前的触发器。要将此数据传递给您的 Lambda 函数，请使用AdminRespondToAuthChallenge和 RespondToAuthChallengeAPI 操作中的 ClientMetadata参数。Amazon Cognito 在传递给令牌生成前函数的请求中不包含来自`ClientMetadata`参数AdminInitiateAuth和 InitiateAuthAPI 操作的数据。	1
范围	访问令牌范围。访问令牌中的范围是您的用户请求且您授权应用程序客户端发布的用户池标准范围和自定义范围。	2

令牌生成前响应参数

名称	说明	最低触发器事件版本
claimsOverrideDetails	用于存放 `V1_0` 触发器事件中所有元素的容器。	1
claimsAndScopeOverrideDetails	`V2_0`或`V3_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` 声明。在访问令牌和 ID 令牌中，您的 `groupOverrideDetails` 对象将替换 `cognito:groups` 声明。组覆盖是版本 1 事件可以对访问令牌进行的唯一更改。	1
scopesToAdd	您要添加到用户访问令牌中的`scope`声明的范围列表。不能添加包含一个或多个空格字符的范围值。	2
scopesToSuppress	您要从用户访问令牌中的`scope`声明中移除的范围列表。	2

^* 版本一事件的响应对象可以返回字符串。版本二和版本三事件的响应对象可以返回复杂的对象。

令牌生成前触发器事件版本 2 示例：添加和隐藏声明、范围及组

此示例对用户的令牌进行了以下修改。

在 ID 令牌中将其 family_name 设置为 Doe。
防止 email 和 phone_number 声明出现在 ID 令牌中。
将其 ID 令牌 cognito:roles 声明设置为 "arn:aws:iam::123456789012:role\/sns_callerA","arn:aws:iam::123456789012:role\/sns_callerC","arn:aws:iam::123456789012:role\/sns_callerB"。
将其 ID 令牌 cognito:preferred_role 声明设置为 arn:aws:iam::123456789012:role/sns_caller。
将作用域 openid、email 和 solar-system-data/asteroids.add 添加到访问令牌中。
隐藏访问令牌的作用域 phone_number 和 aws.cognito.signin.user.admin。删除 phone_number 可阻止从 userInfo 中检索用户的电话号码。删除 aws.cognito.signin.user.admin 可阻止用户通过 Amazon Cognito 用户池 API 请求读取和修改自己的个人资料。

注意
只有当访问令牌中的剩余作用域包括 openid 和至少一个其他标准作用域时，从作用域中删除 phone_number 才会阻止检索用户的电话号码。有关更多信息，请参阅关于范围。
将其 ID 和访问令牌 cognito:groups 声明设置为 "new-group-A","new-group-B","new-group-C"。

Amazon Cognito 将事件信息传递给 Lambda 函数。随后，该函数将相同事件对象随同响应中的任何更改返回给 Amazon Cognito。在 Lambda 控制台中，您可以设置一个测试事件，该事件包含与您的 Lambda 触发器相关的数据。以下是此代码示例的一个测试事件：

令牌生成前事件版本 2 示例：添加包含复杂对象的声明

此示例对用户的令牌进行了以下修改。

将数字、字符串、布尔值和 JSON 类型的声明添加到 ID 令牌。这是版本二触发器事件可对 ID 令牌进行的唯一更改。
将数字、字符串、布尔值和 JSON 类型的声明添加到访问令牌。
将三个范围添加到访问令牌。
隐藏 ID 和访问令牌中的email声明。
隐藏访问令牌中的 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);
};

令牌生成前事件版本 1 示例：添加新声明并隐藏现有声明

此示例将版本 1 触发器事件与令牌生成前 Lambda 函数结合使用，以添加新声明并隐藏现有声明。

Amazon Cognito 将事件信息传递给 Lambda 函数。随后，该函数将相同事件对象随同响应中的任何更改返回给 Amazon Cognito。在 Lambda 控制台中，您可以设置一个测试事件，该事件包含与您的 Lambda 触发器相关的数据。以下是此代码示例的测试事件：由于该代码示例不处理任何请求参数，因此您可以使用带有空请求的测试事件。有关常见请求参数的更多信息，请参阅用户池 Lambda 触发器事件。

令牌生成前事件版本 1 示例：修改用户的组成员资格

此示例将版本 1 触发器事件与令牌生成前 Lambda 函数结合使用，以修改用户的组成员资格。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

验证身份验证质询响应 Lambda 触发器

迁移用户