本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 令牌生成前 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 函数或通过 AWS Command Line Interface （AWS CLI）更新用户池 `LambdaConfig`。 ## 事件版本 您的用户池可以向您的 Lambda 函数提供不同版本的令牌生成前触发事件。`V1_0` 触发器提供用于修改 ID 令牌的参数。`V2_0` 或 `V3_0` 触发器为以下项提供参数。 1. `V1_0` 触发器的功能。 1. 能够自定义访问令牌。 1. 能够将复杂的数据类型传递给 ID 令牌和访问令牌声明值： + 字符串 + 数字 + 布尔值 + 由字符串、数字、布尔值或它们的组合构成的数组 + JSON **注意** 在 ID 令牌中，您可以将复杂对象填充到除了 `phone_number_verified`、`email_verified`、`updated_at` 和 `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)参数中设置的值。事件版本一、二和三在**基础版**和**增值版**功能计划中均可用。版本三事件的 M2M 操作采用独立于每月活跃用户（MAU）计费公式的定价结构。有关更多信息，请参阅 [Amazon Cognito 定价](https://aws.amazon.com/cognito/pricing/)。 **注意** 在 GMT 时间 2024 年 11 月 22 日 18:00 或之前已启用**高级安全功能**选项并持续保留在**精简版**功能层级的用户池，可使用令牌生成前触发器的事件版本一和版本二。此旧版层级中*未启用* 高级安全功能的用户池仅可使用事件版本一。版本三*仅* 在基础版和增值版中可用。 ## 声明和作用域参考 Amazon Cognito 限制了您可以在访问令牌和身份令牌中添加、修改或隐藏的声明和作用域。下表描述了您的 Lambda 函数可以修改和不能修改的声明，以及影响声明存在或价值的触发器事件参数。 | 声明 | 默认令牌类型 | 是否可以添加？ | 是否可以修改？ | 是否可以隐藏？ | 事件参数 - 添加或修改 | 事件参数 - 隐藏 | 身份类型 | 事件版本 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 任何不在用户池令牌架构中的声明 | 无 | 支持 | 是 | 不适用 | 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 | 否 | 否 | 否 | 不适用 | 不适用 | 用户 | 不适用 | | 任何其他带有 cognito: 前缀的声明 | 无 | 否 | 否 | 否 | 不适用 | 不适用 | 不适用 | 不适用 | | username | 访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户 | v2\$10, v3\$10 | | sub | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户 | 不适用 | | 标准 OIDC 属性 | ID | 支持 | 是 | 是 | claimsToAddOrOverride | claimsToSuppress | 用户 | 全部 | | custom: 属性 | ID | 支持 | 是 | 是 | claimsToAddOrOverride | claimsToSuppress | 用户 | 全部 | | dev: 属性 | ID | 否 | 否 | 是 | 不适用 | claimsToSuppress | 用户 | 全部 | | identities | ID | 否 | 否 | 否 | 不适用 | 不适用 | 用户 | 不适用 | | aud[4](#cognito-pretoken-aud-note) | ID | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | client\$1id | 访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | event\$1id | 访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | device\$1key | 访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户 | 不适用 | | version | 访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | acr | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | amr | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | at\$1hash | ID | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | auth\$1time | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | azp | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | exp | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | iat | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | iss | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | jti | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | nbf | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | nonce | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | origin\$1jti | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | | token\$1use | ID、访问 | 否 | 否 | 否 | 不适用 | 不适用 | 用户、计算机 | 不适用 | 1 机器身份的访问令牌仅适用于 `v3_0` 的触发器输入事件。事件版本三仅在**基础版**和**增值版**功能层级中可用。**精简版**层级的用户池可以接收 `v1_0` 事件。启用高级安全功能的**精简版**用户池可以接收 `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 角色。 + 从外部来源添加用户属性。 + 添加或替换现有用户属性值。 + 隐藏用户属性，否则这些属性由于用户获得的授权范围以及您授予应用程序客户端的属性读取权限，会传递给您的应用程序。 ## 自定义访问令牌 使用令牌生成前 Lambda 触发器的事件版本二和三，您可以自定义来自用户池的访问令牌的内容。访问令牌授权用户从受访问保护的资源（例如 Amazon Cognito 令牌授权的 API 操作和第三方）中检索信息。 APIs对于使用客户凭证授予的 machine-to-machine（M2M）授权，Amazon Cognito 仅在您的用户池配置为版本三 () 事件时才会调用令牌生成前触发器。`V3_0`有关访问令牌的更多信息，请参阅[了解访问令牌](amazon-cognito-user-pools-using-the-access-token.md)。 将令牌生成前 Lambda 触发器与访问令牌结合使用，可实现以下目的。 + 在 `scope` 声明中添加或隐藏作用域。例如，您可以将作用域添加到由 Amazon Cognito 用户池 API 身份验证生成的访问令牌中，该身份验证仅分配作用域 `aws.cognito.signin.user.admin`。 + 更改用户在用户池组中的成员资格。 + 添加尚不存在于 Amazon Cognito 访问令牌中的声明。 + 隐藏原本会传递到应用程序的声明。 要在用户池中支持访问自定义，必须将用户池配置为生成触发器请求的更新版本。请按照如下所示的过程更新用户池。 ------ #### [ AWS 管理控制台 ] **在令牌生成前 Lambda 触发器中支持访问令牌自定义** 1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)，然后选择**用户池**。 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` 参数中包含以下内容。`V2_0` 的值为 `LambdaVersion` 会使您的用户池为访问令牌添加相关参数并应用更改。`V3_0` 的值为 `LambdaVersion` 会生成与 `V2_0` 相同的事件，但会使您的用户池*同样* 向 M2M 访问令牌应用更改。要调用特定的函数版本，请使用以函数版本作为 `LambdaArn` 值的 Lambda 函数 ARN。 ``` "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)的结果。在使用用户委托人的身份验证操作中，您可以将客户端元数据传递给 [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html)API 请求正文中的令牌生成前触发器。[AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html)由于应用程序通过直接向 [令牌端点](token-endpoint.md) 发出请求来执行为 M2M 生成访问令牌的流程，因此它们的模型不同。在客户端凭证令牌请求的 POST 正文中，传递一个 `aws_client_metadata` 参数，其值为客户端元数据对象经 URL 编码（`x-www-form-urlencoded`）后的字符串。有关示例请求，请参阅[基本授权的客户端凭证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) + [令牌生成前触发器事件版本 2 示例：添加和隐藏声明、作用域及组](#aws-lambda-triggers-pre-token-generation-example-version-2-overview) + [令牌生成前事件版本 2 示例：添加包含复杂对象的声明](#aws-lambda-triggers-pre-token-generation-example-version-2-complex-objects) + [令牌生成前事件版本 1 示例：添加新声明并隐藏现有声明](#aws-lambda-triggers-pre-token-generation-version-1-add-claim) + [令牌生成前事件版本 1 示例：修改用户的组成员资格](#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 ] 版本一令牌可以在 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 | 您的用户所属的[用户池组](cognito-user-pools-user-groups.md#cognito-user-pools-user-groups.title)。 | 1 | | iamRolesTo覆盖 | 您可以将用户池组与 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 在传递给令牌生成前函数的请求中不包含来自`ClientMetadata`参数[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 操作的数据。 | 1 | | 范围 | 访问令牌的作用域。访问令牌中的作用域是您的用户请求且您授权应用程序客户端发布的用户池标准作用域和自定义作用域。 | 2 | ### 令牌生成前响应参数 | Name | 说明 | 最低触发器事件版本 | | --- |--- |--- | | claimsOverrideDetails | 用于存放 V1\$10 触发器事件中所有元素的容器。 | 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` 声明。在访问令牌和 ID 令牌中，您的 `groupOverrideDetails` 对象将替换 `cognito:groups` 声明。组覆盖是版本 1 事件可以对访问令牌进行的唯一更改。 | 1 | | scopesToAdd | 您希望添加到用户访问令牌中的 `scope` 声明的作用域列表。不能添加包含一个或多个空格字符的作用域值。 | 2 | | scopesToSuppress | 您希望从用户访问令牌中的 `scope` 声明中移除的作用域列表。 | 2 | \$1 版本一事件的响应对象可以返回字符串。版本二和三事件的响应对象可以返回[复杂对象](#user-pool-lambda-pre-token-generation-event-versions)。 ## 令牌生成前触发器事件版本 2 示例：添加和隐藏声明、作用域及组 此示例对用户的令牌进行了以下修改。 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 请求读取和修改自己的个人资料。 **注意** 只有当访问令牌中的剩余作用域包括 `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 令牌。这是版本二触发器事件可对 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 示例：添加新声明并隐藏现有声明 此示例将版本 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 示例：修改用户的组成员资格 此示例将版本 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": {} } ``` ------