事件版本声明和作用域参考 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参数中设置的值。事件版本一、二和三在基础版和增值版功能计划中均可用。版本三事件的 M2M 操作采用独立于每月活跃用户（MAU）计费公式的定价结构。有关更多信息，请参阅 Amazon Cognito 定价。

注意

在 GMT 时间 2024 年 11 月 22 日 18:00 或之前已启用高级安全功能选项并持续保留在精简版功能层级的用户池，可使用令牌生成前触发器的事件版本一和版本二。此旧版层级中未启用 高级安全功能的用户池仅可使用事件版本一。版本三仅在基础版和增值版中可用。

声明和作用域参考

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

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

¹ 机器身份的访问令牌仅适用于 v3_0 的触发器输入事件。事件版本三仅在基础版和增值版功能层级中可用。精简版层级的用户池可以接收 v1_0 事件。启用高级安全功能的精简版用户池可以接收 v1_0 和 v2_0 事件。

² 将您的令牌生成前触发器配置为：使用事件版本 v1_0 仅处理 ID 令牌，使用 v2_0 处理 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 正文中，传递一个 aws_client_metadata 参数，其值为客户端元数据对象经 URL 编码（x-www-form-urlencoded）后的字符串。有关示例请求，请参阅基本授权的客户端凭证。以下是传递键值对 {"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

版本一令牌可以在 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

版本二和三请求事件添加了可自定义访问令牌的字段。用户池可将版本三事件的更改应用于机器身份的访问令牌。这些版本还添加了对响应对象中复杂 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"
            }
        }
    }
}

令牌生成前请求参数

Name	说明	最低触发器事件版本
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

令牌生成前响应参数

Name	说明	最低触发器事件版本
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 触发器

迁移用户