使用 Lambda 触发器自定义用户池工作流 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用 Lambda 触发器自定义用户池工作流

您可以创建一个 Lambda 函数,然后在用户池操作 [如用户注册、确认和登录(身份验证)] 期间使用 Lambda 触发器触发该函数。您可以添加身份验证质询、迁移用户和自定义验证消息。

下表总结了使用 Lambda 触发器自定义用户池操作的一些方法:

用户池流 运算 说明

自定义身份验证流程

定义身份验证质询 确定自定义身份验证流中的下一个挑战
创建身份验证质询 在自定义身份验证流中创建挑战
验证身份验证质询响应 确定响应在自定义身份验证流中是正确的
身份验证事件 身份验证前 Lambda 触发器 自定义验证以接受或拒绝登录请求
身份验证后 Lambda 触发器 记录自定义分析的事件
令牌生成前 Lambda 触发器 增加或隐藏令牌声明
注册 注册前 Lambda 触发器 执行接受或拒绝注册请求的自定义验证
确认后 Lambda 触发器 为自定义分析添加自定义欢迎消息或事件日志记录
迁移用户 Lambda 触发器 将用户从现有用户目录迁移到用户池
消息 自定义消息 Lambda 触发器 执行消息的高级自定义和本地化
令牌创建 令牌生成前 Lambda 触发器 添加或删除 ID 令牌中的属性
电子邮件和 SMS 第三方提供商 自定义发件人 Lambda 触发器 使用第三方提供商发送 SMS 和电子邮件

重要注意事项

在使用 Lambda 函数之前,请考虑以下信息:

  • 除了自定义发件人 Lambda 触发器之外,Amazon Cognito 会同步调用 Lambda 函数。Amazon Cognito 调用您的 Lambda 函数时,函数必须在 5 秒内响应。如果没有及时响应,Amazon Cognito 将重新尝试调用。3 次尝试失败后,该函数将超时。您无法更改此 5 秒钟超时值。有关更多信息,请参阅 Lambda 编程模型

  • 如果您删除某个 Lambda 触发器,必须更新用户池中的相应触发器。例如,如果您删除身份验证后触发器,则必须在相应用户池中将 Post authentication(身份验证后)触发器设置为 none(无)。

  • 如果您的用户使用 Amazon Cognito 托管 UI,则他们可以看到 Lambda 触发器在查询参数(由 Amazon Cognito 添加到回调 URL)中生成的错误,但自定义发件人 Lambda 触发器除外。我们建议 Lambda 触发器仅生成您希望用户看到的错误。在 Lambda 触发器本身中记录任何敏感或调试信息。

  • 当您在 Amazon Cognito 控制台之外创建 Lambda 触发器时,您必须为 Lambda 函数添加权限。当您添加权限时,Amazon Cognito 可以代表您的用户池调用函数。您可以从 Lambda 控制台添加权限或者使用 Lambda AddPermission 操作。

    Lambda 基于资源的策略示例

    以下 Lambda 基于资源的策略示例授予 Amazon Cognito 有限调用 Lambda 函数的能力。Amazon Cognito 只能在代表 aws:SourceArn 中的用户池和 aws:SourceAccount 条件中的账户时才能调用函数。

    { "Version": "2012-10-17", "Id": "default", "Statement": [ { "Sid": "lambda-allow-cognito", "Effect": "Allow", "Principal": { "Service": "cognito-idp.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "<your Lambda function ARN>", "Condition": { "StringEquals": { "AWS:SourceAccount": "<your account number>" }, "ArnLike": { "AWS:SourceArn": "<your user pool ARN>" } } } ] }

针对联合身份用户的 Lambda 触发器

您可以使用以下 Lambda 触发器,为使用联合身份提供商登录的用户自定义用户池工作流。

注意
  • 联合身份用户必须使用 Amazon Cognito 托管的 UI 登录。

  • 对于某些操作,联合身份用户会调用多个 Lambda 函数。

联合身份用户触发器源
触发器 triggerSource 值 触发事件
注册前 PreSignUp_ExternalProvider 联合身份用户首次从 Amazon Cognito 托管 UI 登录页面登录。
确认后 PostConfirmation_ConfirmSignUp 联合身份用户首次从 Amazon Cognito 托管 UI 登录页面登录。
身份验证前 PreAuthentication_Authentication 联合身份用户从 Amazon Cognito 托管 UI 登录页面登录,但首次登录除外。
身份验证后 PostAuthentication_Authentication 联合身份用户从 Amazon Cognito 托管 UI 登录页面成功进行身份验证,但首次登录除外。
令牌生成前 TokenGeneration_HostedAuth 联合身份用户从 Amazon Cognito 托管 UI 登录页面成功进行身份验证且将要向其颁发令牌,但首次登录除外。

联合身份登录不会在您的用户池中调用任何 自定义身份验证质询 Lambda 触发器迁移用户 Lambda 触发器自定义消息 Lambda 触发器 或者自定义发件人 Lambda 触发器

添加用户池 Lambda 触发器

Original console

使用控制台添加用户池 Lambda 触发器

  1. 使用 Lambda 控制台创建 Lambda 函数。有关 Lambda 函数的更多信息,请参阅https://docs.amazonaws.cn/lambda/latest/dg/《Amazon Lambda 开发人员指南》。

  2. 转到 Amazon Cognito 控制台。选择 Manage User Pools(管理用户池)。

  3. 从列表中选择一个现有用户池,或创建一个用户池

  4. 在您的用户池中,从导航栏中选择 Triggers(触发器)选项卡。

  5. 选择 Lambda 触发器,例如注册前身份验证前。然后,从 Lambda function(Lambda 函数)下拉列表中选择 Lambda 函数。

  6. 选择 Save changes(保存更改)。

  7. 您可以在 Lambda 控制台中使用 Amazon CloudWatch 记录您的 Lambda 函数。有关更多信息,请参阅访问适用于 Lambda 的 Amazon CloudWatch Logs

New console

使用控制台添加用户池 Lambda 触发器

  1. 使用 Lambda 控制台创建 Lambda 函数。有关 Lambda 函数的更多信息,请参阅《Amazon Lambda 开发人员指南》https://docs.amazonaws.cn/lambda/latest/dg/

  2. 转到 Amazon Cognito 控制台,然后选择 User Pools(用户池)。

  3. 从列表中选择一个现有用户池,或创建一个用户池

  4. 选择 User pool properties(用户池属性)选项卡,并找到 Lambda triggers(Lambda 触发器)。

  5. 选择 Add a Lambda trigger(添加 Lambda 触发器)。

  6. 基于您希望自定义的身份验证阶段,选择 Lambda 触发器 Category(类别)。

  7. 选择 Assign Lambda function(分配 Lambda 函数),然后在同一个 Amazon Web Services 区域 中选择一个函数作为您的用户池。

    注意

    如果您的 Amazon Identity and Access Management (IAM) 凭证有权更新 Lambda 函数,Amazon Cognito 将添加基于 Lambda 资源的策略。通过此政策,Amazon Cognito 可以调用您选择的函数。如果登录凭证没有足够的 IAM 权限,则必须单独更新基于资源的策略。有关更多信息,请参阅重要注意事项

  8. 选择 Save changes(保存更改)。

  9. 您可以在 Lambda 控制台中使用 CloudWatch 记录您的 Lambda 函数。有关更多信息,请参阅访问适用于 Lambda 的 CloudWatch Logs

用户池 Lambda 触发器事件

Amazon Cognito 将事件信息传递给 Lambda 函数。随后,Lambda 函数将相同事件对象随同响应中的任何更改返回给 Amazon Cognito。此事件显示了 Lambda 触发器通用参数:

JSON
{ "version": "string", "triggerSource": "string", "region": AWSRegion, "userPoolId": "string", "userName": "string", "callerContext": { "awsSdkVersion": "string", "clientId": "string" }, "request": { "userAttributes": { "string": "string", .... } }, "response": {} }

用户池 Lambda 触发器通用参数

version

您的 Lambda 函数的版本号。

triggerSource

触发 Lambda 函数的事件的名称。有关每个 triggerSource 的说明,请参阅用户池 Lambda 触发器源

region

Amazon Web Services 区域,作为 AWSRegion 实例。

userPoolId

用户池的用户池 ID。

userName

当前用户的用户名。

callerContext

调用方上下文。此上下文包括以下内容:

awsSdkVersion

Amazon 开发工具包版本号。

clientId

用户池应用程序客户端 ID。

request

来自 Amazon Cognito 服务的请求。此请求必须包括以下参数:

userAttributes

一个或多个用户属性名称/值对。每一对的形式为 "name": "value"。

response

来自 Lambda 触发器的响应。响应中的返回参数取决于触发事件。

用户池 Lambda 触发器源

本节介绍每个 Amazon Cognito Lambda triggerSource 参数及其触发事件。

注册、确认和登录 (身份验证) 触发器
触发器 triggerSource 值 触发事件
注册前 PreSignUp_SignUp 注册前。
注册前 PreSignUp_AdminCreateUser 在管理员创建新用户时做好注册准备。
注册前 PreSignUp_ExternalProvider 适用于外部身份提供商的注册前。
确认后 PostConfirmation_ConfirmSignUp 注册后确认。
确认后 PostConfirmation_ConfirmForgotPassword 忘记密码后确认。
身份验证前 PreAuthentication_Authentication 身份验证前。
身份验证后 PostAuthentication_Authentication 身份验证后。
自定义身份验证质询触发器
触发器 triggerSource 值 触发事件
定义身份验证质询 DefineAuthChallenge_Authentication 定义身份验证质询。
创建身份验证质询 CreateAuthChallenge_Authentication 创建身份验证质询。
验证身份验证质询 VerifyAuthChallengeResponse_Authentication 验证身份验证质询响应。
令牌生成前触发器
触发器 triggerSource 值 触发事件
令牌生成前 TokenGeneration_HostedAuth Amazon Cognito 从您托管的 UI 登录页面对用户进行身份验证。
令牌生成前 TokenGeneration_Authentication 用户身份验证流程完成。
令牌生成前 TokenGeneration_NewPasswordChallenge 管理员创建用户。当用户必须更改临时密码时,Amazon Cognito 调用此项。
令牌生成前 TokenGeneration_AuthenticateDevice 结束用户设备身份验证。
令牌生成前 TokenGeneration_RefreshTokens 用户尝试刷新身份和访问令牌时调用。
迁移用户触发器
触发器 triggerSource 值 触发事件
用户迁移 UserMigration_Authentication 用户登录时进行迁移。
用户迁移 UserMigration_ForgotPassword 忘记密码流程中的用户迁移。
自定义消息触发器
触发器 triggerSource 值 触发事件
自定义消息 CustomMessage_SignUp 用户在您的用户池中注册时的自定义消息。
自定义消息 CustomMessage_AdminCreateUser 当您创建用户作为管理员并且 Amazon Cognito 向他们发送临时密码时的自定义消息。
自定义消息 CustomMessage_ResendCode 现有用户请求新的确认代码时的自定义消息。
自定义消息 CustomMessage_ForgotPassword 用户请求重置密码时的自定义消息。
自定义消息 CustomMessage_UpdateUserAttribute 用户更改其电子邮件地址或电话号码并且 Amazon Cognito 发送验证代码时的自定义消息。
自定义消息 CustomMessage_VerifyUserAttribute 用户添加电子邮件地址或电话号码并且 Amazon Cognito 发送验证代码时的自定义消息。
自定义消息 CustomMessage_Authentication 配置了 SMS MFA 的用户登录时的自定义消息。