令牌生成前 Lambda 触发器 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

令牌生成前 Lambda 触发器

由于 Amazon Cognito 在令牌生成之前调用此触发器,您可以自定义身份令牌声明。

您可以使用此 Amazon Lambda 触发器在 Amazon Cognito 生成身份令牌之前自定义身份令牌。您可以使用此触发器来在身份令牌中添加新声明、更新声明或者隐藏声明。要使用此功能,可以从 Amazon Cognito 用户池控制台关联 Lambda 函数或通过 Amazon Command Line Interface (Amazon CLI) 更新用户池。

您无法修改以下声明:

  • acr

  • amr

  • aud

  • at_hash

  • auth_time

  • azp

  • cognito:username

  • exp

  • iat

  • identities

  • iss

  • jti

  • nbf

  • nonce

  • origin_jti

  • sub

  • token_use

令牌生成前 Lambda 触发器源

triggerSource 值 触发事件
TokenGeneration_HostedAuth 通过 Amazon Cognito 托管 UI 登录页进行身份验证时调用。
TokenGeneration_Authentication 用户身份验证流完成之后调用。
TokenGeneration_NewPasswordChallenge 管理员创建用户之后调用。当用户必须更改临时密码时调用此流。
TokenGeneration_AuthenticateDevice 用户设备身份验证结束时调用。
TokenGeneration_RefreshTokens 用户尝试刷新身份和令牌时调用。

令牌生成前 Lambda 触发器参数

这些是 Amazon Cognito 随同常见参数中的事件信息一起传递给此 Lambda 函数的参数。

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

令牌生成前请求参数

groupConfiguration

包含当前组配置的输入对象。对象包括 groupsToOverrideiamRolesToOverridepreferredRole

groupsToOverride

与接收身份令牌的用户相对应的组名称的列表。

iamRolesToOverride

与这些组对应的当前 Amazon Identity and Access Management (IAM) 角色的列表。

preferredRole

指示首选 IAM 角色的字符串。

clientMetadata

一个或多个键值对,您可以指定它们并将它们作为自定义输入提供给 Lambda 函数以用于令牌生成前的触发器。要将此数据传递给 Lambda 函数,请在 AdminRespondToAuthChallengeRespondToAuthChallenge API 操作中使用 ClientMetadata 参数。Amazon Cognito 在传递到令牌生成前函数的请求中,不包括 AdminInitiateAuthInitiateAuth API 操作的 ClientMetadata 参数中传递的数据。

令牌生成前响应参数

claimsToAddOrOverride

要添加或覆盖的声明的一个或多个键值对的映射。对于与组相关的声明,请改用 groupOverrideDetails。

claimsToSuppress

包含您希望 Amazon Cognito 在身份令牌中隐藏的声明的列表。

注意

如果您的函数同时隐藏并替换了声明值,则 Amazon Cognito 会隐藏声明。

groupOverrideDetails

包含当前组配置的输出对象。对象包括 groupsToOverrideiamRolesToOverridepreferredRole

您的函数将 groupOverrideDetails 对象替换为您提供的对象。如果您在响应中提供空的或空对象,则 Amazon Cognito 将隐藏组。要保持现有组配置不变,请将请求的 groupConfiguration 对象的值复制到响应中的 groupOverrideDetails 对象。然后将其传回服务。

Amazon Cognito ID 令牌和访问令牌都包含 cognito:groups 声明。在访问令牌和 ID 令牌中,您的 groupOverrideDetails 对象将替换 cognito:groups 声明。

令牌生成前示例:添加新声明并隐藏现有声明

此示例使用令牌生成前 Lambda 函数添加新声明和隐藏现有声明。

Node.js
exports.handler = (event, context, callback) => { event.response = { "claimsOverrideDetails": { "claimsToAddOrOverride": { "attribute_key2": "attribute_value2", "attribute_key": "attribute_value" }, "claimsToSuppress": ["email"] } }; // Return to Amazon Cognito callback(null, event); };

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

JSON
{ "request": {}, "response": {} }

令牌生成前示例:修改用户的组成员资格

此示例使用令牌生成前 Lambda 函数修改用户的组成员资格。

Node.js
exports.handler = (event, context, callback) => { event.response = { "claimsOverrideDetails": { "claimsToAddOrOverride": { "attribute_key2": "attribute_value2", "attribute_key": "attribute_value" }, "claimsToSuppress": ["email"], "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 to Amazon Cognito callback(null, event); };

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

JSON
{ "request": {}, "response": {} }