Amazon Cognito - 开发人员指南...Amazon Cognito 开发人员指南什么是 Amazon...

Amazon Cognito开发人员指南

Amazon Cognito 开发人员指南

Amazon Cognito 开发人员指南Copyright copy Amazon Web Services Inc andor its affiliates All rights reserved

Amazon 的商标和商业外观不得用于任何非 Amazon 的商品或服务也不得以任何可能引起客户混淆或者贬低或诋毁Amazon 的方式使用所有非 Amazon 拥有的其他商标均为各自所有者的财产这些所有者可能附属于 Amazon与Amazon 有关联或由 Amazon 赞助也可能不是如此

Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异要查看适用于中国区域的差异请参阅中国的 Amazon Web Services 服务入门


Table of Contents什么是 Amazon Cognito 1

Amazon Cognito 的特点 2Amazon Cognito 入门 2区域可用性 3Amazon Cognito 定价 3使用 Amazon Cognito 控制台 3

Amazon Cognito 入门 5获取 Amazon Web Services 账户和您的根用户凭证 5创建 IAM 用户 6作为 IAM 用户登录 7创建 IAM 用户访问密钥 7

Amazon Cognito 常见场景 9使用用户池进行身份验证 9访问您的服务器端资源 9使用 API Gateway 和 Lambda 访问资源 10访问Amazon包含用户池和身份池的服务 11与第三方进行身份验证和访问Amazon包含身份池的服务 11访问Amazon AppSyncAmazon Cognito 资源 12

教程 13创建用户池 13

相关资源 13创建身份池 13

相关资源 14清理您的Amazon资源 14

与应用程序集成 15Amazon Cognito 身份验证Amazon AmplifyFramework 15

多租户应用程序最佳实践 16基于用户池的多租户 16基于应用程序客户端的多租户 16基于集团的多租户 17基于属性的自定义多租户 17多租户安全建议 17

Amazon Cognito user pools 18用户池入门 19

先决条件注册 Amazon 账户 19步骤 1 创建用户池 19步骤 2 添加应用程序以启用托管 Web UI 20步驟 3 向用户池添加社交登录 (可选) 21步骤 4 将使用 SAML 身份提供商的登录添加到用户池 (可选) 26后续步骤 27

使用托管 UI 28使用 Amazon Amplify 设置托管 UI 28使用 Amazon Cognito 控制台设置托管 UI 28配置应用程序客户端 30配置域 33自定义内置网页 38定义资源服务器 41

添加通过第三方登录 43添加社交身份提供商 44添加 SAML 提供商 49添加 OIDC 提供商 55指定属性映射 60

使用 Lambda 触发器 63重要注意事项 64

iii


使用 Lambda 触发器 64用户池 Lambda 触发器事件 64用户池 Lambda 触发器通用参数 65Lambda 触发器源 66注册后 Lambda 器 67确认 Lambda 器 72身份验证前 Lambda 器 75身份验证后触 Lambda 器 78质询 Lambda 触发器 81令牌生成前 Lambda 器 90迁移用户 Lambda 触发器 93自定义消息 Lambda 触发器 96自定义发件人 Lambda 触发器 101

使用 Amazon Pinpoint 分析 107查找 Amazon Cognito 和 Amazon Pinpoint 区域映射 107

管理用户 109注册并确认用户账户 109以管理员身份创建用户 115向用户池添加组 118管理和搜索用户 120恢复用户帐户 123将用户导入一个用户池 124

电子邮件设置 134默认电子邮件功能 134Amazon SES 电子邮件配置 134配置电子邮件账户 134

SMS 消息设置 137首次在 Amazon Cognito 用户池中设置 SMS 消息 137

使用令牌 139使用 ID 令牌 139使用访问令牌 141使用刷新令牌 143撤销令牌 144验证 JSON Web 令牌 145

在登录后访问资源 147访问服务器端资源 9使用 API Gateway 和 Lambda 访问资源 148访问Amazon使用身份池的资源 149

用户池控制台参考 152用户池名称 153用户和组 153Attributes 153密码要求 158管理员创建用户策略 159电子邮件或电话验证 159消息自定义 160标签 163设备 163应用程序客户端 164触发 165审核设置 165分析 166应用程序客户端设置 167域名 167UI 自定义 168资源服务器 168身份提供商 168

iv


属性映射 171管理错误响应 172

Amazon Cognito 身份池 174身份池入门 174

注册 Amazon 账户 175在 Amazon Cognito 中创建一个身份池 175安装移动或 JavaScript 开发工具包 175整合身份提供商 176获取凭证 176

使用身份池 176用户 IAM 角色 176经过身份验证和未经身份验证的身份 177启用或禁用未经身份验证的身份 177更改与身份类型关联的角色 177启用或编辑身份验证提供商 177删除身份池 178从身份池删除身份 178管理数据集 178批量发布数据 179启用推送同步 179设置 Amazon Cognito 流 179设置 Amazon Cognito 活动 179

身份池概念 180身份池身份验证流程 180IAM 角色 184角色信任和权限 188

使用属性进行访问控制 189将属性用于访问控制与 Amazon Cognito 身份池一起使用 190使用属性作为访问控制策略示例 190禁用访问控制的属性 192默认提供商映射 192

基于角色的访问控制 193为角色映射创建角色 193授予传递角色权限 194使用令牌向用户分配角色 194使用基于规则的映射向用户分配角色 195基于规则的映射中使用的令牌声明 195基于角色的访问控制的最佳实践 196

获取凭证 196Android 197iOS - Objective-C 198iOS - Swift 198JavaScript 199Unity 200Xamarin 201

访问Amazon服务 202Android 202iOS - Objective-C 202iOS - Swift 202JavaScript 203Unity 203Xamarin 203

身份池外部身份提供商 203Facebook 204Login with Amazon 208Google 211使用 Apple 登录 217

v


OpenID Connect 提供商 221SAML 身份提供商 223

已经过开发人员验证的身份 224了解身份验证流程 225定义开发人员提供商名称并将其与身份池关联 225实施身份提供商 225更新登录映射 (仅限 Android 和 iOS) 230获取令牌 (服务器端) 231连接到现有社交身份 232支持在提供商之间转换 232

切换身份 235Android 235iOS - Objective-C 235iOS - Swift 235JavaScript 236Unity 236Xamarin 237

Amazon Cognito 同步 238Amazon Cognito Sync 入门 238

注册 Amazon 账户 238在 Amazon Cognito 中设置身份池 239存储和同步数据 239

同步数据 239正在初始化 Amazon Cognito Sync 239了解数据集 240在数据集中读取并写入数据 242使用同步存储空间同步本地数据 243

处理回调 245Android 246iOS - Objective-C 247iOS - Swift 249JavaScript 251Unity 253Xamarin 255

推送同步 257创建 Amazon SSimple Notification Service (Amazon SNS) 应用 257在 Amazon Cognito 控制台中启用推送同步 257在您的应用程序中使用推送同步Android 257在您的应用程序中使用推送同步iOS ndash Objective-C 259在您的应用程序中使用推送同步iOS ndash Swift 261

Amazon Cognito 流 262Amazon Cognito 事件 264

安全性 267数据保护 267

数据加密 268Identity and Access Management 268

Audience 268使用身份进行身份验证 269使用策略管理访问 270Amazon Cognito 如何与 IAM 协同工作 271基于身份的策略示例 277问题排查 279使用服务相关角色 281身份验证 283

日志记录和监控 289跟踪 CloudWatch 和 Service Quotas 中的配额和使用情况 289Amazon Cognito 用户池指标 289

vi


Amazon Cognito 用户池的尺寸 294使用 Service Quotas 控制台跟踪指标 294使用 CloudWatch 控制台跟踪指标 295为配额创建 CloudWatch 警报 295使用记录 Amazon Cognito API 调用Amazon CloudTrail 295使用 Amazon CloudTrail Watch Logs Insights 分析 Amazon Cognito 事件 297

合规性验证 298故障恢复能力 299

区域数据注意事项 299基础设施安全性 299配置和漏洞分析 300安全最佳实践 300

添加多重验证 (MFA) 300添加高级安全 303

Amazon 托管策略 311策略更新 312

为资源添加标签 313支持的资源 313标签限制 313使用控制台管理标签 313Amazon CLI 示例 314

分配标签 314查看标签 315删除标签 315在创建资源时应用标签 316

API 操作 316适用于用户池标签的 API 操作 316适用于身份池标签的 API 操作 316

配额 317操作配额 317配额分类 317操作特殊处理 317类别操作 318跟踪配额使用情况 321确定配额要求 322优化配额 322API 请求速率配额 322资源配额 323

可调整资源配额 323不可调整的资源配额 324

API 参考 326用户池 API 参考 326用户池 Auth API 参考 326

AUTHORIZATION 终端节点 326TOKEN 终端节点 331USERINFO 终端节点 334LOGIN 终端节点 336LOGOUT 终端节点 337撤销终端节点 338

身份池 API 参考 339Cognito 同步 API 参考 339

文档历史记录 340 cccxlv

vii


什么是 Amazon CognitoAmazon Cognito 为您的 Web 和移动应用程序提供身份验证授权和用户管理您的用户可使用用户名和密码直接登录也可以通过第三方（例如 FacebookAmazonGoogle 或 Apple）登录

Amazon Cognito 的两个主要组件是用户池和身份池用户池是为您的应用程序提供注册和登录选项的用户目录使用身份池您可以授予用户访问其他 Amazon 服务的权限您可以单独或配合使用身份池和用户池

Amazon Cognito 用户池和身份池配合使用

有关常见 Amazon Cognito 场景请参阅图表在这里目标是验证用户身份然后授予用户访问其他Amazon服务

1 在第一步中您的应用程序用户通过用户池登录并在成功进行身份验证后收到用户池令牌2 接下来您的应用程序将用户池令牌交换Amazon凭证3 最后您的应用程序用户可以使用这些Amazon凭证来访问其他Amazon服务例如 Amazon S3 或

DynamoDB

有关使用身份池和用户池的更多示例请参阅Amazon Cognito 常见场景 (p 9)

Amazon Cognito 符合 SOC 1-3PCI DSSISO 27001 的要求且符合 HIPAA-BAA 的条件有关更多信息请参阅 Amazon范围内的服务另请参阅区域数据注意事项 (p 299)

主题

1

Amazon Cognito 开发人员指南Amazon Cognito 的特点

bull Amazon Cognito 的特点 (p 2)bull Amazon Cognito 入门 (p 2)bull 区域可用性 (p 3)bull Amazon Cognito 定价 (p 3)bull 使用 Amazon Cognito 控制台 (p 3)

Amazon Cognito 的特点用户池

用户池是 Amazon Cognito 中的用户目录利用户池您的用户可以通过 Amazon Cognito 登录您的 Web 或移动应用程序或通过第三方身份提供商 (IdP) 联合登录无论您的用户是直接登录还是通过第三方登录用户池的所有成员都有一个可通过开发工具包访问的目录配置文件

用户池提供

bull 注册和登录服务bull 用于登录用户的内置的可自定义的 Web UIbull 使用 FacebookGoogleLogin with Amazon 和 Sign in with Apple 的社交登录以及通过您的用户池中

的 SAML 和 OIDC 身份提供商的登录bull 用户目录管理和用户配置文件bull 多重验证 (MFA)遭盗用凭证检查账户盗用保护以及电话和电子邮件验证等安全功能bull 通过 Amazon Lambda 触发器进行的自定义工作流程和用户迁移

有关用户池的更多信息请参阅用户池入门 (p 19)和Amazon Cognito 用户池 API 参考

身份池

利用户身份池您的用户可以获取临时Amazon要访问的凭证Amazon服务例如 Amazon S3 和DynamoDB身份池支持匿名访客用户以及可用来验证身份池用户的身份的以下身份提供商

bull Amazon Cognito 用户池bull 使用 FacebookGoogleLogin with Amazon 和 Sign in with Apple 的社交登录bull OpenID Connect (OIDC) 提供商bull SAML 身份提供商bull 已经过开发人员验证的身份

要保存用户配置文件信息您的身份池需要与用户池集成

有关身份池的更多信息请参阅Amazon Cognito 身份池入门 (联合身份) (p 174)和Amazon Cognito 身份池 API 参考

Amazon Cognito 入门有关首要任务和开始位置的指南请参阅 Amazon Cognito 入门 (p 5)

有关视频文章文档和示例应用程序请参阅Amazon Cognito 开发人员资源

要使用 Amazon Cognito您需要Amazonaccount 有关更多信息请参阅使用 Amazon Cognito 控制台 (p 3)

2

Amazon Cognito 开发人员指南区域可用性

区域可用性Amazon Cognito 提供多个Amazon面向全球的区域Amazon Cognito 分布在多个可用区内这些可用区的物理位置是相互隔离的但可通过私有低延迟高吞吐量和高度冗余的网络连接联合在一起这些可用区启用Amazon提供极高水平的可用性和冗余的服务（包括 Amazon Cognito）同时最大程度地减少延迟

有关 Amazon Cognito 当前提供的所有区域的列表请参阅Amazon区域和终端节点中的Amazon WebServices 通用参考要了解有关每个区域中可用的可用区数量的更多信息请参阅Amazon全球基础设施

Amazon Cognito 定价有关 Amazon Cognito 定价的信息请参阅Amazon Cognito 定价

使用 Amazon Cognito 控制台您可以使用Amazon Cognito 控制台创建和管理用户池和身份池

如何使用 Amazon Cognito 控制台

1 要使用 Amazon Cognito您需要注册Amazon账户2 转至Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证3 要创建或编辑用户池请选择管理您的用户池

有关更多信息请参阅用户池入门 (p 19)4 要创建或编辑身份池请选择 Manage Identity Pools (管理身份池)

有关更多信息请参阅 Amazon Cognito 身份池入门 (联合身份) (p 174)

Amazon Cognito 控制台是Amazon Web Services Management Console后者提供了有关账户和账单的信息有关更多信息请参阅使用 Amazon Web Services Management Console

3

Amazon Cognito 开发人员指南使用 Amazon Cognito 控制台

4

Amazon Cognito 开发人员指南获取 Amazon Web Services 账户和您的根用户凭证

Amazon Cognito 入门本节介绍 Amazon Cognito 首要任务以及开始位置有关 Amazon Cognito 的概述请参阅什么是 AmazonCognito (p 1)

Amazon Cognito 的两个主要组件是用户池和身份池用户池是为 Web 和移动应用程序提供注册和登录选项的用户目录身份池提供Amazon凭证以授予用户访问其他Amazon服务您可以单独使用或配合使用用户池和身份池

首要任务和开始位置

使用用户池添加注册和登录

1 使用用户池创建用户目录2 添加应用程序以启用托管 UI3 向用户池添加社交登录4 向用户池添加通过基于 SAML 的身份提供商 (IdP) 进行的登录5 向用户池添加通过 OpenID Connect (OIDC) IdP 进行的登录6 安装用户池开发工具包7 自定义内置托管 Web UI 登录页面和注册页面8 配置用户池安全功能9 使用 Lambda 触发器自定义用户池工作流程10 Amazon Pinpoint 分析收集数据和目标活动

在用户池中管理用户

bull 注册并确认用户账户bull 以管理员身份创建用户账户bull 管理和搜索用户账户bull 向用户池添加组bull 将用户导入到用户池

访问资源

常见的 Amazon Cognito 场景

bull 使用用户池进行身份验证bull 通过用户池访问后端资源bull 通过用户池访问 API Gateway 和 Lambdabull 访问Amazon具有用户池和身份池的服务bull 访问Amazon通过第三方和身份池提供服务bull 访问Amazon通过用户池或身份池访问的 AppSync 资源

获取 Amazon Web Services 账户和您的根用户凭证访问Amazon您必须注册 Amazon Web Services 账户

5

Amazon Cognito 开发人员指南创建 IAM 用户

注册 Amazon Web Services 账户

1 打开 httpsportalawsamazoncombillingsignup2 按照屏幕上的说明进行操作

在注册时您将接到一通电话要求您使用电话键盘输入一个验证码

Amazon注册过程完成后会向您发送一封确认电子邮件在任何时候您都可以通过转至 httpsawsamazoncom 并选择 My Account (我的账户) 来查看当前的账户活动并管理您的账户

创建 IAM 用户如果您的账户已包含具有完整Amazon管理员权限则可以跳过此部分

首次创建 Amazon Web Services (Amazon) 账户时您将以单一登录身份开始此身份具有对账户中所有Amazon 服务和资源的完全访问权限此身份称为 Amazon Web Services 账户根用户在登录时请输入您用于创建账户的电子邮件地址和密码

Important

强烈建议您不使用根用户执行日常任务即使是管理任务相反请遵循仅使用根用户创建您的第一个 IAM 用户的最佳实践然后请妥善保存根用户凭证仅用它们执行少数账户和服务管理任务要查看需要您以根用户身份登录的任务请参阅需要根用户凭证的任务

自行创建管理员用户并将该用户添加到管理员组（控制台）

1 登录IAM 控制台搜索作为帐户所有者方法是选择根用户并输入 Amazon Web Services 账户电子邮件地址在下一页上输入您的密码

Note

强烈建议您遵守以下使用 Administrator IAM 用户的最佳实践妥善保存根用户凭证只在执行少数账户和服务管理任务时才作为根用户登录

2 在导航窗格中选择用户然后选择添加用户3 对于 User name (用户名)输入 Administrator4 选中 Amazon Web Services Management Console 访问旁边的复选框然后选择自定义密码并在文

本框中输入新密码5 （可选）默认情况下Amazon 要求新用户在首次登录时创建新密码您可以清除 User must create a

new password at next sign-in (用户必须在下次登录时创建新密码) 旁边的复选框以允许新用户在登录后重置其密码

6 选择 NextPermissions (下一步权限)7 在设置权限下选择将用户添加到组8 选择创建组9 在 Create group (创建组) 对话框中对于 Group name (组名称)输入 Administrators10 选择 Filter policies (筛选策略)然后选择 Amazon managed - job function (Amazon 托管的工作职能) 以

筛选表内容11 在策略列表中选中 AdministratorAccess 的复选框然后选择 Create group (创建组)

Note

您必须先激活 IAM 用户和角色对账单的访问权限然后才能使用 AdministratorAccess 权限访问 Amazon Billing and Cost Management 控制台为此请按照ldquo向账单控制台委派访问权限rdquo教程第 1 步中的说明进行操作

12 返回到组列表中选中您的新组所对应的复选框如有必要选择 Refresh 以在列表中查看该组

6

Amazon Cognito 开发人员指南作为 IAM 用户登录

13 选择 Next标签14 （可选）通过以键值对的形式附加标签来向用户添加元数据有关在 IAM 中使用标签的更多信息请参

阅《IAM 用户指南》中的标记 IAM 实体15 选择 Next审核以查看要添加到新用户的组成员资格的列表如果您已准备好继续请选择 Create

user

您可以使用此相同的流程创建更多的组和用户并允许您的用户访问 Amazon Web Services 账户资源的费用要了解有关使用策略限制用户对特定 Amazon 资源的权限的信息请参阅访问管理和示例策略

作为 IAM 用户登录登录IAM 控制台搜索通过选择IAM 用户并输入 Amazon Web Services 账户 ID 或账户别名在下一页上输入您的 IAM 用户名和密码

Note

为方便起见Amazon登录页面使用浏览器 Cookie 记住您的 IAM 用户名和账户信息如果您先前作为其他用户登录请选择按钮下方的 Sign-in user (登录) 以返回主登录页面在此处您可以输入Amazon Web Services 账户要重定向到您账户的 IAM 用户登录页面的 ID 或账户别名

创建 IAM 用户访问密钥访问密钥包含访问密钥 ID 和秘密访问密钥用于签署对发出的编程请求Amazon 如果没有访问密钥您可以使用进行创建Amazon Web Services Management Console 作为最佳实践请勿使用 Amazon WebServices 账户根用户访问密钥用于不必要时的任何任务而是为自己创建一个具有访问密钥的新管理员IAM 用户

仅当创建访问密钥时您才能查看或下载秘密访问密钥以后您无法恢复它们不过您随时可以创建新的访问密钥您还必须拥有执行所需 IAM 操作的权限有关更多信息请参阅 IAM 用户指南中的访问 IAM 资源所需的权限

为 IAM 用户创建访问密钥

1 登录 Amazon Web Services Management Console单击 httpsconsoleawsamazoncomiam 打开IAM 控制台

2 在导航窗格中选择 Users3 选择要为其创建访问密钥的用户的名称然后选择 Security credentials (安全凭证) 选项卡4 在 Access keys (访问密钥) 部分选择 Create access key (创建访问密钥)5 要查看新访问密钥对请选择 Show (显示)关闭此对话框后您将无法再次访问该秘密访问密钥您

的凭证与下面类似

bull 访问密钥 IDAKIAIOSFODNN7EXAMPLE AKIAIOSFODNN7EXAMPLEbull 秘密访问密钥wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY

6 要下载密钥对请选择下载 csv 文件将密钥存储在安全位置关闭此对话框后您将无法再次访问该秘密访问密钥

请对密钥保密以保护您的 Amazon Web Services 账户切勿通过电子邮件发送密钥请勿对组织外部共享密钥即使有来自 Amazon 或 Amazoncom 的询问合法代表 Amazon 的任何人永远都不会要求您提供密钥

7 下载 csv 文件之后选择 Close (关闭)在创建访问密钥时默认情况下密钥对处于活动状态并且您可以立即使用此密钥对

7

Amazon Cognito 开发人员指南创建 IAM 用户访问密钥

相关主题

bull IAM 用户指南中的什么是 IAMbull Amazon一般引用中的Amazon安全凭证

8

Amazon Cognito 开发人员指南使用用户池进行身份验证

Amazon Cognito 常见场景本主题介绍使用 Amazon Cognito 的六个常见场景

Amazon Cognito 的两个主要组件是用户池和身份池用户池是为 Web 和移动应用程序用户提供注册和登录选项的用户目录身份池提供Amazon凭证以向用户授予对其他Amazon服务

用户池是 Amazon Cognito 中的用户目录您的应用程序用户可以通过用户池直接登录也可以通过第三方身份提供商 (IdP) 联合登录用户池管理处理以下令牌的开销从通过 FacebookGoogleAmazon 和苹果进行的社交登录返回的令牌以及从 OpenID Connect (OIDC) 和 SAML IdC IdC 返回的令牌无论您的用户是直接登录还是通过第三方登录用户池的所有成员都有一个可通过开发工具包访问的目录配置文件

使用身份池您的用户可以获取临时Amazon用于访问的凭证Amazon服务例如 Amazon S3 和DynamoDB身份池支持匿名来宾用户以及通过第三方 IdP 的联合身份验证

主题bull 使用用户池进行身份验证 (p 9)bull 使用用户池访问您的服务器端资源 (p 9)bull 使用 API Gateway 和 Lambda 访问资源 (p 10)bull 访问Amazon包含用户池和身份池的服务 (p 11)bull 与第三方进行身份验证和访问Amazon包含身份池的服务 (p 11)bull 访问Amazon AppSyncAmazon Cognito 资源 (p 12)

使用用户池进行身份验证您可以允许您的用户使用用户池进行身份验证您的应用程序用户可以通过用户池直接登录也可以通过第三方身份提供商 (IdP) 联合登录用户池管理处理以下令牌的开销从通过 FacebookGoogleAmazon 和苹果进行的社交登录返回的令牌以及从 OpenID Connect (OIDC) 和 SAML IdC IdC 返回的令牌

成功进行身份验证后您的 Web 或移动应用程序将收到来自 Amazon Cognito 的用户池令牌您可以使用这些令牌检索Amazon凭证允许您的应用程序访问其他Amazon服务也可以选择使用它们来控制对您的服务器端资源或 Amazon API Gateway 的访问

有关更多信息请参阅 User池身份验证流程 (p 285) 和将令牌与用户池结合使用 (p 139)

使用用户池访问您的服务器端资源成功进行用户池登录后您的 Web 或移动应用程序将收到来自 Amazon Cognito 的用户池令牌您可以使用这些令牌控制对您的服务器端资源的访问您也可以创建用户池组来管理权限以及表示不同类型的用户有关使用组控制资源访问权限的更多信息请参阅向用户池添加组 (p 118)

9

Amazon Cognito 开发人员指南使用 API Gateway 和 Lambda 访问资源

在为用户池配置域后Amazon Cognito 服务会预置一个托管 Web UI您可使用此 UI 向应用程序添加注册页和登录页使用此 OAuth 20 基础您可以创建自己的资源服务器以使您的用户能够访问受保护的资源有关更多信息请参阅为您的用户池定义资源服务器 (p 41)

有关用户池身份验证的更多信息请参阅User池身份验证流程 (p 285)和将令牌与用户池结合使用 (p 139)

使用 API Gateway 和 Lambda 访问资源您可以允许用户通过 API Gateway 访问您的 APIAPI Gateway 会验证来自成功的用户池身份验证的令牌并使用它们向您的用户授予对资源（包括 Lambda 函数）或您自己的 API 的访问权限

您可以使用用户池中的组控制使用 API Gateway 的权限方法是将组成员资格映射到 IAM 角色用户所属的组包含在您的应用程序用户登录时用户池提供的 ID 令牌中有关用户池组的更多信息请参阅向用户池添加组 (p 118)

您可以将您的用户池令牌随请求一起提交到 API Gateway以便 Amazon Cognito 授权方 Lambda 函数进行验证有关 API Gateway 的更多信息请参阅结合使用 API Gateway 与 Amazon Cognito 用户池

10

Amazon Cognito 开发人员指南访问Amazon包含用户池和身份池的服务

访问Amazon包含用户池和身份池的服务成功进行用户池身份验证后您的应用程序将收到来自 Amazon Cognito 的用户池令牌您可以用它们交换用于临时访问其他Amazon服务与身份池有关更多信息请参阅在登录后使用身份池访问 Amazon 服务 (p 149) 和 Amazon Cognito 身份池入门 (联合身份) (p 174)

与第三方进行身份验证和访问Amazon包含身份池的服务

您可以允许用户访问Amazon服务身份池需要来自由第三方身份提供商进行身份验证的用户的 IdP 令牌(如果是匿名来宾则不需要令牌)作为交换身份池授予临时Amazon凭证您可用于访问其他Amazon服务有关更多信息请参阅 Amazon Cognito 身份池入门 (联合身份) (p 174)

11

Amazon Cognito 开发人员指南访问Amazon AppSyncAmazon Cognito 资源

访问Amazon AppSyncAmazon Cognito 资源您可以授予用户访问Amazon AppSync资源其中包含来自成功的 Amazon Cognito 身份验证（来自用户池或身份池）的令牌有关更多信息请参阅访问Amazon AppSync和包含用户池或联合身份的数据源

12

Amazon Cognito 开发人员指南创建用户池

Amazon Cognito 教程Amazon Cognito 的两个主要组件是用户池和身份池用户池是为您的 Web 和移动应用程序提供注册和登录选项的用户目录身份池提供Amazon凭证来授予用户访问其他Amazon服务

主题bull 教程创建用户池 (p 13)bull 教程创建身份池 (p 13)bull 教程清理您的Amazon资源 (p 14)

教程创建用户池借助用户池您的用户可以通过 Amazon Cognito 登录您的 Web 或移动应用程序

创建用户池

1 转到Amazon Cognito 控制台系统可能会提示您输入Amazon凭证2 选择 Manage User Pools (管理用户池)3 选择 Create a user pool4 为您的用户池指定一个名称然后选择查看默认值以保存该名称5 在审查页面上选择创建池

相关资源有关用户池的更多信息请参阅Amazon Cognito user pools (p 18)

另请参阅 User池身份验证流程 (p 285) 和将令牌与用户池结合使用 (p 139)

教程创建身份池借助身份池您的用户可以获取临时Amazon用于访问的凭证Amazon服务例如 Amazon S3 和DynamoDB

创建身份池

1 转到Amazon Cognito 控制台系统可能会提示您输入Amazon凭证2 选择管理身份池3 选择 Create new identity pool (创建新身份池)4 为身份池输入一个名称5 要启用未经身份验证的身份请从 Unauthenticated identities 可折叠部分中选择 Enable access to

unauthenticated identities6 选择 Create Pool7 系统将提示您访问您的Amazon资源的费用

选择Allow创建两个与您的身份池关联的默认角色一个用于未经身份验证的用户另一个用于经过身份验证的用户这些默认角色会向您的身份池提供 Amazon Cognito Sync 访问权限您可以在 IAM 控制台中修改与身份池关联的角色

13

Amazon Cognito 开发人员指南相关资源

8 记下您的身份池 ID 号您将使用它来设置允许您的应用程序用户访问其他的策略Amazon服务 (如Amazon Simple Storage Service 或 DynamoDB)

相关资源有关身份池的更多信息请参阅Amazon Cognito 身份池 (联合身份) (p 174)

有关使用身份池的 S3 示例请参阅通过浏览器将照片上传到 Amazon S3

教程清理您的Amazon资源删除身份池

1 转到Amazon Cognito 控制台系统可能会提示您输入Amazon凭证2 选择 Manage Identity Pools (管理身份池)3 选择要删除的身份池的名称此时将显示身份池的控制面板页4 在控制面板页的右上角选择编辑身份池此时将显示编辑身份池页5 向下滚动并选择删除身份池以将其展开6 选择删除身份池7 选择删除池

删除用户池

1 转到Amazon Cognito 控制台系统可能会提示您输入Amazon凭证2 Manage User Pools (管理用户池)3 选择在上一步中创建的用户池4 在域名页面的应用程序集成下选择删除域5 提示确认时选择删除域6 转到常规设置页面7 选择页面右上角的删除池8 提示确认时输入删除并选择删除池

14

Amazon Cognito 开发人员指南Amazon Cognito 身份验证Amazon AmplifyFramework

将与 Web 和移动应用程序集成当新用户发现您的程序时或当现有用户返回使用您的应用程序时他们的第一个任务是注册或登录通过将 Amazon Cognito 与您的客户端代码集成您可以将应用程序连接到后端Amazon功能可帮助身份验证和授权工作流例如您的应用程序将使用 Amazon Cognito API 在用户池中创建新用户检索用户池令牌以及从身份池中获取临时凭证要将 Amazon Cognito 与您的 Web 或移动应用程序集成请使用AmazonAmplifyFramework

Amazon Cognito 身份验证AmazonAmplifyFramework

Amazon Amplify 向 Web 和移动开发人员提供服务和库借助 Amazon Amplify您可以构建与由 Amazon服务组成的后端环境集成的应用程序要预配置后端环境以及将 Amazon 服务与客户端代码集成请使用 Amazon Amplify 框架该框架提供了一个交互式命令行界面 (CLI)可帮助您为按类别组织的功能（包括分析存储和身份验证以及其他功能）配置 Amazon 资源该框架还为 Web 和移动平台（包括iOSAndroid 及 JavaScript）提供了高级开发工具包和库支持的 JavaScript 框架包括 ReactReactNativeAngularIonic 和 Vue每个开发工具包和库都包含身份验证操作您可以使用这些操作来实施Amazon Cognito 驱动的身份验证工作流

使用Amazon Amplify框架向应用程序添加身份验证功能请参阅Amazon Amplify您使用的平台的授权文档

bull Amazon Amplify 适用于 JavaScript 的身份验证bull Amazon Amplify 适用于 iOS 的身份验证bull Amazon Amplify 适用于 Android 的身份验证

15

Amazon Cognito 开发人员指南基于用户池的多租户

多租户应用程序最佳实践Amazon Cognito 用户池可用于保护小型多租户应用程序其中租户数量和预期容量与相关 Amazon Cognito服务配额一致多租户设计的一个常见用例是运行工作负载以支持测试应用程序的多个版本多租户设计对于测试具有不同数据集的单个应用程序也很有用这样可以充分利用您的集群资源

Note

Amazon Cognito配额应用于每个Amazon账户和区域这些配额在应用程序中的所有租户之间共享查看 Amazon Cognito 服务配额并确保配额符合您的应用程序中的预期容量和预期租户数量

您有四种方法来保护多租户应用程序用户池应用程序客户端组或自定义属性

主题bull 基于用户池的多租户 (p 16)bull 基于应用程序客户端的多租户 (p 16)bull 基于集团的多租户 (p 17)bull 基于属性的自定义多租户 (p 17)bull 多租户安全建议 (p 17)

基于用户池的多租户使用此设计您可以为应用程序中的每个租户创建一个用户池此方法为每个租户提供最大隔离并允许您为每个租户实施不同的配置通过用户池隔离租户允许您灵活地进行用户到租户映射它还允许同一用户使用多个配置文件但是每个用户必须为他们有权访问的每个租户单独注册使用此方法可以单独为每个租户设置托管 UI并将用户重定向到其特定于您的应用程序的租户实例此方法还可以更轻松地与 APIGateway 等后端服务集成我们建议在以下情况下使用此方法

bull 您的应用程序为每个租户具有不同的配置例如每个租户的数据驻留要求密码策略和 MFA 配置可能会有所不同

bull 您的应用程序具有复杂的用户到租户角色映射例如单个用户可以是租户 A 中的 ldquo学生rdquo同一用户也可以是租户 B 中的 ldquo教师rdquo

bull 您的应用程序使用默认 Amazon Cognito 托管 UI 作为本地用户的主要身份验证方法（本机用户是在用户池中使用用户名和密码创建的用户）

bull 您的应用程序具有思洛存储器多租户应用程序其中每个租户都可以获取应用程序基础架构的完整实例以供其使用

工作量级别

使用这种方法的开发和运营努力非常高您需要在使用 Amazon Cognito API 操作和自动化工具的应用程序中构建租户入门和管理组件这些组件是为每个租户创建所需资源所必需的您还需要实现租户匹配的用户界面此外您必须向应用程序添加允许用户注册并登录其相应租户的用户池的逻辑

基于应用程序客户端的多租户通过基于应用程序客户端的多租户您可以将同一用户映射到多个租户而无需重新创建用户的配置文件您可以为每个租户创建一个应用程序客户端并启用租户外部 IdP 作为此应用程序客户端唯一允许的身份提供程序有关更多信息请参阅配置用户池应用程序客户端

16

Amazon Cognito 开发人员指南基于集团的多租户

当您使用托管 UI 对具有本机帐户的用户进行身份验证时基于应用程序客户端的多租户需要额外考虑用户名密码等当托管 UI 正在使用时将创建一个会话 cookie 来维护经过身份验证的用户的会话会话cookie 还在同一用户池中的应用程序客户端之间提供 SSO此方法可以在以下情况下使用

bull 您的应用程序在所有租户中具有相同的配置例如数据驻留和密码策略在所有租户中都是相同的bull 您的应用程序在用户和租户之间具有一对多的映射例如一个用户可以使用同一个配置文件访问多个租

户bull 您有一个仅限联合的多租户应用程序其中租户将始终使用外部 IdP 登录到您的应用程序bull 您拥有 B2B 多租户应用程序租户后端服务将使用客户端凭据授予来访问您的服务在这种情况下您可

以为每个租户创建应用程序客户端并与租户后端服务共享客户端 ID 和密钥以进行计算机到计算机身份验证

工作量级别

采用这种方法的开发努力很大您需要实现租户匹配逻辑和用户界面以便将用户与其租户的应用程序客户端进行匹配

基于集团的多租户通过基于组的多租户您可以将 Amazon Cognito用户池组与一个租户这样您就可以通过基于角色的访问控制 (RBAC) 使用其他功能有关更多信息请参阅基于角色的访问控制

基于属性的自定义多租户使用基于属性的自定义多租户您可以存储租户标识数据如tenant_id作为自定义属性在用户的配置文件中然后您可以处理应用程序和后端服务中的所有多租户逻辑此方法允许您对所有用户使用统一的注册和登录体验您还可以通过选中此自定义属性来标识应用程序中用户的租户

多租户安全建议以下建议可帮助您提高应用程序的安全性

bull 避免使用未经验证的电子邮件地址根据域匹配授权用户访问租户电子邮件地址和电话号码不应受信任除非它们经过您的应用程序验证或外部 IdP 提供验证证明有关设置这些权限的详细信息请参阅属性权限和范围

bull 确保用于标识租户的用户配置文件属性是可由管理员更改的不可变或可变属性应用程序客户端应对这些属性具有只读访问权限

bull 确保在外部 IdP 和应用程序客户端之间具有 11 映射以防止未经授权的跨租户访问如果用户拥有有效的 Amazon Cognito 会话 cookie并且在多个应用程序客户端上允许其外部 IdP则可能会发生这种情况

bull 在应用程序中实施租户匹配和授权逻辑时请确保用户自己不能修改用于授权用户访问租户的条件您还应确保租户身份提供程序管理员不能修改用户访问权限（如果正在使用外部 IdP 进行联合）

17


Amazon Cognito user pools用户池是 Amazon Cognito 中的用户目录利用用户池您的用户可以通过 Amazon Cognito 登录您的 Web或移动应用程序您的用户还可以通过社交身份提供商（例如 GoogleFacebookAmazon 或 Apple）以及 SAML 身份提供商登录无论您的用户是直接登录还是通过第三方登录用户池的所有成员都有一个可通过软件开发工具包 (SDK) 访问的目录配置文件

用户池提供

bull 注册和登录服务bull 用于登录用户的内置的可自定义的 Web UIbull 使用 FacebookGoogleLogin with Amazon 和 Sign in with Apple 的社交登录以及使用您的用户池中

的 SAML 身份提供商的登录bull 用户目录管理和用户配置文件bull 多重身份验证（MFA)遭盗用凭证检查账户盗用保护以及电话和电子邮件验证等安全功能bull 通过 Amazon Lambda 触发器进行的自定义工作流程和用户迁移

在成功验证用户身份后Amazon Cognito 将颁发 JSON Web Token (JWT)可供您用来保护和授权对您自己的 API 的访问或交换Amazon凭证

Amazon Cognito 通过适用于 JavaScriptAndroid 和 iOS 的 Amazon Cognito 用户池身份池身份池提供令牌处理请参阅用户池入门 (p 19)和将令牌与用户池结合使用 (p 139)

Amazon Cognito 的两个主要组件是用户池和身份池身份池提供Amazon凭证以向用户授予对其他Amazon服务使用户池中的用户能够访问Amazon资源您可以配置一个身份池以用用户池令牌交换Amazon凭证有关更多信息请参阅在登录后使用身份池访问 Amazon 服务 (p 149)和Amazon Cognito 身份池入门 (联合身份) (p 174)

主题bull 用户池入门 (p 19)bull 使用 Amazon Cognito 托管 UI 进行注册和登录 (p 28)bull 通过第三方添加用户池登录 (p 43)bull 使用 Lambda 触发器自定义用户池工作流 (p 63)bull 将 Amazon Pinpoint 分析与 Amazon Cognito 用户池结合使用 (p 107)bull 在用户池中管理用户 (p 109)bull Amazon Cognito 用户池的电子邮件设置 (p 134)bull Amazon Cognito 用户池的 SMS 消息设置 (p 137)bull 将令牌与用户池结合使用 (p 139)bull 在成功进行用户池身份验证后访问资源 (p 147)bull 用户池参考 (Amazon Web Services Management Console) (p 152)

18

Amazon Cognito 开发人员指南用户池入门

bull 管理错误响应 (p 172)

用户池入门以下步骤介绍如何使用Amazon Cognito 控制台有关从何处开始使用 Amazon Cognito 的指南请参阅Amazon Cognito 入门 (p 5)

主题bull 先决条件注册 Amazon 账户 (p 19)bull 步骤 1 创建用户池 (p 19)bull 步骤 2 添加应用程序以启用托管 Web UI (p 20)bull 步驟 3 向用户池添加社交登录 (可选) (p 21)bull 步骤 4 将使用 SAML 身份提供商的登录添加到用户池 (可选) (p 26)bull 后续步骤 (p 27)

先决条件注册 Amazon 账户要使用 Amazon Cognito您需要Amazonaccount 如果您还没有账户请按照以下步骤注册

注册Amazon账户



下一步步骤 1 创建用户池 (p 19)

步骤 1 创建用户池通过使用 Amazon Cognito 用户池您可以创建和维护用户目录并将注册信息和登录信息添加到移动应用程序或 Web 应用程序

创建用户池

1 转至Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 选择 Manage User Pools (管理用户池)3 在页面右上角选择选择选择创建用户池4 为用户池指定一个名称然后选择查看默认值保存名称5 在页面左上角选择 Attributes (属性)然后依次选择 Email address or phone number (电子邮件地址或

电话号码) 和 Allow email addresses (允许使用电子邮件地址)最后选择 Next step (下一步) 加以保存

Note

我们建议您启用不区分大小写的username属性然后创建用户池例如如果选择此选项用户将能够使用 ldquo用户名rdquo 或 ldquoUsernamerdquo 登录启用此选项还可启用preferred_username和email别名不区分大小写除了username属性有关更多信息请参阅 CreateUserPool中的Amazon Cognito 用户池 API 参考

19

Amazon Cognito 开发人员指南步骤 2 添加应用程序以启用托管 Web UI

6 在左侧导航菜单中选择选择选择审核7 查看用户池信息并进行必要的更改如果信息正确请选择选择创建池

下一步步骤 2 添加应用程序以启用托管 Web UI (p 20)

步骤 2 添加应用程序以启用托管 Web UI在创建用户池后您可以创建一个应用程序以便使用内置网页来对用户进行注册和登录

在用户池中创建应用程序

1 转至Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 选择 Manage User Pools (管理用户池)3 从列表中选择现有用户池或创建用户池4 在页面左侧的导航栏上选择常规设置下的应用程序客户端5 选择 Add an app client6 为应用程序指定名称7 清除选项生成客户端密钥因为使用客户端 JavaScript 在 URL 中发送它是不安全的客户端密钥由具

有以下特点的应用程序使用拥有可保护客户端密钥的服务器端组件8 选择 Create app client9 记下应用程序客户端 ID10 选择返回池详细信息11 从控制台页面左侧的导航栏中选择应用程序客户端设置12 选择 Cognito 用户池作为其中一个启用身份提供商

Note

要使用外部身份提供商 (IIdPs)（如 FacebookAmazonGoogle 和 Apple）以及通过 OpenIDConnect (OIDC) 或 SAML IdP 进行登录请首先按下文所述的方式配置它们然后返回到应用程序客户端设置页面以启用它们

13 输入 Amazon Cognito 授权服务器在用户通过身份验证之后进行调用的回调 URL对于 Web 应用程序该 URL 应以 https 开头如 httpswwwexamplecom

对于 iOS 或 Android 应用程序您可以使用类似 myapp 的回调 URL14 输入注销 URL15 Select授权代码返回随后与用户池令牌交换的授权代码由于令牌绝不会直接向最终用户公开因此它

们不太可能被泄露但是后端需要自定义应用程序以将授权代码换成用户池令牌出于安全原因我们建议您将授权代码授予流程与用于代码交换 (PKCE) 的证明密钥适用于移动应用程序

16 UNDER允许的 OAuth 流程选择隐式授予使用 Amazon Cognito 将用户池 JSON Web Token (JWT)返回给您当没有可用于将授权代码换成令牌的后端时您可以使用此流程它对于调试令牌也很有帮助

Note

您可以同时启用授权代码授予和隐式代码授予然后按需使用每个授予17 除非您希望明确地排除一个允许的 OAuth 范围否则请选中所有ldquo允许的 OAuth 范围rdquo的复选框

Note

只有在您的应用程序需要代表自己而不是代表用户请求访问令牌时才选择 Client credentials18 选择保存更改

20

Amazon Cognito 开发人员指南步驟 3 向用户池添加社交登录 (可选)

19 在域名页面上键入可用的域前缀20 记下完整的域地址21 选择保存更改

查看您的登录页面

您可以使用以下 URL 查看托管 UI 登录网页记下 response_type在本例中为响应类型 = 代码获取授权代码授予

httpsyour_domainloginresponse_type=codeampclient_id=your_app_client_idampredirect_uri=your_callback_url

您可以使用针对隐式代码授予的以下 URL 查看托管 UI 登录网页其中response_type=token成功登录后Amazon Cognito 会将用户池令牌返回到您的 Web 浏览器的地址栏

httpsyour_domainloginresponse_type=tokenampclient_id=your_app_client_idampredirect_uri=your_callback_url

您可以在响应中的 idtoken= 参数后面找到 JSON Web Token (JWT) 身份令牌

下面是来自隐式授予请求的示例响应您的身份令牌字符串长得多

httpswwwexamplecomid_token=123456789tokens123456789ampexpires_in=3600amptoken_type=Bearer

您可以使用Amazon Lambda请参阅解码并验证 Amazon Cognito JWT 令牌上AmazonGitHub 网站

Amazon Cognito 用户池令牌是使用 RS256 算法对其进行签名的

您可能需要先等待一分钟以刷新浏览器之后才会显示您在控制台中所做的更改

您的域将显示在域名页面上您的应用程序客户端 ID 和回调 URL 显示在常规设置页

下一步步驟 3 向用户池添加社交登录 (可选) (p 21)

步驟 3 向用户池添加社交登录 (可选)您可以允许应用程序用户通过社交身份提供商 (IdP)（如 FacebookGoogleAmazon 和 Apple）进行登录无论您的用户是直接登录还是通过第三方登录所有用户都在用户池中有一个配置文件如果您不想添加通过社交登录身份提供商进行的登录请跳过此步骤

第 1 步向社交 IdP 注册在使用 Amazon Cognito 创建社交 IdP 之前必须向社交 IdP 注册应用程序才能接收客户端 ID 和客户端密钥

向 Facebook 注册应用程序

1 创建 Facebook 开发人员账户

21


2 使用 Facebook 凭证登录3 在 My Apps (我的应用程序) 菜单上选择 Create New App (创建新的应用程序)4 为 Facebook 应用程序提供一个名称然后选择 Create App ID (创建应用程序 ID)5 在左侧导航栏上选择 Settings (设置)然后选择 Basic (基本)6 记下 App ID (应用程序 ID) 和 App Secret (应用程序密钥)您将在下一节中使用它们7 从页面底部选择 + Add Platform (+ 添加平台)8 选择网站9 在 Website (网站) 下将具有 oauth2idpresponse 终端节点的用户池域键入到 Site URL (站点 URL)

中

httpsltyour-user-pool-domaingtoauth2idpresponse

10 选择保存更改11 在 App Domains (应用程序域) 中键入用户池域

httpsltyour-user-pool-domaingt

12 选择保存更改13 从导航栏中选择 Products (产品)然后选择 Facebook Login (Facebook 登录) 中的 Set up (设置)14 从导航栏中选择 Facebook Login (Facebook 登录)然后选择 Settings (设置)

在 Valid OAuth Redirect URIs (有效的 OAuth 重定向 URI) 中键入重定向 URL它将包含具有 oauth2idpresponse 终端节点的用户池域


15 选择保存更改

向 Amazon 注册应用程序

1 创建 Amazon 开发人员账户2 使用 Amazon 凭证登录3 您需要创建一个 Amazon 安全配置文件才能接收 Amazon 客户端 ID 和客户端密钥

从页面顶部的导航栏中选择 Apps and Services (应用程序和服务)然后选择 Login with Amazon (以Amazon 登录)

4 选择 Create a Security Profile (创建安全配置文件)5 键入 Security Profile Name (安全配置文件名称)Security Profile Description (安全配置文件描述) 和

Consent Privacy Notice URL (同意隐私声明 URL)6 选择 Save7 选择 Client ID (客户端 ID) 和 Client Secret (客户端密钥) 以显示客户端 ID 和密钥您将在下一节中使用

它们8 将鼠标悬停在齿轮上并选择 Web Settings (Web 设置)然后选择 Edit (编辑)9 在 Allowed Origins (允许的源) 中键入用户池域


10 在 Allowed Return URLs (允许的返回 URL) 中键入具有 oauth2idpresponse 终端节点的用户池域

22



11 选择 Save

向 Google 注册应用程序

1 创建 Google 开发人员账户2 使用 Google 凭证登录3 选择 CONFIGURE A PROJECT (配置项目)4 键入项目名称然后选择 NEXT (下一步)5 键入产品名称并选择 NEXT (下一步)6 选择Web 浏览器来自的你从何处调用下拉列表中)7 在 Authorized JavaScript origins (授权的 JavaScript 源) 中键入用户池域


8 选择创建此步骤中将不使用 Client ID (客户端 ID) 和 Client Secret (客户端密钥)9 选择完成10 登录 Google 控制台11 在左侧导航栏上选择 Credentials (凭证)12 通过从 Create credentials (创建凭证) 下拉列表中选择 OAuth client ID (OAuth 客户端 ID) 来创建 OAuth

20 凭证13 选择 Web application (Web 应用程序)14 在 Authorized JavaScript origins (授权的 JavaScript 源) 中键入用户池域


15 在 Authorized Redirect URIs (授权的重定向 URI) 中键入具有 oauth2idpresponse 终端节点的用户池域


16 选择 Create (创建) 两次17 记下 OAuth client ID (OAuth 客户端 ID) 和 client secret (客户端密钥)您需要在下一节中使用它们18 选择 OK

向 Apple 注册应用程序

1 创建 Apple 开发人员账户2 使用 Apple 凭证登录3 在左侧导航栏上选择选择证书ID 和配置文件4 在左侧导航栏上选择选择标识符5 在存储库的标识符页面上选择+图标6 在存储库的注册新标识符页面上选择应用程序 ID然后选择Continue7 在 Register an App ID (注册应用程序 ID) 页面上执行以下操作

23


1 在 Description (描述) 下方键入描述2 UNDER应用程序 ID 前缀键入标识符记下值应用程序 ID 前缀因为在您选择 Apple 作为第 2

步将社交 IdP 添加到用户池 (p 47)3 UNDERCapabilities中选择使用 Apple 登录然后选择编辑4 在存储库的使用 Apple 登录应用程序 ID 配置页面上为您的应用程序选择适当的设置然后选

择Save5 选择 Continue (继续)

8 在 Confirm your App ID (确认您的应用程序 ID) 页面上选择 Register (注册)9 在存储库的标识符页面上将鼠标悬停在应用程序 ID在页面右侧选择选择服务 ID然后选择+图标10 在存储库的注册新标识符页面上选择服务 ID然后选择Continue11 在 Register an Services ID (注册服务 ID) 页面上执行以下操作

1 在 Description (描述) 下方键入描述2 在 Identifier (标识符) 下方键入标识符记下此服务 ID因为在您选择 Apple 作为身份提供商之

后您需要此值第 2 步将社交 IdP 添加到用户池 (p 47)3 Select使用 Apple 登录然后选择配置4 在 Web Authentication Configuration (Web 身份验证配置) 页面上选择 Primary App ID (主应用程

序 ID)UNDER網域下键入您的用户池域UNDER返回 URL下键入您的用户池域并包含 oauth2idpresponse 终端节点例如


5 选择Add然后Save您不需要验证域6 选择Continue然后选择注册

12 在左侧导航栏上选择选择密钥13 在 Keys (密钥) 页面上选择 + 图标14 在 Register a New Key (注册新密钥) 页面上执行以下操作

1 在 Key Name (密钥名称) 下方键入密钥名称2 选择使用 Apple 登录然后选择配置3 在存储库的配置密钥页面上选择主应用程序 ID然后选择Save4 选择Continue然后选择注册

15 在存储库的下载您的密钥页面上选择下载下载私有密钥然后选择Done您将需要这个私钥和键ID值然后选择 Apple 作为您的身份提供商第 2 步将社交 IdP 添加到用户池 (p 47)

第 2 步将社交 IdP 添加到用户池在本节中您使用上一节中的客户端 ID 和客户端密钥在用户池中配置社交 IdP

使用 Amazon Web Services Management Console配置用户池社交身份提供商

1 转至Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 选择 Manage your User Pools3 从列表中选择现有用户池或创建用户池4 在左侧导航栏上选择身份提供商5 选择社交身份提供商FacebookGoogleLogin with Amazon或者Apple6 对于 Google 和 Login with Amazon键入在上一节中从社交身份提供商处收到的应用程序客户端 ID 和

应用程序客户端密钥对于 Facebook键入在上一节中从社交身份提供商处收到的应用程序客户端 ID和应用程序客户端密钥并选择 API 版本我们建议选择尽可能高的可用版本因为每个 Facebook

24


API 版本都有一个生命周期和一个弃用日期例如版本 212如果遇到任何问题您可以在创建后更改API 版本Facebook 作用域和属性可能因每个 API 版本而异因此我们建议您测试集成rdquo 对于ldquo使用Apple 登录rdquo请提供在上一节中收到的服务 ID团队 ID密钥 ID 和私有密钥

7 键入要授权的范围的名称范围定义了您要通过应用程序访问的用户属性 (如 name 和 email)对于Facebook这些属性应用逗号分隔对于 Google 和 Login with Amazon则应采用空格分隔对于ldquo使用 Apple 登录rdquo选中要访问的范围的复选框

社交身份提供商示例范围

Facebook public_profile email

Google profile email openid

Login with Amazon profile postal_code

使用 Apple 登录 email name

您的应用程序用户需要同意向您的应用程序提供这些属性关于范围的更多信息请参阅GoogleFacebook 和 Login with Amazon 或ldquo使用 Apple 登录rdquo的文档

对于ldquo使用 Apple 登录rdquo下面提供了可能不会返回范围的用户场景

bull 最终用户离开 Apple 登录页面后出现故障（可能来自 Cognito 内部的故障或开发人员编写的任何内容）

bull 跨用户池和或其他身份验证服务使用服务 ID 标识符bull 在最终用户登录之前开发人员添加了其他范围（未检索到新信息）bull 开发人员删除用户然后用户再次登录而没有从其 Apple ID 个人资料中删除该应用程序

8 为您要配置的社交身份提供商选择 Enable (启用)9 从导航栏中选择 App client settings (应用程序客户端设置)10 选择社交身份提供商作为用户池应用程序的启用身份提供商之一11 在用户池应用程序的回调 URL 中键入回调 URL这是页面的 URL在页面中您的用户在身份验证成

功后将被重定向

httpswwwexamplecom

12 选择保存更改13 在 Attribute mapping 选项卡上至少为必需属性添加映射通常是 email如下所示

a 选中此复选框以选择 FacebookGoogle 或 Amazon 属性名称您还可以键入未在 AmazonCognito 控制台中列出的其他属性的名称

b 从下拉列表中选择目标用户池属性c 选择保存更改d 选择转到摘要页面

第 3 步测试社交 IdP 配置可以通过使用前两节中的元素来创建登录 URL使用此 URL 测试社交 IdP 配置

httpsltyour_user_pool_domaingtloginresponse_type=codeampclient_id=ltyour_client_idgtampredirect_uri=httpswwwexamplecom

25

Amazon Cognito 开发人员指南步骤 4 将使用 SAML 身份提供商的登录添加到用户池 (可选)

您可以在用户池域名控制台页上找到您的域client_id 位于应用程序客户端设置页上对于 redirect_uri 参数使用您的回调 URL这是页面的 URL在页面中您的用户在身份验证成功后将被重定向

Note

5 分钟内未完成的请求将被取消并重定向至登录页面然后会显示 Something went wrong 错误消息

下一步步骤 4 将使用 SAML 身份提供商的登录添加到用户池 (可选) (p 26)

步骤 4 将使用 SAML 身份提供商的登录添加到用户池(可选)您可以允许您的应用程序用户通过 SAML 身份提供商 (IdP) 进行登录无论您的用户是直接登录还是通过第三方登录所有用户都在用户池中有一个配置文件如果您不想添加通过 SAML 身份提供商进行的登录请跳过此步骤

您需要更新您的 SAML 身份提供商并配置您的用户池请参阅 SAML 身份提供商的文档了解有关如何将您的用户池添加为 SAML 20 身份提供商的依赖方或应用程序的信息

请参阅 SAML 身份提供商的文档了解有关如何将您的用户池添加为 SAML 20 身份提供商的依赖方或应用程序的信息在 SAML 身份提供商中为 SAML 20 POST 绑定配置此终端节点

httpsltyourDomainPrefixgtauthltregiongtamazoncognitocomsaml2idpresponse

您可以在域名选项卡Amazon Cognito 控制台

对于一些 SAML 身份提供商您还需要采用以下形式提供 SP urn 受众 URISP 实体 ID

urnamazoncognitospltyourUserPoolIDgt

您可以在常规设置选项卡位于Amazon Cognito 控制台

您还应配置 SAML 身份提供商以便为您的用户池中需要的任何属性提供属性值通常情况下email 是用户池的必需属性在这种情况下SAML 身份提供商应在 SAML 断言中提供一个 email 值 (声明)

Amazon Cognito 用户池支持 SAML 20 与绑定后终端节点联合这使您的应用程序不必检索或分析 SAML断言响应因为用户池直接通过用户代理从身份提供商接收 SAML 响应

在您的用户池中配置 SAML 20 身份提供商

1 转至Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 Manage User Pools (管理用户池)3 从列表中选择现有用户池或创建用户池4 在左侧导航栏上选择身份提供商5 选择 SAML 以打开 SAML 对话框6 在元数据文档下通过 SAML IdP 上传元数据文档还可以输入指向该元数据文档的 URL有关更多信

息请参阅将第三方 SAML 身份提供商与 Amazon Cognito 用户池集成 (p 54)

26

Amazon Cognito 开发人员指南后续步骤

Note

建议您提供终端节点 URL (如果它是一个公有终端节点)而不是上传文件因为这将允许Amazon Cognito 自动刷新元数据通常元数据刷新操作每 6 小时执行一次或在元数据过期前执行 (以时间较早者为准)

7 输入 SAML 提供商名称有关 SAML 命名的更多信息请参阅选择 SAML 身份提供商名称 (p 50)8 输入要使用的任何可选 SAML 标识符9 Select启用 IdP 注销流如果希望用户在从 Amazon Cognito 注销的同时从 SAML IdP 注销请执行此操

作

如果启用此流程在启用时将会向 SAML IdP 发送已签名的注销请求注销终端节点被调用

配置此终端节点以处理来自 IdP 的注销响应此终端节点使用 POST 绑定

httpsltyourDomainPrefixgtauthltregiongtamazoncognitocomsaml2logout

Note

如果选择此选项并且您的 SAML 身份提供商需要已签名的注销请求则您还需要对您的SAML IdP 配置 Amazon Cognito 提供的签名证书SAML IdP 将处理已签名的注销请求并从 Amazon Cognito 会话中注销您的用户

10 选择创建提供商11 在 Attribute mapping 选项卡上至少为必需属性添加映射通常是 email如下所示

a 按照您的身份提供商提供的 SAML 断言中的显示键入 SAML 属性名称如果身份提供商提供了示例 SAML 断言这可能有助于您查找名称一些身份提供商使用简单名称 (如 email)另一些则使用类似于下面的名称

httpschemasxmlsoaporgws200505identityclaimsemailaddress

b 从下拉列表中选择目标用户池属性12 选择保存更改13 选择转到摘要页面

有关更多信息请参阅向用户池添加 SAML 身份提供商 (p 49)

后续步骤现在您已创建用户池下面有一些后续操作

深入了解以下用户池功能

bull 自定义内置登录网页和注册网页 (p 38)bull 向用户池添加多重验证 (MFA) (p 300)bull 向用户池添加高级安全 (p 303)bull 使用 Lambda 触发器自定义用户池工作流 (p 63)bull 将 Amazon Pinpoint 分析与 Amazon Cognito 用户池结合使用 (p 107)

有关 Amazon Cognito 身份验证和授权案例的概述请参阅Amazon Cognito 常见场景 (p 9)

要访问其他Amazon服务请参阅成功的用户池身份验证后参阅在登录后使用身份池访问 Amazon 服务 (p 149)

27

Amazon Cognito 开发人员指南使用托管 UI

除了 Amazon Web Services Management Console和本节前面部分提到的用户池开发工具包之外您还可以使用 Amazon Command Line Interface 与您的用户池配置文件进行交互

使用 Amazon Cognito 托管 UI 进行注册和登录Amazon Cognito 管用户界面为您提供符合 OAuth 20 标准的授权服务器它提供了最终用户流的默认实现如注册身份验证等您可以通过简单地更改用户池配置来自定义用户流例如添加多重身份验证(MFA)您的应用程序将重定向到托管 UI它将处理用户流通过提供特定品牌的徽标和改变外观可以定制用户体验Amazon Cognito 托管用户界面还允许您轻松添加最终用户登录的功能使其能够通过社交提供商（Facebook亚马逊登录谷歌和苹果）任何 OpenID Connect (OIDC) 兼容和 SAML 提供商登录

主题bull 使用 Amazon Amplify 设置托管 UI (p 28)bull 使用 Amazon Cognito 控制台设置托管 UI (p 28)bull 配置用户池应用程序客户端 (p 30)bull 配置用户池域 (p 33)bull 自定义内置登录网页和注册网页 (p 38)bull 为您的用户池定义资源服务器 (p 41)

使用 Amazon Amplify 设置托管 UI如果您使用 Amazon Amplify 向 Web 或移动应用程序添加身份验证功能则可以使用 Amazon Amplify 框架中的命令行界面 (CLI) 和库来设置托管 UI要向应用程序添加身份验证功能您可以使用 Amazon AmplifyCLI 将身份验证类别添加到项目中然后在客户端代码中您可以使用Amazon Amplify库可使用 AmazonCognito 用户池对用户进行身份验证

您可以显示预构建的托管 UI也可以通过重定向到社交登录提供商（例如 FacebookGoogleAmazon 或Apple）的 OAuth 20 终端节点联合用户身份用户成功通过社交提供商身份验证之后如果需要AmazonAmplify 在您的用户池中创建一个新用户并向您的应用程序提供用户的 OIDC 令牌

有关更多信息请参阅您使用的应用平台的 Amazon Amplify 框架文档


使用 Amazon Cognito 控制台设置托管 UI1 转至Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 选择 Manage User Pools (管理用户池)3 从列表中选择现有用户池或创建用户池4 在页面左侧的导航栏上选择常规设置下的应用程序客户端5 选择 Add an app client6 输入您的应用程序的名称7 除非您的授权流程有要求否则应清除选项生成客户端密钥客户端密钥由具有以下特点的应用程序使

用拥有可保护客户端密钥的服务器端组件8 （可选）更改令牌到期设置9 Select身份验证流配置选项10 选择安全配置我们建议您选择Enabled (已启用)

28

Amazon Cognito 开发人员指南使用 Amazon Cognito 控制台设置托管 UI

11 （可选）选择设置属性读取和写入权限12 选择 Create app client13 记下应用程序客户端 ID14 选择返回池详细信息

配置应用程序

1 从控制台页面左侧的导航栏中选择应用程序客户端设置2 选择 Cognito 用户池作为其中一个启用身份提供商

Note

要使用外部身份提供商 (IdP)（如 FacebookAmazonGoogle 或 Apple）以及通过 OpenIDConnect (OIDC) 或 SAML IdP 进行登录请首先按下文所述的方式配置它们然后返回到应用程序客户端设置页面以启用它们

3 Enter回调 URL回调 URL 指示在用户成功登录之后将被重定向到哪里4 Enter注销 URL注销 URL 指示在您的用户注销后会被重定向到哪里5 Select授予授权代码返回随后与用户池令牌交换的授权代码由于令牌绝不会直接向最终用户公开因

此它们不太可能被泄露但是后端需要自定义应用程序以将授权代码换成用户池令牌出于安全原因强烈建议您将授权代码授予流程与用于代码交换 (PKCE) 的证明密钥适用于移动应用程序

6 Select隐式授予从 Amazon Cognito 将用户池 JSON Web Token (JWT) 返回给您当没有可用于将授权代码换成令牌的后端时您可以使用此流程它对于调试令牌也很有帮助

7 您可以同时启用授权代码授予和隐式代码授予然后按需使用每个授予8 除非您希望明确地排除一个允许的 OAuth 范围否则请选中所有ldquo允许的 OAuth 范围rdquo的复选框9 只有在您的应用程序需要代表自己而不是代表用户请求访问令牌时才选择 Client credentials10 选择保存更改

配置域

1 Select选择域名2 在存储库的域名页面上键入域前缀并检查可用性或输入您自己的域3 记下完整的域地址4 选择保存更改


您可以使用以下 URL 查看托管 UI 登录网页记下 response_type在这种情况下响应类型 = 代码获取授权代码授予

httpsltyour_domaingtloginresponse_type=codeampclient_id=ltyour_app_client_idgtampredirect_uri=ltyour_callback_urlgt


httpsltyour_domaingtloginresponse_type=tokenampclient_id=ltyour_app_client_idgtampredirect_uri=ltyour_callback_urlgt


29

Amazon Cognito 开发人员指南配置应用程序客户端




Amazon Cognito 用户池令牌使用 RS256 算法进行签名


您的域将显示在域名页面上您的应用程序客户端 ID 和回调 URL 将显示在应用程序客户端设置页面上

Note

Amazon Cognito 托管的登录网页不支持自定义身份验证流程

配置用户池应用程序客户端在创建用户池后您可以将应用程序客户端配置为使用内置网页来注册和登录用户有关术语请参阅应用程序客户端设置 (p 32)

配置应用程序客户端 (Amazon Web Services Management Console)

1 转至Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 选择 Manage User Pools (管理用户池)3 从列表中选择现有用户池或创建用户池4 在页面左侧的导航栏上选择常规设置下的应用程序客户端5 选择 Add an app client6 输入您的应用程序的名称7 除非您的授权流程有要求否则应清除选项生成客户端密钥客户端密钥由具有以下特点的应用程序使

用拥有可保护客户端密钥的服务器端组件8 （可选）更改令牌到期设置9 Select身份验证流配置选项10 选择安全配置我们建议您选择Enabled (已启用)11 （可选）选择设置属性读取和写入权限12 选择 Create app client13 记下应用程序客户端 ID14 选择返回池详细信息

配置应用程序客户端（Amazon CLI 和 Amazon API）

您可以使用 Amazon CLI 创建更新描述和删除您的用户池应用程序客户端

在这些示例中用您的用户池和应用程序客户端 ID 值替换了ldquoMyUserPoolIDrdquo和ldquoMyAppClientIDrdquo同样您的参数值可能不同于这些示例中使用的值

Note

回调和注销 URL 采用 JSON 格式以防止 CLI 将它们视为远程参数文件mdashcallbackurls ldquo[rdquo httpsexamplecom ldquo]rdquomdashlogout-urls ldquo[rdquo httpsexamplecom ldquo]rdquo

30


更新用户池应用程序客户端（Amazon CLI 和 Amazon API）

aws cognito-idp update-user-pool-client --user-pool-id MyUserPoolID --client-id MyAppClientID --allowed-o-auth-flows-user-pool-client --allowed-o-auth-flows code implicit --allowed-o-auth-scopes openid --callback-urls [httpsexamplecom] --supported-identity-providers [MySAMLIdP LoginWithAmazon]

如果命令成功则 Amazon CLI 会返回确认

UserPoolClient ClientId MyClientID SupportedIdentityProviders [ LoginWithAmazon MySAMLIdP ] CallbackURLs [ httpsexamplecom ] AllowedOAuthScopes [ openid ] ClientName Example AllowedOAuthFlows [ implicit code ] RefreshTokenValidity 30 CreationDate 152462811029 AllowedOAuthFlowsUserPoolClient true UserPoolId MyUserPoolID LastModifiedDate 1530055177553

请参阅 Amazon CLI 命令参考了解更多信息update-user-pool-client

Amazon APIUpdateUserPoolClient

创建用户池应用程序客户端（Amazon CLI 和 Amazon API）

aws cognito-idp create-user-pool-client --user-pool-id MyUserPoolID --client-name myApp

请参阅 Amazon CLI 命令参考了解更多信息create-user-pool-client

Amazon APICreateUserPoolClient

获取有关用户池应用程序客户端的信息（Amazon CLI 和 Amazon API）

aws cognito-idp describe-user-pool-client --user-pool-id MyUserPoolID --client-id MyClientID

请参阅 Amazon CLI 命令参考了解更多信息describe-user-pool-client

Amazon APIDescribeUserPoolClient

列出一个用户池中所有应用程序客户端的信息（Amazon CLI 和 Amazon API）

aws cognito-idp list-user-pool-clients --user-pool-id MyUserPoolID --max-results 3

31


请参阅 Amazon CLI 命令参考了解更多信息list-user-pool-clients

Amazon APIListUserPoolClients

删除用户池应用程序客户端（Amazon CLI 和 Amazon API）

aws cognito-idp delete-user-pool-client --user-pool-id MyUserPoolID --client-id MyAppClientID

请参阅 Amazon CLI 命令参考了解更多信息delete-user-pool-client

Amazon APIDeleteUserPoolClient

应用程序客户端设置以下术语和定义可帮助您配置应用程序客户端

启用身份提供商

您可以选择身份提供商 (IDP) 来对用户进行身份验证该服务可以由您的用户池或第三方（如Facebook）来执行要使用 IdP先得启用它可以启用多个 IdP但必须至少启用一个有关使用外部 IdP 的更多信息请参阅通过第三方添加用户池登录 (p 43)

回调 URL

回调 URL 指示在用户成功登录之后将被重定向到哪里选择至少一个回调 URL且该 URL 应具有以下特点bull 是绝对 URIbull 已预先向客户端注册bull 不包含片段组件

请参阅 OAuth 20 ndash 重定向终端节点

Amazon Cognito 要求HTTPSOVERHTTP但除外httplocalhost仅用于测试目的

应用程序回调 URL（如 myappexample）也受支持注销 URL

注销 URL 指示在您的用户注销后会被重定向到哪里允许的 OAuth 流程

这些区域有授予授权代码流启动代码授予流该流程提供授权代码作为响应此代码可用来与TOKEN终端节点 (p 331)交换访问令牌由于令牌绝不会直接向最终用户公开因此它们不太可能被泄露但是后端需要自定义应用程序以将授权代码换成用户池令牌

Note

出于安全原因对于移动应用程序强烈建议您仅将授权代码授予流程与 PKCE 一起使用

这些区域有隐式授予流允许客户端直接从获取访问令牌 (根据范围可选择获取 ID 令牌)AUTHORIZATION 终端节点 (p 326)如果您的应用程序无法启动授予授权代码流有关更多信息请参阅 OAuth 20 规范

您可以同时启用授权代码授予和隐式代码授予然后按需使用每个授予

这些区域有客户端凭证流在机器对机器的通信中使用利用该流您可以请求访问令牌来访问自己的资源当您的应用程序代表自己而不是代表用户来请求令牌时使用此流

32

Amazon Cognito 开发人员指南配置域

Note

由于客户端凭证流不是代表用户使用的所以只有自定义范围可以与该流一起使用自定义范围就是您为自己的资源服务器定义的范围请参阅为您的用户池定义资源服务器 (p 41)

允许的 OAuth 范围

选择以下一个或多个 OAuth 范围来指定可以为访问令牌请求的访问权限bull 这些区域有phone范围授予对phone_number和phone_number_verified声明此范围只能通

过 openid 范围来请求bull 这些区域有email范围授予对email和email_verified声明此范围只能通过 openid 范围来请

求bull 这些区域有openid范围返回 ID 令牌中客户端可读取的所有用户属性如果客户端未请求 openid

范围则不返回 ID 令牌bull 这些区域有awscognitosigninuseradmin作用域授予访问Amazon Cognito 用户池 API 操

作需要访问令牌例如UpdateUserAttributes和VerifyUserAttributebull profile 范围授予对客户端可读取的所有用户属性的访问权限此范围只能通过 openid 范围来请

求

允许的自定义范围

自定义范围是您在资源服务器格式为资资-资资资-资资资资资请参阅为您的用户池定义资源服务器 (p 41)

有关 OAuth 范围的更多信息请参阅标准 OIDC 范围列表

配置用户池域设置客户端应用程序之后您可以配置注册和登录网页的地址您可以使用 Amazon Cognito 托管域并选择可用域前缀或者也可以使用您自己的 Web 地址作为自定义域

要添加应用程序客户端和 Amazon Cognito 托管域请使用Amazon Web Services Management Console请参阅添加应用程序以启用托管 Web UI

Note

您不能使用文本awsamazon或者cognito在域前缀中

主题bull 将 Amazon Cognito 域用于托管 UI (p 33)bull 将您自己的域用于托管 UI (p 35)

将 Amazon Cognito 域用于托管 UI设置客户端应用程序之后您可以配置注册和登录网页的地址您可以将托管 Amazon Cognito 域与您自己的域前缀一起使用


主题bull Prerequisites (p 34)bull 第 1 步配置托管用户池域 (p 34)

33


bull 第 2 步验证登录页面 (p 34)

Prerequisites

在开始之前您需要

bull 用户池和应用程序客户端有关更多信息请参阅用户池入门 (p 19)

第 1 步配置托管用户池域

配置托管用户池域（Amazon Web Services Management Console）

您可以使用 Amazon Web Services Management Console配置用户池域

配置 Amazon Cognito 托管域

1 登录 Amazon Cognito 控制台2 在导航窗格中选择管理您的用户池然后选择要编辑的用户池3 选择域名选项卡4 在前缀域名框中键入要使用的域前缀5 选择检查可用性以确认域前缀可用6 选择保存更改

配置托管用户池域（Amazon CLI 和 Amazon API）

使用以下命令可以创建域前缀并将其分配到您的用户池

配置用户池域

bull Amazon CLI aws cognito-idp create-user-pool-domain

示例aws cognito-idp create-user-pool-domain --user-pool-id ltuser_pool_idgt --domain ltdomain_namegt

bull Amazon APICreateUserPoolDomain

获取有关域的信息

bull Amazon CLI aws cognito-idp describe-user-pool-domain

示例aws cognito-idp describe-user-pool-domain --domain ltdomain_namegt

bull Amazon APIDescribeUserPoolDomain

如需删除域

bull Amazon CLI aws cognito-idp delete-user-pool-domain

示例aws cognito-idp delete-user-pool-domain --domain ltdomain_namegt

bull Amazon APIDeleteUserPoolDomain

第 2 步验证登录页面

bull 验证登录页面是否可从您的 Amazon Cognito 托管域访问

34



您的域显示在域名Amazon Cognito您的应用程序客户端 ID 和回调 URL 将显示在应用程序客户端设置页面上

将您自己的域用于托管 UI在设置应用程序客户端后您可以使用 Amazon Cognito 托管 UI 的自定义域配置用户池利用自定义域您可以使用您自己的 Web 地址以允许用户登录您的应用程序

主题bull 将自定义域添加到用户池 (p 35)bull 更改自定义域的 SSL 证书 (p 37)

将自定义域添加到用户池

要将自定义域添加到用户池请在 Amazon Cognito 控制台中指定域名并提供您使用Amazon CertificateManager(ACM) 在添加域后Amazon Cognito 提供了一个要添加到 DNS 配置的别名目标

Prerequisites


bull 用户池和应用程序客户端有关更多信息请参阅用户池入门 (p 19)bull 您拥有的 Web 域它的根目录在 DNS 中具有有效的 A 记录有关更多信息请参阅域名bull 能够为自定义域创建子域我们建议使用 auth 作为子域例如authexamplecom

Note

如果您没有通配符证书则可能需要为自定义域的子域获取新证书bull 由 ACM 管理的安全套接字层 (SSL) 证书

Note

您必须更改Amazon区域到美国东部（弗吉尼亚北部）然后才能请求或导入证书bull 要设置自定义域名或更新其证书您必须有权更新 Amazon CloudFront 分配为此您可以为 Amazon

账户中的 IAM 用户组或角色附加以下 IAM 策略声明

Version 2012-10-17 Statement [ Sid AllowCloudFrontUpdateDistribution Effect Allow Action [ cloudfrontupdateDistribution ] Resource [ ] ]

35


请参阅为 CloudFront 使用基于身份的策略（IAM 策略）

第 1 步输入自定义域名

您可以使用 Amazon Cognito 控制台或 API 将域添加到用户池

将域添加到用户池（Amazon Cognito 控制台）

1 登录 Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 登录到Amazon Web Services Management Console并通过以下方面打开 Amazon Cognito 控制

台httpsconsoleamazonawscncognitohome3 选择 Manage User Pools (管理用户池)4 在 Your User Pools (您的用户池) 页面上选择要将您的域添加到的用户池5 在左侧导航菜单上选择 Domain name (域名)6 在 Your own domain (您自己的域) 下选择 Use your domain (使用您的域)7 对于 Domain name (域名)输入您的自定义域名您的域名只能包含小写字母数字和连字符请勿对

第一个或最后一个字符使用连字符使用句点来分隔子域名8 适用于Amazon托管证书下选择要用于您的域的 SSL 证书您可以选择使用 ACM 管理的证书之一

如果您没有可供选择的证书则可使用 ACM 预置证书有关更多信息请参阅开始使用中的Amazon Certificate Manager用户指南

9 选择保存更改10 记下别名目标而不是 IP 地址或域名别名目标是指向 Amazon CloudFront 分配的别名资源记录集

将域添加到用户池（Amazon Cognito API）

bull 使用 CreateUserPoolDomain 操作

第 2 步添加别名目标和子域

在本步骤中您将通过域名服务器 (DNS) 服务提供商设置一个别名该别名指回到上一个步骤中的别名目标如果您将 Amazon Route 53 用于 DNS 地址解析请选择使用 Route 53 添加别名目标和子域

将别名目标和子域添加到当前 DNS 配置

bull 如果您没有将 Route 53 用于 DNS 地址解析则需要让您的 DNS 服务提供商添加上一个步骤中的别名目标作为用户池自定义域的别名您的 DNS 提供商还需要为您的自定义域设置子域

使用 Route 53 添加别名目标和子域

1 登录到Route 53 控制台系统可能会提示您输入 Amazon 凭证2 如果您在 Route 53 中没有托管区域请设置一个托管区域否则请跳过此步骤

a 选择 Create Hosted Zoneb 从域名列表中选择您的自定义域c 对于注释键入有关该托管区域的可选注释d 选择创建

3 在托管区域页面上选择您的托管区域的名称4 选择 Create Record Set5 对 Alias (别名) 选项选择 Yes (是)

36


6 将在上一个步骤中记下的别名目标名称键入到别名目标7 选择创建

Note

您的新记录需要一定时间才会传播到 Route 53 DNS 服务器目前验证更改是否已传播的唯一方式是使用 Route 53GetChangeAPI 方法更改通常在 60 秒内传播到所有 Route 53 名称服务器

8 使用别名目标在 Route 53 中添加域名

a 在托管区域页面上选择您的托管区域的名称b 选择创建记录集并输入以下值

i 对于名称键入首选域名例如如果您尝试创建的子域是 authexamplecom请键入auth

ii 对于 Type选择 A - IPv4 addressiii 对 Alias (别名) 选项选择 Yes (是)iv 将在上一个步骤中记下的别名目标名称键入到别名目标

c 选择创建

Note

或者您也可以创建一个新的托管区域来保存与您的子域关联的记录您还可以在父托管区域中创建委托集来将客户端送交给子域托管区域当您管理托管区域时此方法提供了更大的灵活性（例如限制可以编辑该区域的人员）您只能将此方法用于公有托管区域因为目前不支持将 NS 记录添加到私有托管区域有关更多信息请参阅为通过Amazon Route 53 托管的域创建子域


bull 验证登录页面是否可从您的自定义域访问

通过在浏览器中输入此地址使用您的自定义域和子域进行登录这是包含子域 auth 的自定义域examplecom 的示例 URL

httpsauthexamplecomloginresponse_type=codeampclient_id=ltyour_app_client_idgtampredirect_uri=ltyour_callback_urlgt

更改自定义域的 SSL 证书

如果需要您可以使用 Amazon Cognito 更改应用于自定义域的证书

通常在使用 ACM 进行常规证书更新后此操作是不必要的当您更新 ACM 中的现有证书时证书的ARN 保持不变并且您的自定义域将自动使用新证书

但是如果您将现有证书替换为新证书ACM 将为新证书提供一个新 ARN要将新证书应用于自定义域您必须将此 ARN 提供给 Amazon Cognito

在提供新证书后Amazon Cognito 需要长达 1 小时才能将它分配给自定义域

开始前的准备工作

您必须先将证书添加到 ACM然后才能更改 Amazon Cognito 中的证书有关更多信息请参阅开始使用中的Amazon Certificate Manager用户指南当您将证书添加到 ACM 时您必须选择美国东部（弗吉尼亚北部）作为Amazon区域

37

Amazon Cognito 开发人员指南自定义内置网页

您可以使用 Amazon Cognito 控制台或 API 更改证书

更新证书（Amazon Cognito 控制台）

1 登录到Amazon Web Services Management Console并通过以下方面打开 Amazon Cognito 控制台httpsconsoleamazonawscncognitohome

2 选择 Manage User Pools (管理用户池)3 在 Your User Pools (您的用户池) 页面上选择要将您的域添加到的用户池4 在左侧导航菜单上选择 Domain name (域名)5 UNDER您自己的域用于Amazon托管证书下选择您的新证书6 选择保存更改

更新证书（Amazon Cognito API）

bull 使用 UpdateUserPoolDomain 操作

自定义内置登录网页和注册网页您可以使用 Amazon Web Services Management ConsoleAmazon CLI 或 API 为内置应用程序 UI 体验指定自定义设置您可以上传要显示在应用程序中的自定义徽标图像您也可以选择很多 CSS 自定义项

您可以为单个客户端 (具有特定的 clientId) 或为所有客户端 (通过将 clientId 设置为 ALL) 指定应用程序 UI 自定义设置如果您指定ALL则将对之前未设置 UI 自定义项的所有客户端使用默认配置如果您为某个特定客户端指定了 UI 自定义设置则它无法再回退到 ALL 配置

Note

要使用此功能您的用户池必须有一个与之关联的域

为应用程序指定自定义徽标徽标图像文件允许的最大大小为 100 KB

为应用程序指定 CSS 自定义项您可以为托管应用程序页面自定义 CSS但存在以下限制

bull CSS 类名称只能来自以下列表bull background-customizable

bull banner-customizable

bull errorMessage-customizable

bull idpButton-customizable

bull idpButton-customizablehover

bull inputField-customizable

bull inputField-customizablefocus

bull label-customizable

bull legalText-customizable

bull logo-customizable

bull submitButton-customizable

bull submitButton-customizablehover

bull textDescription-customizable

38


bull 属性值不能包含 HTMLimportsupportspage 或 media 语句也不能包含 Javascript

您可以自定义以下 CSS 属性

Labelsbull font-weight 是 100 的倍数 (从 100 到 900)

输入字段bull width 是以占包含块大小的百分比形式表示的宽度bull height 是输入字段的高度以像素 (px) 为单位bull color是文本颜色它可以是任何标准 CSS 颜色值bull Background color是输入字段的背景色它可以是任何标准颜色值bull 边框是标准 CSS 边框值用于指定您的应用程序窗口的边框的宽度透明度和颜色宽度可以是从

1px 到 100px 的任何值透明度可以是完全透明或不透明颜色可以是任何标准颜色值文本描述

bull padding-top 是文本描述上方的填充量bull padding-bottom 是文本描述下方的填充量bull display 可以是 block 或 inlinebull font-size 是文本描述的字体大小

提交按钮bull font-size 是按钮文本的字体大小bull font-weight 是按钮文本的字体粗细bolditalic 或 normalbull margin 是一个由 4 个值组成的字符串用于指示按钮的上边距右边距下边距和左边距大小bull font-size 是文本描述的字体大小bull width 是按钮文本的宽度以占包含块大小的百分比形式表示bull height 是按钮的高度以像素 (px) 为单位bull color是按钮文本颜色它可以是任何标准 CSS 颜色值bull Background color是按钮的背景色它可以是任何标准颜色值

横幅bull padding 是一个由 4 个值组成的字符串用于指示横幅的上边距右边距下边距和左边距大小bull Background color是横幅的背景色它可以是任何标准 CSS 颜色值

提交按钮悬停bull color是您将鼠标指针悬停在按钮上方时按钮的前景色它可以是任何标准 CSS 颜色值bull Background color是您将鼠标指针悬停在按钮上方时按钮的背景色它可以是任何标准 CSS 颜色值

身份提供商按钮悬停bull color是您将鼠标指针悬停在按钮上方时按钮的前景色它可以是任何标准 CSS 颜色值bull Background color是您将鼠标指针悬停在按钮上方时按钮的背景色它可以是任何标准 CSS 颜色值

密码校验无效bull color是Password check not valid消息它可以是任何标准 CSS 颜色值

背景bull Background color是应用程序窗口的背景色它可以是任何标准 CSS 颜色值

错误消息bull margin 是一个由 4 个值组成的字符串用于指示上边距右边距下边距和左边距大小bull padding 是边距大小bull font-size 是字体大小bull width 是错误消息的宽度以占包含块大小的百分比形式表示

39


bull 背景是错误消息的背景色它可以是任何标准 CSS 颜色值bull border 是一个由 3 个值组成的字符串用于指定边框的宽度透明度和颜色bull color是错误消息文本颜色它可以是任何标准 CSS 颜色值bull box-sizing 用于向浏览器指示应包含的大小属性 (宽度和高度)

身份提供商按钮bull height 是按钮的高度以像素 (px) 为单位bull width 是按钮文本的宽度以占包含块大小的百分比形式表示bull 文本对齐是文本对齐设置它可以是 leftright 或 centerbull margin-bottom 是下边距设置bull color是按钮文本颜色它可以是任何标准 CSS 颜色值bull Background color是按钮的背景色它可以是任何标准颜色值bull 边框颜色是按钮边框的颜色它可以是任何标准颜色值

身份提供商描述bull padding-top 是描述上方的填充量bull padding-bottom 是描述下方的填充量bull display 可以是 block 或 inlinebull font-size 是描述的字体大小

法律文本bull color是文本颜色它可以是任何标准 CSS 颜色值bull font-size 是字体大小

徽标bull max-width 是以占包含块大小的百分比形式表示的最大宽度bull max-height 是以占包含块大小的百分比形式表示的最大高度

输入字段聚焦bull 边框颜色是输入字段的颜色它可以是任何标准 CSS 颜色值bull outline 是输入字段的边框宽度 (以像素为单位)

社交按钮bull height 是按钮的高度以像素 (px) 为单位bull 文本对齐是文本对齐设置它可以是 leftright 或 centerbull width 是按钮文本的宽度以占包含块大小的百分比形式表示bull margin-bottom 是下边距设置

密码校验有效bull color是Password check valid消息它可以是任何标准 CSS 颜色值

为用户池指定应用程序 UI 自定义设置（Amazon Web ServicesManagement Console）您可以使用 Amazon Web Services Management Console为应用程序指定 UI 自定义设置

Note

通过利用您的用户池的特定信息构建以下 URL 并将它键入到浏览器中您可以查看具有自定义项的托管 UI httpsltyour_domaingtloginresponse_type=codeampclient_id=ltyour_app_client_idgtampredirect_uri=ltyour_callback_urlgt在控制台中进行的更改出现之前您可能必须等待长达 1 分钟才能刷新浏览器您的域显示在域名选项卡上您的应用程序客户端 ID 和回调 URL 显示在常规设置选项卡

40

Amazon Cognito 开发人员指南定义资源服务器

指定应用程序 UI 自定义设置

1 登录 Amazon Cognito 控制台2 在导航窗格中选择 Manage User Pools (管理用户池)然后选择要编辑的用户池3 选择 UI 自定义项选项卡4 在 App client to customize 下选择要从您之前在 App clients 选项卡中创建的应用程序客户端的下拉菜

单自定义的应用程序5 要上传您自己的徽标图像文件请选择 Choose a file 或者将文件拖动到 Logo (optional) 框中6 在 CSS customizations (optional) 下您可以通过更改各种属性的默认值来自定义应用程序的外观

为用户池指定应用程序 UI 自定义设置（Amazon CLI 和 AmazonAPI）使用以下命令可为您的用户池指定应用程序 UI 自定义项

获取用户池的内置应用程序 UI 的 UI 自定义设置

bull Amazon CLI aws cognito-idp get-ui-customizationbull Amazon APIGetUICustomization

设置用户池的内置应用程序 UI 的 UI 自定义设置

bull Amazon CLI aws cognito-idp set-ui-customization --user-pool-id ltyour-user-pool-idgt --client-id ltyour-app-client-idgt --image-file ltpath-to-logo-image-filegt --css label-customizable color ltcolorgt

bull Amazon APISetUICustomization

为您的用户池定义资源服务器在为用户池配置域后Amazon Cognito 服务会自动预置一个托管 Web UI您可使用此 UI 向应用程序添加注册页和登录页有关更多信息请参阅步骤 2 添加应用程序以启用托管 Web UI (p 20)

资源服务器是访问受保护的资源的服务器它处理从具有访问令牌的应用程序发送的身份验证请求通常情况下资源服务器将提供 CRUD API 来提出这些访问请求此 API 可以在 Amazon API Gateway 中或Amazon应用程序会将 API 调用中的访问令牌传递到资源服务器当应用程序在访问请求中传递令牌时它应该将访问令牌视为不透明的资源服务器将检查访问令牌以确定是否应授予访问权限

Note

您的资源服务器在处理访问令牌内的任何声明之前必须验证访问令牌的签名和到期日期有关验证和使用户池令牌的更多信息请参阅此博客帖子Amazon API Gateway 是用于检查访问令牌和保护您的资源的一个很好的选择有关 API Gateway Lambda 授权方的更多信息请参阅使用 APIGateway Lambda 授权方

范围是应用程序可请求的对资源的访问权限的级别例如如果您有一个照片资源服务器它可能会定义两个范围一个用于对照片的读取访问另一个用于写入删除访问当应用程序发出请求访问权限的 API 调用并传递访问令牌时该令牌将有一个或多个嵌入到其中的范围

概述

Amazon Cognito 允许应用程序开发人员创建自己的 OAuth20 资源服务器并在其中定义自定义范围自定义范围随后可以与某个客户端关联该客户端可以在 OAuth20 授权代码授予流隐式流和客户端凭证流中请求它们将在访问令牌的 scope 声明中添加自定义范围客户端可对其资源服务器使用访问令牌然后

41


服务器基于令牌中给出的范围做出授权决定有关访问令牌范围的更多信息请参阅将令牌与用户池结合使用 (p 139)

Note

您的资源服务器在处理访问令牌内的任何声明之前必须验证访问令牌的签名和到期日期

Note

如果某个应用程序客户端有客户端密钥则它只能使用客户端凭证流

管理资源服务器和自定义范围

在创建资源服务器时您必须提供资源服务器名称和资源服务器标识符对于您在资源服务器中创建的每个范围您都必须提供范围名称和描述

例如

bull Name资源服务器的友好名称如 Weather API 或 Photo APIbull Identifier资源服务器的唯一标识符这可能是您的资源服务器所在的 HTTPS 终端节点例

如httpsmy-weather-apiexamplecom

bull Scope Name范围名称例如weatherread

bull Scope Description范围的简要说明例如Retrieve weather information

当客户端应用程序在任一 OAuth20 流中请求自定义范围时它必须请求范围的完整标识符即 resourceServerIdentifierscopeName例如如果资源服务器标识符是 httpsmyphotosapiexamplecom范围名称是 photosread则客户端应用程序必须在运行时请求httpsmyphotosapiexamplecomphotosread

从资源服务器中删除一个范围不会删除其与所有客户端的关联删除范围只会使其处于非活动状态因此如果客户端应用程序在运行时请求已删除的范围则该范围将被忽略并且不会包含在访问令牌中如果之后重新添加了该范围它将会再次包含在访问令牌中

如果从客户端中删除了某个范围则会删除客户端与范围之间的关联如果客户端在运行时请求了不允许使用的范围则会导致错误并且不会颁发访问令牌

您可以使用 Amazon Web Services Management ConsoleAPI 和 CLI 为您的用户池定义资源服务器和范围

为您的用户池定义资源服务器 (Amazon Web ServicesManagement Console)您可以使用 Amazon Web Services Management Console为您的用户池定义资源服务器

定义资源服务器

1 登录 Amazon Cognito 控制台2 在导航窗格中选择 Manage User Pools (管理用户池)然后选择要编辑的用户池3 选择资源服务器选项卡4 选择添加资源服务器5 输入您的资源服务器的名称 (例如Photo Server)6 输入您的资源服务器的标识符 (例如comexamplephotos)7 输入您的资源的自定义范围的名称例如 read 和 write8 对于每个范围名称输入一个描述如 view your photos 和 update your photos

42

Amazon Cognito 开发人员指南添加通过第三方登录


您定义的每个自定义范围都将显示在应用程序客户端设置选项卡的 OAuth20 允许的自定义范围下面例如comexamplephotosread

为您的用户池定义资源服务器（Amazon CLI 和 Amazon API）使用以下命令可为您的用户池指定资源服务器设置

创建资源服务器

bull Amazon CLI aws cognito-idp create-resource-serverbull Amazon APICreateResourceServer

获取有关您的资源服务器设置的信息

bull Amazon CLI aws cognito-idp describe-resource-serverbull Amazon APIDescribeResourceServer

列出用户池的所有资源服务器的相关信息

bull Amazon CLI aws cognito-idp list-resource-serversbull Amazon APIListResourceServers

删除资源服务器

bull Amazon CLI aws cognito-idp delete-resource-serverbull Amazon APIDeleteResourceServer

更新资源服务器的设置

bull Amazon CLI aws cognito-idp update-resource-serverbull Amazon APIUpdateResourceServer

通过第三方添加用户池登录您的应用程序用户可以通过用户池直接登录也可以通过第三方身份提供商 (IdP) 联合登录用户池管理处理以下令牌的开销从通过 FacebookGoogleAmazon 和苹果进行 OpenID 社交登录返回的令牌利用内置托管 Web UIAmazon Cognito 将为来自所有身份提供商的经过身份验证的用户提供令牌处理和管理让后端系统能够基于一组用户池令牌实现标准化

Note

通过第三方 (联合身份验证) 进行登录可在 Amazon Cognito 用户池中实现此功能不依赖于通过Amazon Cognito 身份池 (联合身份) 实现的联合身份验证

43

Amazon Cognito 开发人员指南添加社交身份提供商

主题bull 向用户池添加社交身份提供商 (p 44)bull 向用户池添加 SAML 身份提供商 (p 49)bull 向用户池添加 OIDC 身份提供商 (p 55)bull 指定适用于用户池的身份提供商属性映射 (p 60)

向用户池添加社交身份提供商您的 Web 和移动应用程序用户可以通过社交身份提供商 (IdP)（例如 FacebookGoogleAmazon 和Apple）进行登录利用内置托管 Web UIAmazon Cognito 将为所有经过身份验证的用户提供令牌处理和管理让后端系统能够基于一组用户池令牌实现标准化

您可以在Amazon Web Services Management Console使用AmazonCLI或使用 Amazon Cognito API 调用

Note


主题bull Prerequisites (p 44)bull 第 1 步向社交 IdP 注册 (p 44)bull 第 2 步将社交 IdP 添加到用户池 (p 47)bull 第 3 步测试社交 IdP 配置 (p 48)

Prerequisites在开始之前您需要

bull 具有应用程序客户端和用户池域的用户池有关更多信息请参阅创建用户池bull 社交身份提供商



1 创建 Facebook 开发人员账户2 使用 Facebook 凭证登录3 在 My Apps (我的应用程序) 菜单上选择 Create New App (创建新的应用程序)4 为 Facebook 应用程序提供一个名称然后选择 Create App ID (创建应用程序 ID)5 在左侧导航栏上选择 Settings (设置)然后选择 Basic (基本)

44


6 记下 App ID (应用程序 ID) 和 App Secret (应用程序密钥)您将在下一节中使用它们7 从页面底部选择 + Add Platform (+ 添加平台)8 选择网站9 在 Website (网站) 下将具有 oauth2idpresponse 终端节点的用户池域键入到 Site URL (站点 URL)

中

















11 选择 Save

45



1 创建 Google 开发人员账户2 使用 Google 凭证登录3 选择 CONFIGURE A PROJECT (配置项目)4 键入项目名称然后选择 NEXT (下一步)5 键入产品名称并选择 NEXT (下一步)6 选择Web 浏览器来自的你从哪儿打电话下拉列表中)7 在 Authorized JavaScript origins (授权的 JavaScript 源) 中键入用户池域









1 创建 Apple 开发人员账户2 使用 Apple 凭证登录3 在左侧导航栏上选择证书ID 和配置文件4 在左侧导航栏上选择标识符5 在存储库的标识符页面上选择+图标6 在存储库的注册新标识符页面上选择应用程序 ID然后选择Continue7 在 Register an App ID (注册应用程序 ID) 页面上执行以下操作

1 在 Description (描述) 下方键入描述2 Under应用程序 ID 前缀中键入标识符记下应用程序 ID 前缀因为在您选择 Apple 作为第 2 步

将社交 IdP 添加到用户池 (p 47)3 UnderCapabilities中选择使用 Apple 登录然后选择编辑4 在存储库的使用 Apple 登录应用程序 ID 配置页面上为您的应用程序选择适当的设置然后选

择Save

46


5 选择 Continue (继续)8 在 Confirm your App ID (确认您的应用程序 ID) 页面上选择 Register (注册)9 在存储库的标识符页面上将鼠标悬停在应用程序 ID在页面右侧选择服务 ID然后选择+图标10 在存储库的注册新标识符页面上选择服务 ID然后选择Continue11 在 Register an Services ID (注册服务 ID) 页面上执行以下操作

1 在 Description (描述) 下方键入描述2 在 Identifier (标识符) 下方键入标识符记下此服务 ID因为在第 2 步将社交 IdP 添加到用户

池 (p 47)3 Select使用 Apple 登录然后选择配置4 在 Web Authentication Configuration (Web 身份验证配置) 页面上选择 Primary App ID (主应用程

序 ID)Under網域中键入您的用户池域Under返回 URL中键入您的用户池域并包含 oauth2idpresponse 终端节点例如



12 在左侧导航栏上选择密钥13 在 Keys (密钥) 页面上选择 + 图标14 在 Register a New Key (注册新密钥) 页面上执行以下操作


15 在存储库的下载您的密钥页面上选择下载以下载私有密钥然后选择Done您将需要这个私钥和键ID值然后选择 Apple 作为您的身份提供商第 2 步将社交 IdP 添加到用户池 (p 47)



1 转到Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 选择 Manage your User Pools3 从列表中选择现有用户池或创建用户池4 在左侧导航栏上选择身份提供商5 选择社交身份提供商FacebookGoogleLogin with Amazon或者Apple6 对于 Google 和 Login with Amazon键入在上一节中从社交身份提供商处收到的应用程序客户端 ID 和

应用程序客户端密钥对于 Facebook键入在上一节中从社交身份提供商处收到的应用程序客户端 ID和应用程序客户端密钥并选择 API 版本我们建议选择尽可能高的可用版本因为每个 FacebookAPI 版本都有一个生命周期和一个弃用日期例如版本 212如果遇到任何问题您可以在创建后更改API 版本Facebook 作用域和属性可能因每个 API 版本而异因此我们建议您测试集成rdquo 对于ldquo使用Apple 登录rdquo请提供在上一节中收到的服务 ID团队 ID密钥 ID 和私有密钥


47













httpswwwexamplecom







Note


48

Amazon Cognito 开发人员指南添加 SAML 提供商

向用户池添加 SAML 身份提供商可允许 Web 和移动应用程序用户通过 SAML 身份提供商 (IdP)（如 Microsoft Active Directory 联合身份验证服务 (ADFS) 或 Shibboleth）登录选择支持 SAML 20 标准的 SAML 身份提供商

利用内置托管 Web UIAmazon Cognito 将为所有经过身份验证的用户提供令牌处理和管理让后端系统能够基于一组用户池令牌实现标准化您可 IdP 在Amazon Web Services Management Console使用AmazonCLI或使用 Amazon Cognito API 调用要开始使用控制台请参阅使用 Amazon Web ServicesManagement Console将ldquo通过基于 SAML 的身份提供商登录rdquo添加到用户池

Note


您需要更新 SAML 身份提供商并配置用户池以支持此功能请参阅 SAML 身份提供商的文档了解有关如何将您的用户池添加为 SAML 20 身份提供商的依赖方或应用程序的信息

Note

Cognito 支持大于 80 个字节的 relayState 值虽然 SAML 规范规定 relayState 值 ldquo长度不得超过 80 个字节rdquo但目前的行业惯例往往偏离这种行为因此拒绝超过 80 个字节的relayState 将破坏许多标准 SAML 提供商集成






您可以在常规设置选项卡中的Amazon Cognito 控制台


Amazon Cognito 用户池支持 SAML 20 与绑定后终端节点联合这使您的应用程序不必检索或分析 SAML断言响应因为用户池直接通过用户代理从身份提供商接收 SAML 响应您的用户池代表您的应用程序充当服务提供商 (SP)Amazon Cognito 支持 SP 发起的单一登录 (SSO)如SAML V20 技术概述

主题bull SAML 用户池 IdP 身份验证流程 (p 50)bull 选择 SAML 身份提供商名称 (p 50)bull 为用户池创建和管理 SAML 身份提供商 (Amazon Web Services Management Console) (p 51)

49


bull 为用户池创建和管理 SAML 身份提供商（Amazon CLI 和 Amazon API） (p 53)bull 将第三方 SAML 身份提供商与 Amazon Cognito 用户池集成 (p 54)

SAML 用户池 IdP 身份验证流程您可以直接从您的用户池集成基于 SAML 的 IdP

1 应用程序通过将用户定向到由 Amazon 托管的 UI 来开始注册和登录过程移动应用程序可以使用 Web视图显示由 Amazon 托管的页

2 通常您的用户池将通过用户的电子邮件地址确定用户的身份提供商

或者如果您的应用程序在将用户定向到用户池之前已收集信息它可以通过查询参数来向 AmazonCognito 提供这些信息

3 您的用户将重定向到身份提供商4 IdP 将对用户进行身份验证 (如有必要)如果 IdP 发现用户具有活动会话则 IdP 将跳过身份验证以提

供单一登录 (SSO) 体验5 IdP 以 POST 方式将 SAML 断言发送到 Amazon Cognito 服务6 在验证 SAML 断言并收集断言中的用户属性 (声明) 后Amazon Cognito 在内部创建或更新用户池中的

用户配置文件Amazon Cognito 将 OIDC 令牌返回到当前已登录用户的应用程序

下图显示了此过程的身份验证流程

Note


当用户进行身份验证后用户池将返回 ID访问权限和刷新令牌ID 令牌是用于身份管理的标准 OIDC 令牌而访问令牌是标准 OAuth 20 令牌虽然 ID 和访问令牌将在 1 小时后过期但应用程序可使用刷新令牌来获取新令牌而无需让用户重新进行身份验证作为开发人员您可以选择刷新令牌的到期时间从而设定用户需要重新进行身份验证的频率如果用户已通过外部 IdP 进行身份验证 (即他们是联合身份用户)则应用程序仍会将 Amazon Cognito 令牌与刷新令牌结合使用来决定用户重新进行身份验证之前经过的时间无论外部 IdP 的令牌何时到期当 ID 和访问令牌过期后用户池将自动使用刷新令牌来获取新的 ID和访问令牌如果刷新令牌也已过期则服务器将通过由 Amazon 托管的应用程序中的页面来自动启动身份验证

选择 SAML 身份提供商名称您需要为 SAML 提供商选择名称字符串的格式为 [ws+=-]+长度最多为 40 个字符

50


(可选) 您还可以为 SAML 提供商选择标识符标识符将唯一解析为与用户池关联的身份提供商通常每个标识符均对应于一个属于 SAML IdP 代表的公司的域对于可由不同的公司使用的多租户应用程序标识符可用于将用户重定向到正确的 IdP由于可能存在同一公司所拥有的多个域因此您可以提供多个标识符

您可以为每个 SAML 提供商关联最多 50 个标识符标识符在身份提供商中必须是唯一的

例如假定您构建了一个可由两个不同的公司 (公司 A 和公司 B) 的员工使用的应用程序公司 A 拥有domainAcom 和 domainAcouk公司 B 拥有 domainBcom进一步假定您设置了两个 IdP一个公司对应一个 Idp

bull 对于 IdP A您可以定义标识符 DomainAcom 和 DomainAcoukbull 对于 IdP B您可以定义标识符 DomainBcom

在您的应用程序中您可以提示用户输入其电子邮件地址通过从电子邮件地址派生域您可以将用户重定向到正确的 IdP方式是在对 IdPIdentifier 终端节点的调用中提供 authorize 中的域例如如果用户输入 bobdomain1couk则用户将重定向到 IdP A

由 Amazon Cognito 托管的登录页将自动解析电子邮件地址以派生信息它会解析电子邮件中的电子邮件域并在调用 IdPIdentifier 终端节点时将其用作 authorize

bull 如果您有多个 SAML IdP 并且全部为它们指定 IdPIdentifier 值则您将会在托管页面上看到一个用于输入电子邮件地址的框

bull 如果您有多个 IdP且您未为其中任意一个指定 IdPIdentifier 值则托管页面将显示 IdP 列表

如果您构建自己的 UI则应解析域名以便它匹配 IdP 设置期间提供的 IdPIdentifiers有关 IdP 设置的更多信息请参阅为用户池配置身份提供商 (p 168)

为用户池创建和管理 SAML 身份提供商 (Amazon Web ServicesManagement Console)您可以使用 Amazon Web Services Management Console创建和删除 SAML 身份提供商

在创建 SAML 身份提供商之前您需要使用从第三方身份提供商 (IdP) 处获得的 SAML 元数据文档有关如何获取或生成所需的 SAML 元数据文档的说明请参阅将第三方 SAML 身份提供商与 Amazon Cognito 用户池集成 (p 54)


1 转到Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 Manage User Pools (管理用户池)3 从列表中选择现有用户池或创建用户池4 在左侧导航栏上选择身份提供商5 选择 SAML 以打开 SAML 对话框6 在元数据文档下通过 SAML IdP 上传元数据文档还可以输入指向该元数据文档的 URL有关更多信


Note


7 输入 SAML 提供商名称有关 SAML 命名的更多信息请参阅选择 SAML 身份提供商名称 (p 50)8 输入要使用的任何可选 SAML 标识符

51


9 Select启用 IdP 注销流如果您希望用户在从 Amazon Cognito 注销的同时从 SAML IdP 注销

如果启用此流程在调用 LOGOUT 终端节点 (p 337) 时将会向 SAML IdP 发送已签名的注销请求



Note






Note

如果您在使用 HTTPS 元数据终端节点 URL 创建 SAML 身份提供商时看见InvalidParameterException（例如ldquoError retrieving metadata from ltmetadataendpointgt (从 lt元数据终端节点gt 检索元数据时出错)rdquo）请确保元数据终端节点已正确设置SSL并且存在与之关联的有效 SSL 证书

设置 SAML IdP 以添加用户池作为信赖方

bull 用户池服务提供商 URN 为urnamazoncognitospltuser_pool_idgtAmazon Cognito 发布AuthnRequest以发布 SAML IdP 以发布 SAML 断言以及对此 URN 的受众限制您的 IdP 将以下 POST 绑定终端节点用于 IdP 到 SP 的响应消息httpsltdomain_prefixgtauthltregiongtamazoncognitocomsaml2idpresponse

bull 确保您的 SAML IdP 在 SAML 断言中为用户池填充 NameID 和任何所需属性NameID 用于在用户池中唯一地标识您的 SAML 联合身份用户使用持久性 SAML 名称 ID 格式

设置 SAML IdP 以添加签名证书

bull 要获取包含身份提供商将用于验证已签名注销请求的公钥的证书请在 Federation (联合身份验证) 控制台页面上 Identity providers (身份提供商) 下的 SAML 对话框中选择 Active SAML Providers (活动 SAML 提供商) 下的 Show signing certificate (显示签名证书)

删除 SAML 提供商

1 登录 Amazon Cognito 控制台

52


2 在导航窗格中选择管理您的用户池然后选择要编辑的用户池3 从联合身份验证控制台页面中选择身份提供商4 选择 SAML 以显示 SAML 身份提供商5 选中要删除的提供商旁边的复选框6 选择删除提供商

为用户池创建和管理 SAML 身份提供商（Amazon CLI 和 AmazonAPI）使用以下命令可创建和管理 SAML 提供商

创建身份提供商并上传元数据文档

bull Amazon CLI aws cognito-idp create-identity-provider

带元数据文件的示例aws cognito-idp create-identity-provider --user-pool-idltuser_pool_idgt --provider-name=SAML_provider_1 --provider-type SAML --provider-details filedetailsjson --attribute-mapping email=httpschemasxmlsoaporgws200505identityclaimsemailaddress

其中 detailsjson 包含

MetadataFile ltSAML metadata XMLgt

Note

如果 ltSAML metadata XMLgt 包含任何引号 ()则必须对其进行转义 ()

带元数据 URL 的示例aws cognito-idp create-identity-provider --user-pool-id ltuser_pool_idgt --provider-name=SAML_provider_1 --provider-type SAML --provider-details MetadataURL=ltmetadata_urlgt --attribute-mapping email=httpschemasxmlsoaporgws200505identityclaimsemailaddress

bull Amazon APICreateIdentityProvider

为身份提供商上传新的元数据文档

bull Amazon CLI aws cognito-idp update-identity-provider

带元数据文件的示例aws cognito-idp update-identity-provider --user-pool-idltuser_pool_idgt --provider-name=SAML_provider_1 --provider-details filedetailsjson --attribute-mapping email=httpschemasxmlsoaporgws200505identityclaimsemailaddress



Note


53


带元数据 URL 的示例aws cognito-idp update-identity-provider --user-pool-id ltuser_pool_idgt --provider-name=SAML_provider_1 --provider-details MetadataURL=ltmetadata_urlgt --attribute-mapping email=httpschemasxmlsoaporgws200505identityclaimsemailaddress

bull Amazon APIUpdateIdentityProvider

获取有关特定身份提供商的信息

bull Amazon CLI aws cognito-idp describe-identity-provider

aws cognito-idp describe-identity-provider --user-pool-id ltuser_pool_idgt --provider-name=SAML_provider_1

bull Amazon APIDescribeIdentityProvider

列出有关所有身份提供商的信息

bull Amazon CLI aws cognito-idp list-identity-providers

示例aws cognito-idp list-identity-providers --user-pool-id ltuser_pool_idgt --max-results 3

bull Amazon API列表 ListIdentityProviders

删除 IdP

bull Amazon CLI aws cognito-idp delete-identity-provider

aws cognito-idp delete-identity-provider --user-pool-id ltuser_pool_idgt --provider-name=SAML_provider_1

bull Amazon APIDeleteIdentityProvider

将第三方 SAML 身份提供商与 Amazon Cognito 用户池集成要配置第三方 SAML 20 身份提供商解决方案以使用 Amazon Cognito用户池的联合身份验证您必须输入一个重定向或登录 URL即httpsltyourDomainPrefixgtauthltregiongtamazoncognitocomsaml2idpresponse您可以在域名控制台页面Amazon Cognito 控制台

Note

在 2017 年 8 月 10 日前的公开测试期间您在用户池中创建的任何 SAML 身份提供商都具有重定向 URL httpsltyourDomainPrefixgtauthltregiongtamazoncognitocomloginredirect如果您的用户池中的公开测试版中具有这些 SAML 身份提供商之一则必须执行以下操作之一

bull 将其替换为使用新的重定向 URL 的新身份提供商bull 更新您的 SAML 身份提供商中的配置以接受旧的和新的重定向 URL

Amazon Cognito 中的所有 SAML 身份提供商都将切换到新的 URL旧的 URL 将于 2017 年 10 月31 日停止工作

对于一些 SAML 身份提供商您必须以 urnamazoncognitospltyourUserPoolIDgt 格式提供 urn 受众 URISP 实体 ID您可以在常规设置选项卡

54

Amazon Cognito 开发人员指南添加 OIDC 提供商

您还必须配置 SAML 身份提供商为您用户池中需要的任意属性提供属性值通常email 是用户池的必需属性这种情况下 SAML 身份提供商将需要在 SAML 断言中提供 email 值 (声明)

以下链接将帮助您配置第三方 SAML 20 身份提供商解决方案以使用 Amazon Cognito 用户池的联合身份验证

Note

身份提供商支持已内置在 Amazon Cognito 中因此您只需转至以下提供商站点即可获取 SAML元数据文档您可以在提供商网站上查看有关与 Amazon 集成的详细说明但您不需要这些说明

解决方案更多信息

Microsoft Active Directory 联合身份验证服务 (ADFS)

您可以从以下地址下载 ADFS 联合身份验证服务器的 SAML 元数据文档httpsltyourservernamegtFederationMetadata2007-06FederationMetadataxml

Okta 在 Okta 中将 Amazon Cognito 用户池配置为应用程序后您可以在管理员部分选择应用程序选择 Sign On (登录) 部分然后查看 Settings forSAML (SAML 设置) 下方的内容该 URL 应类似于httpsltapp-domaingtoktapreviewcomappltapplication-IDgtssosamlmetadata

Auth0 从 Auth0 控制面板获取元数据下载文档选择Clients (客户端)然后选择 Settings (设置)向下滚动选择 Show Advanced Settings (显示高级设置)然后查找您的 SAML Metadata URL (SAML元数据 URL)它应该类似于 httpsltyour-domain-prefixgtauth0comsamlpmetadataltyour-Auth0-client-IDgt

Ping 身份对于 PingFederate您可以在通过文件提供一般SAML 元数据中找到有关下载元数据 XML 文件的说明

向用户池添加 OIDC 身份提供商您可以启用已经拥有OpenID Connect (OIDC)身份提供商 (IIdPs)（如Salesforce或者Ping 身分) 跳过注册步骤 mdash 并使用现有帐户登录您的应用程序利用内置托管 Web UIAmazon Cognito 将为所有经过身份验证的用户提供令牌处理和管理让后端系统能够基于一组用户池令牌实现标准化

Note


您可以将 OIDC IdP 添加到Amazon Web Services Management Console使用AmazonCLI或通过使用用户池 API 方法CreateIdentityProvider

55


主题bull Prerequisites (p 56)bull 第 1 步向 OIDC IdP 注册 (p 56)bull 第 2 步将 OIDC IdP 添加到用户池 (p 58)bull 第 3 步测试 OIDC IdP 配置 (p 59)bull OIDC 用户池 IdP 身份验证流程 (p 59)


bull 具有应用程序客户端和用户池域的用户池有关更多信息请参阅创建用户池bull 一个 OIDC IdP

第 1 步向 OIDC IdP 注册在使用 Amazon Cognito 创建 OIDC IdP 之前必须向 OIDC IdP 注册应用程序才能接收客户端 ID 和客户端密钥

向 OIDC IdP 注册

1 使用 OIDC IdP 创建开发人员账户

链接到 OIDC IdP

OIDC IdP 如何安装 OIDC 发现 URL

Salesforce 安装 Salesforce 身份提供商 httpsloginsalesforcecom

Ping 身分安装 Ping Identity 身份提供商 https资资 Ping 资资资9031idpuserinfoopenid

例如httpspfcompanycom9031idpuserinfoopenid

Okta 安装 Okta 身份提供商 https资资 Okta 资资oktapreviewcom

或者 httpsYour Oktasubdomainoktacom

Microsoft Azure Active Directory(Azure AD)

安装 Microsoft Azure AD 身份提供商

httpsloginwindowsnetcommon

Google 安装 Google 身份提供商 httpsaccountsgooglecom

Note

Amazon Cognito 提供Google 作为集成社交登录 IdP建议使用此集成 IdP请参阅向用户池添加社交身份提供商 (p 44)

56


2 向 OIDC IdP 注册具有 oauth2idpresponse 终端节点的用户池域 URL这将确保 OIDC IdP 之后在对用户进行身份验证时通过 Amazon Cognito 接受此 URL


3 向 Cognito 用户池注册回调 URL这是页面的 URL在页面中您的用户在身份验证成功后将被重定向

httpswwwexamplecom

4 选择范围范围 openid 为必填字段需要电子邮件范围来授予对 email 和 email_verified 声明的访问权限

5 OIDC IdP 为您提供客户端 ID 和客户端密钥您在用户池中设置 OIDC IdP 时将使用它们

例如使用 Salesforce 作为用户池的 OIDC IdP

当您要在与 OIDC 兼容的 IdP (如 Salesforce) 和您的用户池之间建立信任时请使用 OIDC 身份提供商

1 在 Salesforce 开发人员网站上创建账户2 通过在上一步中设置的开发人员账户登录3 查看 Salesforce 页面的顶部

bull 如果您使用的是 Lightning Experience请选择ldquoSetup (设置)rdquo齿轮图标然后选择 Setup Home (设置主页)

bull 如果您使用的是 Salesforce Classic 并且在用户界面标题中看到 Setup (设置)请选择它bull 如果您使用的是 Salesforce Classic 但没有在用户界面标题中看到 Setup (设置)请从顶部导航栏中选

择您的姓名然后从下拉列表中选择 Setup (设置)4 在左侧导航栏上选择 Company Settings (公司设置)5 在导航栏上选择 Domain (域)键入一个域然后选择 Create (创建)6 在左侧导航栏上转至 Platform Tools (平台工具) 并选择 Apps (应用程序)7 选择 App Manager (应用程序管理器)8 a 选择 new connected app (新连接的应用程序)

b 填写必填字段

在 Start URL (启动 URL) 下键入具有 oauth2idpresponse 终端节点的用户池域 URL


c 启用 OAuth settings (OAuth 设置) 并将您的回调 URL 键入到 Callback URL (回调 URL)这是页面的 URL在页面中您的用户在成功登录后将被重定向

httpswwwexamplecom


范围由空格分隔10 选择创建

在 Salesforce 中客户端 ID 称为 Consumer Key (使用者密钥)客户端密钥为 Consumer Secret (使用者私有密钥)记下您的客户端 ID 和客户端密钥您将在下一节中使用它们

57


第 2 步将 OIDC IdP 添加到用户池在本节中配置用户池以通过 OIDC IdP 处理基于 OIDC 的身份验证请求

添加 OIDC IdP (Amazon Cognito 控制台)

1 转到Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 Manage User Pools (管理用户池)3 从列表中选择现有用户池或创建用户池4 在左侧导航栏上选择身份提供商5 选择 OpenID Connect6 在提供商名称中键入一个唯一名称7 在客户端 ID 中键入上一节中的 OIDC IdP 的客户端 ID8 在客户端密钥中键入上一节中的客户端密钥9 在下拉列表中选择用于将 userinfo 终端节点中的用户的详细信息提取到属性请求方法的 HTTP 方法

（GET 或 POST）10 键入要授权的范围的名称范围定义了您要通过应用程序访问的用户属性 (如 name 和 email)根据

OAuth 20 规范范围由空格分隔

您的应用程序用户需要同意向您的应用程序提供这些属性11 键入 IdP 的 URL然后选择运行发现

Note

URL 应该以 https 开头并且不应以下斜杠结尾只有端口号 443 和 80 可用于此URL例如Salesforce 使用以下 URLhttpsloginsalesforcecom

bull 如果运行发现不成功则需要提供授权终端节点令牌终端节点用户信息终端节点和 Jwksuri（JSON Web Key的位置）

Note

如果提供程序使用发现进行联合登录则发现文档必须对以下值使用 HTTPS授权终端令牌终端用户信息端点和 jwks_uri否则登录将失败

12 选择创建提供商13 在左侧导航栏上选择应用程序客户端设置14 选择在上一步中设置的 OIDC 提供商作为启用身份提供商之一15 键入一个回调 URL供 Amazon Cognito 授权服务器在用户通过身份验证之后进行调用这是页面的

URL在页面中您的用户在身份验证成功后将被重定向

httpswwwexamplecom

16 在允许的 OAuth 流程下启用授权代码授予和隐式代码授予

除非您希望明确地排除一个允许的 OAuth 范围否则请选中所有ldquo允许的 OAuth 范围rdquo的复选框17 选择保存更改18 在左侧导航栏的属性映射选项卡上将 OIDC 声明的映射添加到用户池属性

a 作为默认值OIDC 声明 sub 将映射到用户池属性用户名您可以将其他 OIDC 声明映射到用户池属性键入 OIDC 声明然后从下拉列表中选择对应的用户池属性例如声明 email 通常会映射到用户池属性电子邮件

58


b 在下拉列表中选择目标用户池属性c 选择保存更改d 选择转到摘要页面

添加 OIDC IdP (Amazon CLI)

bull 请参阅 CreateIdentityProvider API 方法的参数描述

aws cognito-idp create-identity-provider--user-pool-id string--provider-name string--provider-type OIDC--provider-details map

--attribute-mapping string--idp-identifiers (list)--cli-input-json string--generate-cli-skeleton string

使用此提供商详细信息映射

client_id string client_secret string authorize_scopes string attributes_request_method string oidc_issuer string

authorize_url string token_url string attributes_url string jwks_uri string

第 3 步测试 OIDC IdP 配置可以通过使用上两节中的元素并使用这些元素测试 OIDC IdP 配置来创建授权 URL

httpsltyour_user_pool_domaingtoauth2authorizeresponse_type=codeampclient_id=ltyour_client_idgtampredirect_uri=httpswwwexamplecom

您可以在用户池域名控制台页上找到您的域您可以在 General settings (常规设置) 页面上找到 client_id对于 redirect_uri 参数使用您的回调 URL这是页面的 URL在页面中您的用户在身份验证成功后将被重定向

OIDC 用户池 IdP 身份验证流程当您的用户使用 OIDC IdP 登录您的应用程序时这就是身份验证流程

59

Amazon Cognito 开发人员指南指定属性映射

1 您的用户将登录 Amazon Cognito 内置登录页面并获得通过 OIDC IdP (如 Salesforce) 登录的选项2 您的用户将重定向到 OIDC IdP 的 authorization 终端节点3 在您的用户经过身份验证后OIDC IdP 将使用授权代码重定向至 Amazon Cognito4 Amazon Cognito 将与 OIDC IdP 交换此授权代码以获得访问令牌5 Amazon Cognito 在您的用户池中创建或更新用户账户6 Amazon Cognito 颁发应用程序持有者令牌可能包括身份访问和刷新令牌

Note


OIDC 是基于 OAuth 20 的身份层它指定 IdP 向 OIDC 客户端应用程序 (信赖方) 颁发的 JSON 格式的(JWT) 身份令牌有关将 Amazon Cognito 添加为 OIDC 信赖方的信息请参阅您的 OIDC IdP 的文档

当用户进行身份验证后用户池将返回 ID访问权限和刷新令牌ID 令牌是用于身份管理的标准 OIDC 令牌而访问令牌是标准 OAuth 20 令牌

指定适用于用户池的身份提供商属性映射您可以使用 Amazon Web Services Management ConsoleAmazon CLI 或 API 来指定用户池的身份提供商的属性映射

关于映射的需知信息在使用映射之前请查看以下重要详细信息

bull 用户登录您的应用程序时所需的每个用户池属性必须存在映射例如如果您的用户池需要电子邮件属性来登录则将此属性映射到身份提供商中的对等属性

bull 默认情况下映射的电子邮件地址未验证您无法使用一次性代码验证映射的电子邮件地址而是映射身份提供商的属性以获取验证状态例如谷歌和大多数 OIDC 提供商都包含email_verified属性

bull 对于每个映射的用户池属性最大值长度 (2048 个字符) 必须足够大以容纳 Amazon Cognito 从身份提供商处获取的值否则用户登录您的应用程序时Amazon Cognito 会引发错误如果您将自定义属性映射到身份提供商令牌请将长度设置为 2048 个字符

60


bull 对于以下身份提供商username 用户池属性必须仅映射到特定属性

身份提供商映射到 username 的属性

Facebook id

Google sub

Login with Amazon user_id

OpenID Connect (OIDC) 提供商 sub

使用 Apple 登录 sub

bull 用户登录您的应用程序时Amazon Cognito 必须能够更新映射的用户池属性用户通过某个身份提供商登录时Amazon Cognito 将使用来自身份提供商的最新信息更新映射的属性Amazon Cognito 更新各个映射的属性即使当前值已经与最新信息匹配如果 Amazon Cognito 无法更新属性它会引发错误要确保 Amazon Cognito 可以更新属性请检查以下要求bull 映射的用户池属性必须可变具有可变属性写入权限的应用程序客户端可以更新这些属性在

Amazon Cognito 控制台中定义用户池属性时您可以将这些属性设置为可变或者如果您使用CreateUserPool API 操作创建用户池则可将这些属性中的每个属性的 Mutable 参数设置为 true

bull 在应用程序的应用程序客户端设置中映射的属性必须可写您可以设置哪些属性可写入到应用程序客户端页面上的 Amazon Cognito 控制台或者如果您使用 CreateUserPoolClient API 操作创建应用程序客户端则可以将这些属性添加到 WriteAttributes 数组

bull 如果身份提供商属性包含多个值Amazon Cognito 将对包含非字母数字字符的值进行 URL 表单进行编码（不包括 - 和_字符）您应该在应用程序中使用之前对这些值进行解码

指定适用于用户池的身份提供商属性映射 (Amazon Web ServicesManagement Console)您可以使用 Amazon Web Services Management Console指定用户池的身份提供商的属性映射

Note

只有当声明存在于传入令牌中时Amazon Cognito 才会将传入声明映射到用户池属性如果之前映射的声明不再存在于传入令牌中则不会被删除或更改如果您的应用程序需要映射已删除的声明则可以使用预身份验证 lambda 触发器在身份验证期间删除自定义属性并允许从传入令牌重新填充这些属性

指定社交身份提供商属性映射

1 登录 Amazon Cognito 控制台2 在导航窗格中选择管理您的用户池然后选择要编辑的用户池3 选择属性映射选项卡4 选择 FacebookGoogleAmazon 或 Apple 选项卡5 对于需要映射的每个属性请执行以下步骤

a 选中截取复选框b 对于用户池属性在下拉列表中选择要映射到社交身份提供商属性的用户池属性c 如果您需要更多属性请选择添加 Facebook 属性（或者添加 Google 属性添加 Amazon 属性

或添加 Apple 属性）并执行以下步骤

i 在 Facebook 属性（或者 Google 属性Amazon 属性或 Apple 属性）字段中输入要映射的属性的名称

61


ii 在用户池属性字段中从下拉列表中选择要将社交身份提供商属性映射到的用户池属性d 选择保存更改

指定 SAML 提供商属性映射

1 登录 Amazon Cognito 控制台2 在导航窗格中选择管理您的用户池然后选择要编辑的用户池3 选择属性映射选项卡4 选择 SAML 选项卡5 选中要捕获其值的所有属性对应的截取框如果您清除某个属性的截取框并保存您的更改则将删除该

属性的映射6 从下拉列表中选择身份提供商7 对于需要映射的每个属性请执行以下步骤

a 选择添加 SAML 属性b 在 SAML 属性字段中输入要映射的 SAML 属性的名称c 在用户池属性字段中从下拉列表中选择要将 SAML 属性映射到的用户池属性


指定适用于用户池的身份提供商属性映射（Amazon CLI 和Amazon API）使用以下命令可为您的用户池指定身份提供商属性映射

在提供商创建时指定属性映射





Note




指定现有身份提供商的属性映射


62

Amazon Cognito 开发人员指南使用 Lambda 触发器

示例aws cognito-idp update-identity-provider --user-pool-id ltuser_pool_idgt--provider-name ltprovider_namegt --attribute-mapping email=httpschemasxmlsoaporgws200505identityclaimsemailaddress


获取有关特定身份提供商的属性映射的信息


示例aws cognito-idp describe-identity-provider --user-pool-id ltuser_pool_idgt--provider-name ltprovider_namegt


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

下表总结了一些可执行的自定义

用户池流操作描述

定义身份验证质询确定自定义身份验证流中的下一个挑战

创建身份验证质询在自定义身份验证流中创建挑战

自定义身份验证流程

验证身份验证质询响应确定响应在自定义身份验证流中是正确的

the section called ldquo身份验证前Lambda 器rdquo (p 75)

自定义验证以接受或拒绝登录请求

the section called ldquo身份验证后触Lambda 器rdquo (p 78)

自定义分析的事件日志记录

身份验证事件

the section called ldquo令牌生成前Lambda 器rdquo (p 90)

补充或禁止令牌申请

the section called ldquo注册后Lambda 器rdquo (p 67)

自定义验证以接受或拒绝注册请求

the section called ldquo确认 Lambda器rdquo (p 72)

为自定义分析自定义欢迎消息或事件日志记录

注册

the section called ldquo迁移用户Lambda 触发器rdquo (p 93)

将用户从现有用户目录迁移到用户池

消息 the section called ldquo自定义消息Lambda 触发器rdquo (p 96)

消息的高级自定义和本地化

令牌创建 the section called ldquo令牌生成前Lambda 器rdquo (p 90)

添加或删除 Id 令牌中的属性

Email 和 SMS 第三方提供商 the section called ldquo自定义发件人Lambda 触发器rdquo (p 101)

使用第三方提供商发送 SMS 和电子邮件

63

Amazon Cognito 开发人员指南重要注意事项

主题bull 重要注意事项 (p 64)bull 添加用户池 Lambda 触发器 (p 64)bull 用户池 Lambda 触发器事件 (p 64)bull 用户池 Lambda 触发器通用参数 (p 65)bull 用户池 Lambda 触发器源 (p 66)bull 注册后 Lambda 器 (p 67)bull 确认 Lambda 器 (p 72)bull 身份验证前 Lambda 器 (p 75)bull 身份验证后触 Lambda 器 (p 78)bull 自定义身份验证质询 Lambda 触发器 (p 81)bull 令牌生成前 Lambda 器 (p 90)bull 迁移用户 Lambda 触发器 (p 93)bull 自定义消息 Lambda 触发器 (p 96)bull 自定义发件人 Lambda 触发器 (p 101)

重要注意事项在开始处理 Lambda 函数之前请务必考虑以下信息

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

bull 如果您删除某个 Amazon Lambda 触发器则必须更新用户池中的相应触发器例如如果您删除身份验证后触发器则必须在相应用户池中将身份验证后触发器设置为无

bull 除自定义发件人 Lambda 触发器外如果您的最终用户使用 Amazon Cognito 托管 UI 作为回调 URL 中的查询参数Lambda 触发器抛出的错误将直接对他们可见作为建议的最佳实践应从 Lambda 触发器中抛出面向最终用户的错误并且所有敏感或调试信息都应记录在 Lambda 触发器中

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

1 创建 Lambda 函数使用Lambda 控制台有关 Lambda 函数的更多信息请参阅Amazon Lambda开发人员指南

2 导航到Amazon Cognito 控制台中选择管理用户池3 从列表中选择现有用户池或创建用户池4 在您的用户池中从导航栏中选择触发器选项卡5 选择一个 Lambda 触发器如注册前或者身份验证前然后从Lambda 函数下拉列表中)6 选择保存更改7 您可以使用 Lambda 控制台中的 CloudWatch 记录您的 Lambda 函数有关更多信息请参阅访问

Lambda 的 CloudWatch Logs

用户池 Lambda 触发器事件Amazon Cognito 将事件信息传递到您的 Lambda 函数该函数将同一事件对象连同响应中的任何更改返回到 Amazon Cognito此事件显示了 Lambda 触发器通用参数

64

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 触发器通用参数版本

您的 Lambda 函数的版本号triggerSource

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

区域

Amazon 区域作为 AWSRegion 实例userPoolId

用户池的用户池 IDuserName

当前用户的用户名callerContext

调用方上下文由以下内容组成awsSdkVersion

Amazon 开发工具包版本号clientId

与用户池关联的客户端的 ID请求

来自 Amazon Cognito 服务的请求此请求必须包括userAttributes

一个或多个用户属性名称值对每个配对的形式均为资资资

65

Amazon Cognito 开发人员指南Lambda 触发器源

响应

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

用户池 Lambda 触发器源本节介绍每个 Amazon Cognito Lambda triggerSource 参数及其触发事件

注册确认和登录 (身份验证) 触发器

Trigger (触发器) triggerSource 值触发事件

注册前 PreSignUp_SignUp 注册前

注册前 PreSignUp_AdminCreateUser 在管理员创建新用户时做好注册准备

注册前 PreSignUp_ExternalProvider 注册前提供方


确认后 PostConfirmation_ConfirmSignUp注册后确认

确认后 PostConfirmation_ConfirmForgotPassword忘记密码后确认

身份验证前 PreAuthentication_Authentication身份验证前

身份验证后 PostAuthentication_Authentication身份验证后

自定义身份验证质询触发器


定义身份验证质询 DefineAuthChallenge_Authentication定义身份验证质询

创建身份验证质询 CreateAuthChallenge_Authentication创建身份验证质询

验证身份验证质询 VerifyAuthChallengeResponse_Authentication验证身份验证质询响应

令牌生成前触发器


令牌生成前 TokenGeneration_HostedAuth 通过 Amazon Cognito 托管 UI 登录页进行身份验证时调用

令牌生成前 TokenGeneration_Authentication用户身份验证流完成之后调用

令牌生成前 TokenGeneration_NewPasswordChallenge管理员创建用户之后调用当用户必须更改临时密码时调用此流

令牌生成前 TokenGeneration_AuthenticateDevice用户设备身份验证结束时调用

令牌生成前 TokenGeneration_RefreshTokens用户尝试刷新身份和令牌时调用

66

Amazon Cognito 开发人员指南注册后 Lambda 器

迁移用户触发器


用户迁移 UserMigration_Authentication用户登录时进行迁移

用户迁移 UserMigration_ForgotPassword忘记密码流程中的用户迁移

自定义消息触发器


自定义消息 CustomMessage_SignUp 自定义消息 ndash 在注册后发送确认代码

自定义消息 CustomMessage_AdminCreateUser自定义消息 ndash 向新用户发送临时密码

自定义消息 CustomMessage_ResendCode 自定义消息 ndash 向现有用户重新发送确认代码

自定义消息 CustomMessage_ForgotPassword自定义消息 ndash 针对ldquo忘记密码rdquo请求发送确认代码

自定义消息 CustomMessage_UpdateUserAttribute自定义消息 ndash 当用户的电子邮件或电话号码发生更改时此触发器自动向用户发送验证码不可用于其他属性

自定义消息 CustomMessage_VerifyUserAttribute自定义消息 ndash 当用户针对新的电子邮件或电话号码手动请求验证码时此触发器向用户发送验证码

自定义消息 CustomMessage_Authentication自定义消息 ndash 在身份验证过程中发送 MFA 代码

注册后 Lambda 器注册前 Lambda 函数在 Amazon Cognito 注册新用户之前触发它允许您执行自定义验证以在注册过程中接受或拒绝注册请求

主题bull 注册后 Lambda 流程 (p 68)bull 注册前触 Lambda 参数 (p 68)bull 注册教程 (p 69)bull 注册前示例自动确认注册的域中的用户 (p 70)bull 注册前示例自动确认和自动验证所有用户 (p 71)

67


注册后 Lambda 流程客户端注册流程

服务器注册流程

该请求包含客户端中的数据来自传递到用户池 SignUp 和 AdminCreateUser API 方法的ValidationData 值

注册前触 Lambda 参数这些是此 Lambda 函数所需的参数除了常见参数

JSON

request userAttributes string string validationData string string clientMetadata string string

response autoConfirmUser boolean autoVerifyPhone boolean autoVerifyEmail boolean

68


注册前请求参数

userAttributes

表示用户属性的一个或多个名称值对属性名称是键validationData

在用户注册请求中包含验证数据的一个或多个名称值对设置验证数据然后在用户注册请求中从客户端传递您 Lambda 以 ClientMetadata 用InitiateAuth和AdminInitiateAuthAPI 操作

clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给函数该函数是为注册前触发器指定的您可以使用以下 API 操作中的 ClientMetadata 参数将此数据传递给 Lambda 函数AdminCreateUserAdminRespondToAuthChallengeForgotPassword 和SignUp

注册前响应参数在响应中如果您想要自动确认用户则您可以将 autoConfirmUser 设置为 true您可以将autoVerifyEmail 设置为 true以自动验证用户的电子邮件您可以将 autoVerifyPhone 设置为true以自动验证用户的电话号码

Note

响应参数autoVerifyPhoneautoVerifyEmail和autoConfirmUser会被 Amazon Cognito忽略当预注册 lambda 由AdminCreateUserAPI

autoConfirmUser

设置为 true 以自动确认用户否则设置为 falseautoVerifyEmail

设置为 true 可以设置为所注册用户已通过验证的电子邮件否则为 false如果 autoVerifyEmail设置为 true则 email 属性必须具有有效的非空值否则将出现错误用户将无法完成注册

如果选择 email 属性作为别名则在设置了 autoVerifyEmail 时将为用户的电子邮件创建别名如果已存在具有该电子邮件的别名则别名将移动到新用户以前用户的电子邮件将标记为未验证有关更多信息请参阅别名概述 (p 155)

autoVerifyPhone

设置为 true 可以设置为所注册用户已通过验证的电话号码否则为 false如果 autoVerifyPhone设置为 true则 phone_number 属性必须具有有效的非空值否则将出现错误用户将无法完成注册

如果选择 phone_number 属性作为别名则在设置了 autoVerifyPhone 时将为用户的电话号码创建别名如果已存在具有该电话号码的别名则别名将移动到新用户以前用户的电话号码将标记为未验证有关更多信息请参阅别名概述 (p 155)

注册教程注册前 Lambda 函数在用户注册前触发请参阅这些适用于 JavaScriptAndroid 和 iOS 的 AmazonCognito 注册教程

平台教程

JavaScript 身份开发工具包通过 JavaScript 注册用户

Android 身份开发工具包通过 Android 注册用户

69


平台教程

iOS 身份开发工具包通过 iOS 注册用户

注册前示例自动确认注册的域中的用户使用注册前 Lambda 触发器可以添加自定义逻辑来验证注册用户池的新用户以下是示例 JavaScript 程序演示如何注册新用户它将在身份验证过程中调用注册前 Lambda 触发器

JavaScript

var attributeList = []var dataEmail = Name email Value your email herevar dataPhoneNumber = Name phone_number Value your phone number here with +country code and no delimiters in front

var dataEmailDomain = Name customdomain Value examplecomvar attributeEmail = new AmazonCognitoIdentityCognitoUserAttribute(dataEmail)var attributePhoneNumber = new AmazonCognitoIdentityCognitoUserAttribute(dataPhoneNumber)var attributeEmailDomain = new AmazonCognitoIdentityCognitoUserAttribute(dataEmailDomain) attributeListpush(attributeEmail)attributeListpush(attributePhoneNumber)attributeListpush(attributeEmailDomain) var cognitoUseruserPoolsignUp(username password attributeList null function(err result) if (err) alert(err) return cognitoUser = resultuser consolelog(user name is + cognitoUsergetUsername()))

这是一个示例 Lambda 触发器在使用用户池注册前 Lambda 触发器注册前调用它使用自定义属性customdomain 自动确认来自特定电子邮件域的新用户任何不在自定义域中的新用户都将添加到用户池但不会自动确认

Nodejs

exportshandler = (event context callback) =gt Set the user pool autoConfirmUser flag after validating the email domain eventresponseautoConfirmUser = false

Split the email address so we can compare domains var address = eventrequestuserAttributesemailsplit()

70


This example uses a custom attribute customdomain if (eventrequestuserAttributeshasOwnProperty(customdomain)) if ( eventrequestuserAttributes[customdomain] === address[1]) eventresponseautoConfirmUser = true

Return to Amazon Cognito callback(null event)

Python

def lambda_handler(event context) It sets the user pool autoConfirmUser flag after validating the email domain event[response][autoConfirmUser] = False

Split the email address so we can compare domains address = event[request][userAttributes][email]split()

This example uses a custom attribute customdomain if customdomain in event[request][userAttributes] if event[request][userAttributes][customdomain] == address[1] event[response][autoConfirmUser] = True

Return to Amazon Cognito return event

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

JSON

request userAttributes email testuserexamplecom customdomain examplecom response

注册前示例自动确认和自动验证所有用户此示例确认所有用户并将用户的 email 和 phone_number 属性设置为ldquo已验证rdquo(如果该属性存在)此外如果启用了别名当设置了自动验证时将为 phone_number 和 email 创建别名

Note

如果已存在具有相同电话号码的别名则别名将移动到新用户以前用户的 phone_number 将标记为未验证电子邮件地址也是如此要防止出现这种情况可以使用用户池 ListUsers API 查看现有用户是否已在使用新用户的电话号码或电子邮件地址作为别名

Nodejs

exportshandler = (event context callback) =gt

71

Amazon Cognito 开发人员指南确认 Lambda 器

Confirm the user eventresponseautoConfirmUser = true

Set the email as verified if it is in the request if (eventrequestuserAttributeshasOwnProperty(email)) eventresponseautoVerifyEmail = true

Set the phone number as verified if it is in the request if (eventrequestuserAttributeshasOwnProperty(phone_number)) eventresponseautoVerifyPhone = true


Python

def lambda_handler(event context) Confirm the user event[response][autoConfirmUser] = True

Set the email as verified if it is in the request if email in event[request][userAttributes] event[response][autoVerifyEmail] = True

Set the phone number as verified if it is in the request if phone_number in event[request][userAttributes] event[response][autoVerifyPhone] = True



JSON

request userAttributes email userexamplecom phone_number +12065550100 response

确认 Lambda 器Amazon Cognito 在确认新用户后调用此触发器让您能够发送自定义消息或添加自定义逻辑例如您可以使用此触发器来收集新的用户数据

请求包含已确认用户的当前属性

主题bull 确认后 Lambda 流程 (p 73)

72


bull 确认后触 Lambda 器参数 (p 73)bull 用户确认教程 (p 74)bull 确认后示例 (p 74)

确认后 Lambda 流程客户端确认注册流程

服务器确认注册流程

确认忘记密码流程

确认后触 Lambda 器参数这些是此 Lambda 函数所需的参数除了常见参数

JSON

request userAttributes string string

73


clientMetadata string string response

确认后请求参数

userAttributes

一个或多个密钥表示用户属性的值对clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 数该函数是为确认后触发器指定的您可以使用以下 API 操作中的 ClientMetadata 参数将此数据传递给 Lambda 函数AdminConfirmSignUpConfirmForgotPasswordConfirmSignUp 和SignUp

确认后响应参数预计响应中没有其他返回信息

用户确认教程确认后 Lambda 函数在 Amazon Cognito 确认新用户后触发请参阅这些适用于 JavaScriptAndroid 和iOS 的用户确认教程

平台教程

JavaScript 身份开发工具包通过 JavaScript 确认用户

Android 身份开发工具包通过 Android 确认用户

iOS 身份开发工具包通过 iOS 确认用户

确认后示例此示例 Lambda 函数将使用 Amazon SES 向用户发送确认电子邮件有关更多信息请参阅AmazonSimple Email Service 开发人员指南

Nodejs

var aws = require(aws-sdk)

var ses = new awsSES()

exportshandler = (event context callback) =gt consolelog(event)

if (eventrequestuserAttributesemail) sendEmail(eventrequestuserAttributesemail Congratulations + eventuserName + you have been confirmed function(status)

74

Amazon Cognito 开发人员指南身份验证前 Lambda 器

Return to Amazon Cognito callback(null event) ) else Nothing to do the users email ID is unknown callback(null event)

function sendEmail(to body completedCallback) var eParams = Destination ToAddresses [to] Message Body Text Data body Subject Data Cognito Identity Provider registration completed

Replace source_email with your SES validated email address Source ltsource_emailgt

var email = sessendEmail(eParams function(err data) if (err) consolelog(err) else consolelog(===EMAIL SENT===) completedCallback(Email sent) ) consolelog(EMAIL CODE END)


JSON

request userAttributes email userexamplecom email_verified true response

身份验证前 Lambda 器当用户尝试登录时Amazon Cognito 会调用此触发器让自定义验证能够接受或拒绝身份验证请求

75


Note

触发器取决于激活触发器之前用户池中的现有用户

主题bull 身份验证前 Lambda 流程 (p 76)bull 身份验证前 Lambda 器参数 (p 76)bull 身份验证教程 (p 77)bull 身份验证前示例 (p 77)

身份验证前 Lambda 流程客户端身份验证流程

服务器身份验证流程

该请求包含客户端中的数据来自传递到用户池 InitiateAuth 和 AdminInitiateAuth API 方法的ClientMetadata 值

有关更多信息请参阅 User池身份验证流程 (p 285)

身份验证前 Lambda 器参数这些是此 Lambda 函数所需的参数除了常见参数

JSON


76


validationData string string userNotFound boolean response

身份验证前请求参数

userAttributes

表示用户属性的一个或多个名称值对userNotFound

当为您的用户池客户端将 PreventUserExistenceErrors 设置为 ENABLED 时将填充此布尔值validationData

在用户的登录请求中包含验证数据的一个或多个键值对您 Lambda 以 ClientMetadata用InitiateAuth和AdminInitiateAuthAPI 操作

身份验证前响应参数

预计响应中没有其他返回信息

身份验证教程身份验证前 Lambda 函数在 Amazon Cognito 登录新用户之前触发请参阅这些适用于 JavaScriptAndroid和 iOS 的登录教程

平台教程

JavaScript 身份开发工具包通过 JavaScript 登录用户

Android 身份开发工具包通过 Android 登录用户

iOS 身份开发工具包通过 iOS 登录用户

身份验证前示例此示例函数将阻止来自特定用户池应用程序客户端的用户登录用户池

Nodejs

exportshandler = (event context callback) =gt if (eventcallerContextclientId === user-pool-app-client-id-to-be-blocked) var error = new Error(Cannot authenticate users from this user pool app client)

Return error to Amazon Cognito callback(error event)

77

Amazon Cognito 开发人员指南身份验证后触 Lambda 器


Python

def lambda_handler(event context) if event[callerContext][clientId] == ltuser pool app client id to be blockedgt raise Exception(Cannot authenticate users from this user pool app client)



JSON

callerContext clientId ltuser pool app client id to be blockedgt response

身份验证后触 Lambda 器Amazon Cognito 在登录用户后调用此触发器让您能够在身份验证后添加自定义逻辑

主题bull 身份验证后 Lambda 流程 (p 78)bull 身份验证后 Lambda 器参数 (p 79)bull 身份验证教程 (p 80)bull 身份验证后示例 (p 80)

身份验证后 Lambda 流程

客户端身份验证流程

78




身份验证后 Lambda 器参数这些是此 Lambda 函数所需的参数除了常见参数

JSON

request userAttributes string string newDeviceUsed boolean clientMetadata string string response

身份验证后请求参数

newDeviceUsed

此标记指示用户是否已在新设备上登录仅在用户池的记住的设备值设置为 Always 或 User Opt-In时设置它

userAttributes

表示用户属性的一个或多个名称值对clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 数该函数是为身份验证后触发器指定的您 Lambda 以 ClientMetadata用AdminRespondToAuthChallenge和RespondToAuthChallengeAPI 操作

身份验证后响应参数


79


身份验证教程身份验证后 Lambda 函数在 Amazon Cognito 登录新用户之后触发请参阅这些适用于 JavaScriptAndroid和 iOS 的登录教程

平台教程




身份验证后示例此身份验证后示例 Lambda 函数将成功登录数据发送到 CloudWatch Logs Challenge

Nodejs


Send post authentication data to Cloudwatch logs consolelog (Authentication successful) consolelog (Trigger function = eventtriggerSource) consolelog (User pool = eventuserPoolId) consolelog (App client ID = eventcallerContextclientId) consolelog (User ID = eventuserName)


Python

from __future__ import print_functiondef lambda_handler(event context)

Send post authentication data to Cloudwatch logs print (Authentication successful) print (Trigger function = event[triggerSource]) print (User pool = event[userPoolId]) print (App client ID = event[callerContext][clientId]) print (User ID = event[userName])



JSON

triggerSource testTrigger userPoolId testPool userName testName

80

Amazon Cognito 开发人员指南质询 Lambda 触发器

callerContext clientId 12345 response

自定义身份验证质询 Lambda 触发器

作为用户池的一部分这些 Lambda 触发器将发出并验证自己的质询定制身份验证流程

定义身份验证质询

Amazon Cognito 调用此触发器以启动自定义身份验证流程创建身份验证质询

Amazon Cognito 在定义身份验证质询以创建自定义质询验证身份验证质询响应

Amazon Cognito 调用此触发器以验证最终用户对自定义质询的响应是否有效

您可以使用这些质询 Lambda 触发器引入新的质询类型例如这些质询类型可能包含 CAPTCHA 或动态质询问题

您可以使用用户池 InitiateAuth 和 RespondToAuthChallenge API 方法将身份验证泛化为两个常见步骤

在此流程中用户通过回答连续的质询进行身份验证直到身份验证失败或用户获得令牌这两个 API 调用可重复执行以包含不同的质询

81


Note


主题bull 定义身份验证质询 Lambda 触发器 (p 82)bull 创建身份验证质询 Lambda 触发器 (p 85)bull 验证身份验证质询响应 Lambda 触发器 (p 88)

定义身份验证质询 Lambda 触发器


Amazon Cognito 调用此触发器以启动定制身份验证流程

此 Lambda 触发器的请求包括session该数组是一个包含当前身份验证流程中向用户显示的所有质询的数组请求还包含相应的结果质询详细信息 (ChallengeResult) 按时间顺序存储在 session 数组中其中 session[0] 表示向用户显示的第一个质询

您可以让 Amazon Cognito 在提出自定义质询之前验证用户密码过程概述

1 要开始请让您的应用启动登录方法是调用InitiateAuth或者AdminInitiateAuth与AuthParameters映射包括CHALLENGE_NAMESRP_A和SRP_A和USERNAME

2 您的定义身份验证质询 Lambda 触发器将与包含challengeName SRP_A和challengeResulttrue

82


3 在收到这些输入后您的 Lambda 函数响应challengeNamePASSWORD_VERIFIERissueTokens falsefailAuthentication false

4 如果密码验证成功您的 Lambda 函数将再次调用一个包含challengeNamePASSWORD_VERIFIER和challengeResult true

5 您的 Lambda 函数通过响应challengeName CUSTOM_CHALLENGEissueTokens false和failAuthentication false如果您不想通过密码验证启动自定义身份验证流程则可以使用AuthParametersMap 包括CHALLENGE_NAME CUSTOM_CHALLENGE

6 质询循环将一直重复到所有质询得到回答

主题bull 定义身份验证质询 Lambda 触发器参数 (p 83)bull 定义身份验证质询示例 (p 84)

定义身份验证质询 Lambda 触发器参数

这些是此 Lambda 函数所需的参数除了常见参数

JSON

request userAttributes string string session [ ChallengeResult ] clientMetadata string string userNotFound boolean response challengeName string issueTokens boolean failAuthentication boolean

定义身份验证质询请求参数

这些是调用 Lambda 函数时提供给 Lambda 函数的参数

userAttributes


当为您的用户池客户端将 PreventUserExistenceErrors 设置为 ENABLED 时将填充的一个布尔值值 true 表示用户 ID（用户名电子邮件地址等）不匹配任何现有用户如果PreventUserExistenceErrors 设置为 ENABLED则服务将不会向应用程序报告用户不存在建议的最佳做法是让您的 Lambda 函数保持相同的用户体验包括延迟以便调用者无法检测到用户存在或不存在时的不同行为

83


session

一个 ChallengeResult 元素数组每个元素都包含以下元素challengeName

质询类型以下值之一CUSTOM_CHALLENGESRP_APASSWORD_VERIFIERSMS_MFADEVICE_SRP_AUTHDEVICE_PASSWORD_VERIFIER 或 ADMIN_NO_SRP_AUTH

Important

您应该始终查看challengeName在您的DefineAuthChallengeLambda 触发器以确保它与预期值匹配当用户是否已成功通过身份验证以及是否应颁发令牌时

challengeResult

如果用户成功完成质询则设置为 true否则设置为 falsechallengeMetadata

自定义质询的名称仅当 challengeName 为 CUSTOM_CHALLENGE 时使用clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 函数该函数是为定义身份验证质询触发器指定的您可以使用ClientMetadata中的参数AdminRespondToAuthChallenge和RespondToAuthChallengeAPI 操作

定义身份验证质询响应参数

在响应中您可以返回身份验证流程的下一阶段

challengeName

一个包含下一质询的名称的字符串如果您希望向您的用户显示新的质询请在此处指定质询名称issueTokens

如果您确定用户已通过完成相关质询而进行了充分的身份验证则设置为 true否则设置为 falsefailAuthentication

如果您想要终止当前的身份验证流程则设置为 true否则设置为 false

定义身份验证质询示例此示例针对身份验证定义一系列质询并发布质询令牌 (仅在成功完成所有质询后)

Nodejs

exportshandler = (event context callback) =gt if (eventrequestsessionlength == 1 ampamp eventrequestsession[0]challengeName == SRP_A) eventresponseissueTokens = false eventresponsefailAuthentication = false eventresponsechallengeName = PASSWORD_VERIFIER else if (eventrequestsessionlength == 2 ampamp eventrequestsession[1]challengeName == PASSWORD_VERIFIER ampamp eventrequestsession[1]challengeResult == true) eventresponseissueTokens = false eventresponsefailAuthentication = false eventresponsechallengeName = CUSTOM_CHALLENGE else if (eventrequestsessionlength == 3 ampamp eventrequestsession[2]challengeName == CUSTOM_CHALLENGE ampamp eventrequestsession[2]challengeResult == true)

84


eventresponseissueTokens = true eventresponsefailAuthentication = false else eventresponseissueTokens = false eventresponsefailAuthentication = true


创建身份验证质询 Lambda 触发器

创建身份验证质询

Amazon Cognito 在定义身份验证质询如果自定义质询已被指定为定义身份验证质询触发器它将创建一个自定义身份验证流程

调用此 Lambda 触发器来创建要向用户显示的质询此 Lambda 触发器的请求包括challengeName和sessionchallengeName 是一个字符串是向用户显示的下一质询的名称此属性的值在 ldquo定义身份验证质询 Lambdardquo 触发器中设置

质询循环将一直重复到所有质询得到回答

主题bull 创建身份验证质询 Lambda 触发器参数 (p 86)bull 创建身份验证质询示例 (p 87)

85


创建身份验证质询 Lambda 触发器参数


JSON

request userAttributes string string challengeName string session [ ChallengeResult ] clientMetadata string string userNotFound boolean response publicChallengeParameters string string privateChallengeParameters string string challengeMetadata string

创建身份验证质询请求参数

userAttributes


当为您的用户池客户端将 PreventUserExistenceErrors 设置为 ENABLED 时将填充此布尔值challengeName

新质询的名称session

会话元素是一组 ChallengeResult 元素其中每个元素包含以下元素challengeName

质询类型以下值之一CUSTOM_CHALLENGEPASSWORD_VERIFIERSMS_MFADEVICE_SRP_AUTHDEVICE_PASSWORD_VERIFIER或 ADMIN_NO_SRP_AUTH

challengeResult

如果用户成功完成质询则设置为 true否则设置为 false

86


challengeMetadata


一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 函数该函数是为创建身份验证质询触发器指定的您 Lambda 以 ClientMetadata用AdminRespondToAuthChallenge和RespondToAuthChallengeAPI 操作

创建身份验证质询响应参数

publicChallengeParameters

客户端应用程序要在向用户显示的质询中使用的一个或多个键值对此参数应包含所有必要信息以向用户准确显示质询

privateChallengeParameters

此参数仅由 ldquo验证身份验证质询响应rdquo Lambda 触发器使用此参数应包含所需的所有信息以验证用户对质询的响应也就是说publicChallengeParameters 参数包含向用户显示的问题privateChallengeParameters 包含问题的有效答案

challengeMetadata

自定义质询的名称 (如果是自定义质询)

创建身份验证质询示例

CAPTCHA 作为针对用户的质询而创建CAPTCHA 图像的 URL 作为 captchaUrl 添加到公有质询参数中并且预期答案添加到私有质询参数中

Nodejs

exportshandler = (event context callback) =gt if (eventrequestchallengeName == CUSTOM_CHALLENGE) eventresponsepublicChallengeParameters = eventresponsepublicChallengeParameterscaptchaUrl = url123jpg eventresponseprivateChallengeParameters = eventresponseprivateChallengeParametersanswer = 5 eventresponsechallengeMetadata = CAPTCHA_CHALLENGE


87


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

验证身份验证质询响应

Amazon Cognito 调用此触发器以验证最终用户对自定义身份验证质询的响应是否有效它是用户池自定义身份验证流程的一部分

此触发器的请求包括 privateChallengeParameters 和 challengeAnswer 参数这些区域有privateChallengeParameters值由 ldquo创建身份验证质询质询rdquo Lambda 触发器返回并将包含用户的预期响应challengeAnswer 参数包含用户对质询的响应

响应包含 answerCorrect 属性如果用户成功完成质询则该属性设置为 true否则设置为 false


主题bull 验证身份验证质询 Lambda 触发器参数 (p 88)bull 验证身份验证质询响应示例 (p 89)

验证身份验证质询 Lambda 触发器参数


JSON

request

88


userAttributes string string privateChallengeParameters string string challengeAnswer string string clientMetadata string string userNotFound boolean response answerCorrect boolean

验证身份验证质询请求参数

userAttributes


当为您的用户池客户端将 PreventUserExistenceErrors 设置为 ENABLED 时将填充此布尔值privateChallengeParameters

此参数来自ldquo创建身份验证质询rdquo触发器它将与用户的 challengeAnswer 进行对比以确定用户是否通过了质询

此参数仅由 ldquo验证身份验证质询响应rdquo Lambda 触发器使用它应包含验证用户对质询的响应所需的一切信息这包括 publicChallengeParameters 参数 (包含向用户显示的问题) 和privateChallengeParameters (包含问题的有效答案)

challengeAnswer

来自用户对质询的响应的答案clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 函数该函数是为验证身份验证质询触发器指定的您 Lambda 以 ClientMetadata用AdminRespondToAuthChallenge和RespondToAuthChallengeAPI 操作

验证身份验证质询响应参数

answerCorrect

如果用户已成功完成质询则设置为 true否则设置为 false

验证身份验证质询响应示例在本示例中Lambda 函数检查用户对质询的响应是否与预期响应一致如果用户的响应与预期响应一致则 answerCorrect 参数设置为 true

89

Amazon Cognito 开发人员指南令牌生成前 Lambda 器

Nodejs

exportshandler = (event context callback) =gt if (eventrequestprivateChallengeParametersanswer == eventrequestchallengeAnswer) eventresponseanswerCorrect = true else eventresponseanswerCorrect = false


令牌生成前 Lambda 器Amazon Cognito 在令牌生成之前调用此触发器让您能够自定义身份令牌声明

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

有一些无法修改的声明其中包括acramraudauth_timeazpexpiatidentitiesisssubtoken_usenonceat_hash和 cognitousername

主题bull 令牌生成前 Lambda 器源 (p 90)bull 令牌生成前触 Lambda 器参数 (p 90)bull 令牌生成前示例添加新声明并禁止现有声明 (p 92)bull 令牌生成前示例修改用户的组成员资格 (p 92)

令牌生成前 Lambda 器源

triggerSource 值触发事件

TokenGeneration_HostedAuth 通过 Amazon Cognito 托管 UI 登录页进行身份验证时调用

TokenGeneration_Authentication 用户身份验证流完成之后调用

TokenGeneration_NewPasswordChallenge 管理员创建用户之后调用当用户必须更改临时密码时调用此流

TokenGeneration_AuthenticateDevice 用户设备身份验证结束时调用

TokenGeneration_RefreshTokens 用户尝试刷新身份和令牌时调用

令牌生成前触 Lambda 器参数这些是此 Lambda 函数所需的参数除了常见参数

90


JSON

request userAttributes string string groupConfiguration groupsToOverride [string ] iamRolesToOverride [string ] preferredRole string clientMetadata string string response claimsOverrideDetails claimsToAddOrOverride string string claimsToSuppress [string ]

groupOverrideDetails groupsToOverride [string ] iamRolesToOverride [string ] preferredRole string

令牌生成前请求参数

groupConfiguration

包含当前组配置的输入对象包括 groupsToOverrideiamRolesToOverride 和preferredRole

groupsToOverride

与为其发放身份令牌的用户相关联的组名称的列表iamRolesToOverride

与这些组相关联的当前 IAM 角色的列表preferredRole

用于指示首选 IAM 角色的字符串clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 函数该函数是为令牌生成前触发器指定的您 Lambda 以 ClientMetadata用AdminRespondToAuthChallenge和RespondToAuthChallengeAPI 操作

91


令牌生成前响应参数

claimsToAddOrOverride

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

claimsToSuppress

包含要从身份令牌中隐藏的声明的列表Note

如果某个值既要被隐藏又要被替换则它将被隐藏groupOverrideDetails

包含当前组配置的输出对象包括 groupsToOverrideiamRolesToOverride 和preferredRole

groupOverrideDetails 对象已替换为您提供的如果在响应中提供空或空对象则组将被隐藏要保持现有组配置不变请在响应中将请求的 groupConfiguration 对象的值复制到 groupOverrideDetails 对象并将其传回给服务

令牌生成前示例添加新声明并禁止现有声明此示例使用令牌生成前 Lambda 来添加新声明和隐藏现有声明

Nodejs

exportshandler = (event context callback) =gt eventresponse = claimsOverrideDetails claimsToAddOrOverride attribute_key2 attribute_value2 attribute_key attribute_value claimsToSuppress [email]



JSON

request response

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

92

Amazon Cognito 开发人员指南迁移用户 Lambda 触发器

Nodejs

exportshandler = (event context callback) =gt eventresponse = claimsOverrideDetails claimsToAddOrOverride attribute_key2 attribute_value2 attribute_key attribute_value claimsToSuppress [email] groupOverrideDetails groupsToOverride [group-A group-B group-C] iamRolesToOverride [arnawsiamXXXXXXXXXXXXrolesns_callerA arnawsiamXXXXXXXXXrolesns_callerB arnawsiamXXXXXXXXXXrolesns_callerC] preferredRole arnawsiamXXXXXXXXXXXrolesns_caller



JSON

request response

迁移用户 Lambda 触发器如果用户在使用密码登录时或在使用忘记密码流程时未在用户池中Amazon Cognito 会调用此触发器Lambda 函数成功返回后Amazon Cognito 将在用户池中创建用户有关利用用户迁移 Lambda 触发器进行身份验证流程的详细信息请参阅利用用户迁移 Lambda 触发器将用户导入用户池 (p 124)

您可以使用此 Lambda 触发器在用户登录时或在忘记密码流程中将他们从现有用户目录迁移到Amazon Cognito 用户池

主题bull 迁移用户 Lambda 触发器源 (p 93)bull 迁移用户 Lambda 触发器参数 (p 94)bull 例如迁移已有密码的用户 (p 95)

迁移用户 Lambda 触发器源


UserMigration_Authentication 用户登录时进行迁移

93



UserMigration_ForgotPassword 在忘记密码流程中迁移用户

迁移用户 Lambda 触发器参数这些是此 Lambda 函数所需的参数除了常见参数

JSON

userName string request password string validationData string string clientMetadata string string response userAttributes string string finalUserStatus string messageAction string desiredDeliveryMediums [ string ] forceAliasCreation boolean

迁移用户请求参数

userName

用户输入的用户名密码

由用户输入的登录密码不是在忘记密码流程中设置的密码validationData


clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 数该函数是为迁移用户触发器指定的您 Lambda 以 ClientMetadata 用AdminRespondToAuthChallenge和ForgotPasswordAPI 操作

迁移用户响应参数

userAttributes

此字段为必填

94


它必须包含一个或多个名称-值对表示要存储在用户池中的用户配置文件内的用户属性您可以同时包括标准的和自定义的用户属性自定义属性需要使用 custom 前缀以便与标准属性区分开来有关更多信息请参阅自定义属性

Note

为了便于用户在忘记密码流程中重置密码用户必须拥有经过验证的电子邮件或经过验证的电话号码Amazon Cognito 将包含重置密码代码的消息发送到用户属性中的电子邮件或电话号码

Attributes 要求

创建用户池时标记为必需的所有属性

如果迁移过程中缺少任何必需的属性将使用默认值

username 如果您已使用电子邮件和或 preferred_username 别名配置用户池 (登录用户名除外)而用户输入电子邮件或电话号码进行登录此属性必需

否则将用作可选用户名替代用户输入的用户名

Note

在用户池中用户名必须是唯一的

finalUserStatus

在登录期间此属性可设置为 CONFIRMED 或不设置以自动确认您的用户并允许他们使用原来的密码登录对于用户而言这是最简单的体验

如果此属性设置为 RESET_REQUIRED用户必须在迁移后 (即登录时) 立即更改密码而您的客户端应用程序需要在身份验证流程期间处理 PasswordResetRequiredException

Note

在使用 Lambda 触发器进行迁移期间不会强制执行为用户池配置的密码强度策略如果密码不符合配置的密码策略则仍会接受该密码以允许用户继续迁移要强制执行密码强度策略并拒绝不符合策略的密码请验证代码中的密码强度然后如果密码不符合策略则将 ldquo最终用户状态rdquo 设置为 ldquo必需rdquo

messageAction

此属性可设置为 ldquoSUp以隐藏通常由 Amazon Cognito 发送给新用户的欢迎消息如果未返回此属性将不发送欢迎消息

desiredDeliveryMediums

此属性设置为 EMAIL 可通过电子邮件发送欢迎消息设置为 SMS 可通过 SMS 发送欢迎消息如果未返回此属性将通过 SMS 发送欢迎消息

forceAliasCreation

如果该参数设置为 true并且在 UserAttributes 参数中指定的电话号码或电子邮件地址已作为其他用户的别名存在则 API 调用会将该别名从以前的用户迁移到新创建的用户以前的用户将无法再使用该别名登录

如果此属性设置为 false 且别名存在将不会迁移用户并且一个错误将返回客户端应用程序

如果未返回此属性则认为是 false

例如迁移已有密码的用户此示例 Lambda 函数将使用现有密码迁移用户并隐藏 Amazon Cognito 发送的欢迎消息

95

Amazon Cognito 开发人员指南自定义消息 Lambda 触发器

Nodejs


var user

if ( eventtriggerSource == UserMigration_Authentication )

authenticate the user with your existing user directory service user = authenticateUser(eventuserName eventrequestpassword) if ( user ) eventresponseuserAttributes = email useremailAddress email_verified true eventresponsefinalUserStatus = CONFIRMED eventresponsemessageAction = SUPPRESS contextsucceed(event) else Return error to Amazon Cognito callback(Bad password) else if ( eventtriggerSource == UserMigration_ForgotPassword )

Lookup the user in your existing user directory service user = lookupUser(eventuserName) if ( user ) eventresponseuserAttributes = email useremailAddress required to enable password-reset code to be sent to user email_verified true eventresponsemessageAction = SUPPRESS contextsucceed(event) else Return error to Amazon Cognito callback(Bad password) else Return error to Amazon Cognito callback(Bad triggerSource + eventtriggerSource)

自定义消息 Lambda 触发器Amazon Cognito 在发送电子邮件或电话验证消息或多重验证 (MFA) 代码前调用此触发器让您能够动态自定义消息您可以在消息自定义rdquo 选项卡Amazon Cognito 控制台

请求包含 codeParameter这是一个字符串用作发送给用户的代码的占位符将 codeParameter 字符串插入消息正文中您要插入验证码的位置收到此回复后Amazon Cognito 服务将取代codeParameter字符串与实际验证码

Note

自定义消息 Lambda 函数与CustomMessage_AdminCreateUser触发器将返回用户名和验证码所以请求必须包含requestusernameParameter和requestcodeParameter

96


主题bull 自定义消息 Lambda 触发器源 (p 97)bull 自定义消息 Lambda 触发器参数 (p 97)bull 注册自定义消息示例 (p 98)bull 管理员创建用户的自定义消息示例 (p 99)

自定义消息 Lambda 触发器源


CustomMessage_SignUp 自定义消息 ndash 在注册后发送确认代码

CustomMessage_AdminCreateUser 自定义消息 ndash 向新用户发送临时密码

CustomMessage_ResendCode 自定义消息 ndash 向现有用户重新发送确认代码

CustomMessage_ForgotPassword 自定义消息 ndash 针对ldquo忘记密码rdquo请求发送确认代码

CustomMessage_UpdateUserAttribute 自定义消息 ndash 当用户的电子邮件或电话号码发生更改时此触发器自动向用户发送验证码不可用于其他属性

CustomMessage_VerifyUserAttribute 自定义消息 ndash 当用户针对新的电子邮件或电话号码手动请求验证码时此触发器向用户发送验证码

CustomMessage_Authentication 自定义消息 ndash 在身份验证过程中发送 MFA 代码

自定义消息 Lambda 触发器参数这些是此 Lambda 函数所需的参数除了常见参数

JSON

request userAttributes string string codeParameter 资资资资 usernameParameter string clientMetadata string string response smsMessage string emailMessage string emailSubject string

97


自定义消息请求参数

userAttributes

表示用户属性的一个或多个名称值对codeParameter

一个字符串用作自定义消息中验证码的占位符username参数

用户名参数这是管理员创建用户流程的必要请求参数clientMetadata

一个或多个键值对您可以将其作为自定义输入内容提供给 Lambda 数该函数是为自定义消息触发器指定的您可以使用以下 API 操作中的 ClientMetadata 参数将此数据传递给 Lambda 函数bull AdminResetUserPasswordbull AdminRespondToAuthChallengebull AdminUpdateUserAttributesbull ForgotPasswordbull GetUserAttributeVerificationCodebull ResendConfirmationCodebull SignUpbull UpdateUserAttributes

自定义消息响应参数在响应中您指定要在发送给用户的消息中使用的自定义文本

smsMessage

要发送给用户的自定义 SMS 消息必须包含请求中收到的 codeParameter 值emailMessage

要发送给用户的自定义电子邮件必须包含请求中收到的 codeParameter 值如果 EmailSendingAccount 不是开发者并且返回 EmailMessage 消息则 400 错误代码comamazonawscognitoidentityidpmodelInvalidLambdaResponseException仅当用户池的 emailMessage SendingAccount 是 DEVELOPER 时才允许 EmailMessage

emailSubject

自定义消息的主题行如果 EmailSendingAccount 不是开发者并且返回 EmailMessage 消息则 400错误代码comamazonawscognitoidentityidpmodelInvalidLambdaResponseException仅当用户池的 EmailSendingAccount 是 DEVELOPER 时才允许 EmailSubject

注册自定义消息示例当服务要求应用程序向用户发送验证码时系统会调用此 Lambda 函数自定义电子邮件或短信

Lambda 触发器可以在多个时间点调用注册后重新发送验证码时忘记密码时或验证用户属性时响应包含电子邮件和 SMS 消息消息必须包含代码参数该参数是发送给用户的验证码的占位符

对于电子邮件消息的最大长度为 20000 个 UTF-8 字符其中包括验证代码可以在这些电子邮件中使用HTML 标签

SMS 的最大长度为 140 个 UTF-8 字符其中包括验证码

98


Nodejs

exportshandler = (event context callback) =gt if(eventuserPoolId === theSpecialUserPool) Identify why was this function invoked if(eventtriggerSource === CustomMessage_SignUp) Ensure that your message contains eventrequestcodeParameter This is the placeholder for code that will be sent eventresponsesmsMessage = Welcome to the service Your confirmation code is + eventrequestcodeParameter eventresponseemailSubject = Welcome to the service eventresponseemailMessage = Thank you for signing up + eventrequestcodeParameter + is your verification code Create custom message for other events Customize messages for other user pools



JSON

version 1 triggerSource CustomMessage_SignUpCustomMessage_ResendCodeCustomMessage_ForgotPasswordCustomMessage_VerifyUserAttribute region ltregiongt userPoolId ltuserPoolIdgt userName ltuserNamegt callerContext awsSdk ltcalling aws sdk with versiongt clientId ltapps client idgt request userAttributes phone_number_verified false email_verified true codeParameter response smsMessage ltcustom message to be sent in the message with code parametergt emailMessage ltcustom message to be sent in the message with code parametergt emailSubject ltcustom email subjectgt

管理员创建用户的自定义消息示例自定义消息 Lambda 函数与CustomMessage_AdminCreateUser触发器将返回用户名和验证码所以它将包含requestusernameParameter和requestcodeParameter在消息正文中

99


代码参数值是临时密码的占位符username 是向您的用户提供的用户名占位符

对于电子邮件消息的最大长度为 20000 个 UTF-8 字符其中包括验证代码可以在这些电子邮件中使用HTML 标签SMS 的最大长度为 140 个 UTF-8 字符其中包括验证码

响应包含电子邮件和 SMS 消息

Nodejs

exportshandler = (event context callback) =gt if(eventuserPoolId === theSpecialUserPool) Identify why was this function invoked if(eventtriggerSource === CustomMessage_AdminCreateUser) Ensure that your message contains eventrequestcodeParameter eventrequestusernameParameter This is the placeholder for the code and username that will be sent to your user eventresponsesmsMessage = Welcome to the service Your user name is + eventrequestusernameParameter + Your temporary password is + eventrequestcodeParameter eventresponseemailSubject = Welcome to the service eventresponseemailMessage = Welcome to the service Your user name is + eventrequestusernameParameter + Your temporary password is + eventrequestcodeParameter Create custom message for other events Customize messages for other user pools



JSON

version 1 triggerSource CustomMessage_AdminCreateUser region ltregiongt userPoolId ltuserPoolIdgt userName ltuserNamegt callerContext awsSdk ltcalling aws sdk with versiongt clientId ltapps client idgt request userAttributes phone_number_verified false email_verified true codeParameter usernameParameter username response smsMessage ltcustom message to be sent in the message with code parameter and username parametergt

100

Amazon Cognito 开发人员指南自定义发件人 Lambda 触发器

emailMessage ltcustom message to be sent in the message with code parameter and username parametergt emailSubject ltcustom email subjectgt

自定义发件人 Lambda 触发器Amazon Cognito 用户池提供两个 Lambda 触发器CustomEmailSender和CustomSMSSender以激活第三方电子邮件和 SMS 通知您可以使用您选择的 SMS 和电子邮件提供商从 Lambda 函数代码中向用户发送通知当需要向用户发送确认码验证码或临时密码等通知时这些会触发您配置的 Lambda 功能AmazonCognito 将代码和临时密码（秘密）发送到您触发的 Lambda 函数这些秘密使用Amazon KMS客户托管密密密钥和Amazon Encryption SDKAmazon Encryption SDK是一个客户端加密库可帮助您加密和解密通用数据

Note

您可以使用Amazon CLI或 SDK 配置用户池以使用这些 Lambda 触发器Amazon Cognito 控制台上不可用这些配置

CustomEmailSender (p 101)

Amazon Cognito 调用此触发器向用户发送电子邮件通知CustomSMSSender (p 104)

Amazon Cognito 调用此触发器向用户发送 SMS 通知

Resources以下资源可以帮助您使用CustomEmailSender和CustomSMSSender触发器

Amazon KMS

Amazon KMS是一项托管服务可让您轻松创建和控制客户主密钥 (CMK)这是用于加密数据的加密密钥有关更多信息请参阅是什么Amazon Key Management Service

客户主密钥

客户主密钥 (CMK) 是主密钥的逻辑表示CMK 包含元数据如密钥 ID创建日期描述和密钥状态CMK 还包含用于加密和解密数据的密钥材料有关更多信息请参阅客户主密钥

对称客户主密密密

对称客户主密钥表示 256 位加密密钥它永远不会离开Amazon KMS未加密要使用对称 CMK必须调用 Amazon KMS对称密钥用在对称加密中加密和解密采用的是相同的密钥有关更多信息请参阅对称客户主密钥

自定义电子邮件 Lambda 触发器这些区域有CustomEmailSender触发器以使第三方提供商能够从 Lambda 函数代码中向用户发送电子邮件通知使用此触发器涉及五个主要步骤

Note

这些区域有CustomEmailSender触发器在 Amazon Cognito 控制台中不可用

101


bull 创建 Lambda 函数CustomEmailSenderAmazon Cognito 使用Amazon Encryption SDK来加密密码（临时密码或授权码）

bull 创建加密密密密密密密密密Amazon KMS此密钥将用于加密 Amazon Cognito 生成的临时密码和授权码然后您可以在自定义发件人 Lambda 函数中解密这些密钥以纯文本形式将它们发送给最终用户

bull 授予 Amazon Cognito 服务主要人身份识别-idpamazonawscom 访问权限以调用 Lambda 函数bull 编辑 Lambda 函数中的代码以使用客户发件人或第三方提供商bull 更新现有用户池以添加自定义发件人 Lambda 触发器

Important

为了提高安全性您必须在Amazon KMS(KMS) 当CustomEmailSender或者CustomSMSSender配置了用户池Amazon Cognito 使用您配置的 KMS 密钥来加密代码或临时密码Amazon Cognito 将 base64 编码的密文发送到您的 Lambda 函数有关更多信息请参阅对称客户主密钥

启用CustomEmailSenderLambda 触发器

您可以启用CustomEmailSender使用 Lambda 函数触发器

第 1 步创建 Lambda 函数

创建 Lambda 函数CustomEmailSender触发器Amazon Cognito 使用Amazon加密 SDK来加密密码（临时密码或授权码）

第 2 步创建加密密密密密密密密密Amazon KMS

创建加密密密密密密密密密Amazon KMS此密钥将用于加密 Amazon Cognito 生成的临时密码和授权码然后您可以在自定义发件人 Lambda 函数中解密这些密钥以便能够将它们以明文形式发送给最终用户

第 3 步授予 Amazon Cognito 服务主要人身份识别-idpamazonawscom 访问权限以调用 Lambda 函数

使用以下命令

aws lambda add-permission --function-name lambda_arn --statement-id CognitoLambdaInvokeAccess --action lambdaInvokeFunction --principal cognito-idpamazonawscom

第 4 步编辑代码以使用自定义发件人

Amazon Cognito 使用Amazon Encryption SDK来加密密码（临时密码和授权码）然后再将它们发送到自定义发件人 Lambda 函数在使用您选择的自定义提供程序将这些密码发送给最终用户之前您需要对其进行解密使用Amazon Encryption SDK与您的 Lambda 函数一起使用则需要将 SDK 与您的函数打包想要了解有关信息请参阅安装Amazon适用于 JavaScript 的加密开发工具包您也可以通过完成以下步骤来更新 Lambda 软件包

1 从控制台导出 Lambda 函数包2 解压缩程序包3 添加Amazon Encryption SDK添加到程序包例如如果您使用的是 Nodejs则添加node_modules目

录并包含来自 aws-密码客户端节点的库4 重新创建程序包5 从修改后的目录更新 Lambda 函数代码

102


第 5 步更新用户池以添加自定义发件人 Lambda 触发器

更新用户池以添加CustomEmailSender触发器

Send the parameter to update-user-pool along with any existing user pool configurations --lambda-config CustomEmailSender=LambdaVersion=V1_0LambdaArn= lambda-arn KMSKeyID= key-id

以下 Nodejs 示例展示了如何使用CustomEmailSenderLambda 函数

const AWS = require(aws-sdk) const b64 = require(base64-js) const encryptionSdk = require(aws-cryptoclient-node) Configure the encryption SDK client with the KMS key from the environment variables const encrypt decrypt = encryptionSdkbuildClient(encryptionSdkCommitmentPolicyREQUIRE_ENCRYPT_ALLOW_DECRYPT) const generatorKeyId = processenvKEY_ALIAS const keyIds = [ processenvKEY_ID ] const keyring = new encryptionSdkKmsKeyringNode( generatorKeyId keyIds ) exportshandler = async (event) =gt

Decrypt the secret code using encryption SDK let plainTextCode if(eventrequestcode) const plaintext messageHeader = await decrypt(keyring b64toByteArray(eventrequestcode)) plainTextCode = plaintext

PlainTextCode now has the decrypted secret if(eventtriggerSource == CustomEmailSender_SignUp) Send email to end-user using custom or 3rd party provider Include temporary password in the email else if(eventtriggerSource == CustomEmailSender_ResendCode) else if(eventtriggerSource == CustomEmailSender_ForgotPassword) else if(eventtriggerSource == CustomEmailSender_UpdateUserAttribute) else if(eventtriggerSource == CustomEmailSender_VerifyUserAttribute) else if(eventtriggerSource == CustomEmailSender_AdminCreateUser) else if(eventtriggerSource == CustomEmailSender_AccountTakeOverNotification) return

103


自定义电子邮件发件人 Lambda 触发源下表显示了 Lambda 代码中自定义电子邮件触发器源的触发事件

TriggerSource value 触发事件

CustomEmailSender_SignUp 注册后发送确认代码

CustomEmailSender_ResendCode 向新用户重新发送临时密码

CustomEmailSender_ForgotPassword 向现有用户重新发送确认代码

CustomEmailSender_UpdateUserAttribute 当用户的电子邮件发生更改时此触发器自动向用户发送验证码不可用于其他属性

CustomEmailSender_VerifyUserAttribute 当用户针对新的电子邮件地址手动请求验证码时此触发器向用户发送验证码

CustomEmailSender_AdminCreateUser 向新用户发送临时密码

CustomEmailSender_AccountTakeOverNotification当检测到有人试图接管他们的帐户时此触发器会向客户发送通知

自定义 SMS 发件人 Lambda 触发器这些区域有CustomSMSSender触发器从 Lambda 函数代码中调用以使第三方提供商能够向用户发送SMS 通知使用此触发器涉及五个主要步骤

Note

这些区域有CustomSMSSender触发器在 Amazon Cognito 控制台中不可用

bull 创建 Lambda 函数CustomSMSSenderbull 创建加密密密密密密密密密Amazon KMSbull 授予 Amazon Cognito 服务主要人身份识别-idpamazonawscom 访问权限以调用 Lambda 函数bull 编辑 Lambda 函数中的代码以包含第三方提供程序bull 更新您的用户池以添加自定义触发器

Important

为了提高安全性您必须在Amazon KMS 当CustomEmailSender或者CustomSMSSender配置了用户池Amazon Cognito 使用您配置的 KMS 密钥来加密代码或临时密码Amazon Cognito 将base64 编码的密文发送到您的 Lambda 函数有关更多信息请参阅对称客户主密钥

启用CustomSMSSenderLambda 触发器您可以启用CustomSMSSender触 Lambda 器


创建 Lambda 函数CustomSMSSender触发器Amazon Cognito 使用Amazon加密 SDK来加密密码（临时密码或授权码）


104




使用以下命令授予 Lambda 函数的访问权限







更新用户池以添加自定义发件人触发器

代码示例

Send the parameter to update-user-pool along with any existing user pool configurations --lambda-config CustomSMSSender=LambdaVersion=V1_0LambdaArn= lambda-arn KMSKeyID= key-id

以下 Nodejs 示例展示了如何使用CustomSMSSenderLambda 函数

const AWS = require(aws-sdk) const b64 = require(base64-js) const encryptionSdk = require(aws-cryptoclient-node) Configure the encryption SDK client with the KMS key from the environment variables const encrypt decrypt = encryptionSdkbuildClient(encryptionSdkCommitmentPolicyREQUIRE_ENCRYPT_ALLOW_DECRYPT) const generatorKeyId = processenvKEY_ALIAS const keyIds = [ processenvKEY_ID ] const keyring = new encryptionSdkKmsKeyringNode( generatorKeyId keyIds )

105


exportshandler = async (event) =gt


PlainTextCode now has the decrypted secret if(eventtriggerSource == CustomSMSSender_SignUp) Send sms to end-user using custom or 3rd party provider Include temporary password in the email else if(eventtriggerSource == CustomSMSSender_ResendCode) else if(eventtriggerSource == CustomSMSSender_ForgotPassword) else if(eventtriggerSource == CustomSMSSender_UpdateUserAttribute) else if(eventtriggerSource == CustomSMSSender_VerifyUserAttribute) else if(eventtriggerSource == CustomSMSSender_AdminCreateUser) else if(eventtriggerSource == CustomSMSSender_AccountTakeOverNotification) return

主题bull 自定义 SMS 发件人 Lambda 触发源 (p 104)

自定义 SMS 发件人 Lambda 触发源

下表显示了 Lambda 代码中自定义 SMS 触发器源的触发事件


CustomSMSSender_SignUp 注册后发送确认代码的自定义消息

CustomSMSSender_ResendCode 向新用户发送临时密码

CustomSMSSender_ForgotPassword 向现有用户重新发送确认代码

CustomSMSSender_UpdateUserAttribute 当用户的电子邮件或电话号码发生更改时此触发器自动向用户发送验证码不可用于其他属性

CustomSMSSender_VerifyUserAttribute 当用户针对新的电话号码手动请求验证码时此触发器向用户发送验证码

CustomSMSSender_Authentication 在身份验证过程中发送 MFA 代码

CustomSMSSender_AdminCreateUser 向新用户发送临时密码

106

Amazon Cognito 开发人员指南使用 Amazon Pinpoint 分析

将 Amazon Pinpoint 分析与 Amazon Cognito 用户池结合使用

Amazon Cognito User Pools与 Amazon Pinpoint 集成为 Amazon Cognito 用户池提供分析并丰富Amazon Pinpoint 市场活动的用户数据Amazon Pinpoint 提供分析和有针对性的市场活动以使用推送通知推动用户与移动应用程序的交互通过 Amazon Cognito 用户池中的 Amazon Pinpoint 分析支持您可以在 Amazon Pinpoint 控制台中跟踪用户池注册登录日活跃用户 (DAU) 和月活跃用户 (MAU)您可以深入查看不同日期范围或属性的数据例如设备平台设备区域设置和应用程序版本

您还可以使用Amazon Mobile SDK for Android或Amazon Mobile SDK for iOS设置特定于您的应用程序的用户属性然后可以使用这些属性在 Amazon Pinpoint 上对用户进行细分并向他们发送有针对性的推送通知如果您选择与 Amazon Pinpoint 共享用户属性数据中的分析选项卡中将 Amazon Cognito 为用户电子邮件地址和电话号码创建其他终端节点

查找 Amazon Cognito 和 Amazon Pinpoint 区域映射下表显示了 Amazon Cognito 和亚马 Amazon Pinpoint 之间的区域映射使用此表查找您构建 AmazonCognito 用户池的地区以及相应的 Amazon Pinpoint 区域接下来使用这些区域集成 Amazon Cognito 和您的 Amazon Pinpoint 项目

支持亚马逊 Pinpoint 的 Amazon Cognito 区域 Amazon Pinpoint 项目区域

ap-northeast-1

ap-northeast-2

ap-south-1

ap-southeast-1

ap-southeast-2

ca-central-1

eu-central-1

eu-west-1

eu-west-2

us-east-1

us-east-2

us-west-2

us-east-1

us-east-1

美国-东部 1 ap-soust-1

us-east-1

美国-east-1 ap-southeast-2

us-east-1

美国-东部 1 eu-central-1

us-east-1 eu-west-1

us-east-1

us-east-1

us-east-1

美国-east-1 us-west-2

区域映射示例

bull 如果您在 ap-1 中创建用户池则必须在 us-east-1 中创建您的 Amazon Pinpoint 项目bull 如果您在 ap-南1 中创建用户池则必须在 us-east-1 或 ap-南1 中创建您的 Amazon Pinpoint 项目

Note

Amazon Pinpoint 可在多个Amazon北美欧洲亚洲和大洋洲的区域除了表中的例外情况外Amazon Cognito 将仅支持亚马逊地区内的 Pinpoint 集成如果 Amazon Pinpoint 与 Amazon

107

Amazon Cognito 开发人员指南查找 Amazon Cognito 和 Amazon Pinpoint 区域映射

Cognito 位于同一地区则 Amazon Cognito 将事件发送到同一地区内的 Amazon Pinpoint 项目如果 Amazon Pinpoint 在该地区不可用那么 Amazon Cognito 在该地区不支持 Amazon Pinpoint集成直到亚马逊 Pinpoint 可用有关 Amazon Pinpoint 详细地区信息请参阅Amazon Pinpoint终端节点和配额

指定 Amazon Pinpoint 分析设置 (Amazon Web ServicesManagement Console）指定分析设置

1 登录 Amazon Cognito 控制台2 在导航窗格中选择 Manage User Pools (管理用户池)然后选择要编辑的用户池3 选择分析选项卡4 选择添加分析和活动5 从列表中选择 Cognito app client6 要将您的 Amazon Cognito 应用程序映射到Amazon Pinpoint 项目下从列表中选择 Amazon Pinpoint

项目

Note

Amazon Pinpoint 项目 ID 是 Amazon Pinpoint 项目特有的由 32 个字符组成的字符串它在Amazon Pinpoint 控制台中列出您可以将多个 Amazon Cognito 应用程序映射到单个 Amazon Pinpoint 项目但是每个Amazon Cognito 应用程序只能映射到一个 Amazon Pinpoint 项目在 Amazon Pinpoint 中每个项目都应是单个应用程序例如如果游戏开发人员有两款游戏则每款游戏都应是单独的 Amazon Pinpoint 项目即使两款游戏使用同一 AmazonCognito 用户池有关 Amazon Pinpoint 项目的更多信息请参阅在 Amazon Pinpoint 中创建项目

7 选择与 Amazon Pinpoint 共享用户属性数据如果您希望 Amazon Cognito 向 Amazon Pinpoint 发送电子邮件地址和电话号码以便为用户创建额外的终端节点验证账户电话号码和电子邮件地址后只有在它们可用于用户账户时它们才会与 Amazon Pinpoint 共享

Note

一个终端节点唯一地标识可以使用 Amazon Pinpoint 向其发送推送通知的用户设备有关终端节点的更多信息请参阅添加终端节点中的Amazon Pinpoint 开发人员指南

8 选择保存更改9 要指定额外的应用程序映射请选择添加其他应用程序映射10 选择保存更改

指定 Amazon Pinpoint 分析设置 (Amazon CLI和AmazonAPI）使用以下命令为您的用户池指定 Amazon Pinpoint 分析设置

在创建应用程序时为用户池的现有客户端应用程序指定分析设置

bull Amazon CLI aws cognito-idp create-user-pool-clientbull Amazon APICreateUserPoolClient

为用户池的现有客户端应用程序更新分析设置

bull Amazon CLI aws cognito-idp update-user-pool-clientbull Amazon APIUpdateUserPoolClient

108

Amazon Cognito 开发人员指南管理用户

Note

Amazon Cognito 支持在您使用ApplicationArn

在用户池中管理用户创建用户池后您可以创建确认和管理用户账户借助 Amazon Cognito 用户池组您可以通过将 IAM 角色映射到组来管理您的用户及其对资源的访问

利用用户迁移 Lambda 触发器您可以将用户导入用户池中此方法使用户能够在首次登录您的用户池时从您的现有用户目录无缝迁移到用户池

主题bull 注册并确认用户账户 (p 109)bull 以管理员身份创建用户账户 (p 115)bull 向用户池添加组 (p 118)bull 管理和搜索用户账户 (p 120)bull 恢复用户帐户 (p 123)bull 将用户导入一个用户池 (p 124)

注册并确认用户账户可通过以下任一方法将用户账户添加到您的用户池中

bull 用户在您用户池的客户端应用程序中进行注册该应用程序可以是移动应用程序或 Web 应用程序bull 您可以将用户账户导入到用户池中有关更多信息请参阅通过 CSV 文件将用户导入用户池

中 (p 125)bull 您可以在用户池中创建用户账户并邀请用户登录有关更多信息请参阅以管理员身份创建用户账

户 (p 115)

自行注册的用户需要获得确认才可登录导入和创建的用户已经过确认但他们需要在首次登录时创建密码以下部分将介绍确认过程以及电子邮件和电话验证

用户账户确认概述下图阐明了确认过程

109

Amazon Cognito 开发人员指南注册并确认用户账户

用户账户可以处于以下任一状态

已注册 (未确认)

用户已成功注册但在用户账户得到确认之前无法登录在此状态下用户已启用但未得到确认

自行注册的新用户由此状态开始已确认

用户账户已确认用户可以登录如果用户输入通过电子邮件或手机 (SMS) 收到的确认代码（如果是通过电子邮件则单击确认链接）从而确认了用户账户则系统将自动验证该电子邮件或电话号码代码或链接的有效期为 24 小时

如果管理员或预注册 Lambda 触发器确认了用户账户则可能没有与账户关联的经验证电子邮件或电话号码

需要重置密码

用户账户已确认但用户必须请求代码并重置其密码才可登录

由管理员或开发人员导入的用户账户以此状态开始强制更改密码

用户账户已确认用户可以使用临时密码进行登录但在首次登录时用户必须将其密码更改为新值然后才能执行其他操作

由管理员或开发人员创建的用户账户以此状态开始已禁用

必须先禁用用户账户才可将其删除

在注册时验证联系人信息当新用户注册您的应用程序时您可能希望他们提供至少一种联系方式例如利用用户的联系人信息您可以

bull 在用户选择重置其密码时发送临时密码bull 在更新用户的个人信息或财务信息后向用户发送通知

110


bull 发送促销信息（例如特别优惠或折扣）bull 发送账户摘要或账单提醒

对于像这样的使用案例将消息发送到经过验证的目的地非常重要否则您可能会将消息发送到错误键入的无效电子邮件地址或电话号码或者更糟糕的是您可能会将敏感信息发送给冒充您的用户的坏人

为了帮助确保您仅将消息发送给正确的人员请配置您的 Amazon Cognito 用户池使用户在注册时必须提供以下内容

a 一个电子邮件地址或电话号码b Amazon Cognito 发送到该电子邮件地址或电话号码的验证码

通过提供验证码用户可以证明其有权访问收到该代码的邮箱或手机用户提供代码后Amazon Cognito会通过以下方式更新您的用户池中的用户相关信息

bull 将用户的状态设置为 CONFIRMEDbull 更新用户的属性以指示已验证电子邮件地址或电话号码

要查看此信息您可以使用 Amazon Cognito 控制台或者您可以使用 AdminGetUser API 操作带Amazon CLI 的 admin-get-user 命令或某个 Amazon 开发工具包中的相应操作

如果用户具有经验证的联系方式Amazon Cognito 会在用户请求密码重置时自动向其发送消息

配置您的用户池以要求电子邮件或手机验证

通过要求电子邮件或手机验证有助于确保您可通过可靠方式来联系您的用户完成以下步骤以使用Amazon Cognito 控制台配置您的用户池


如果您还没有用户池则需要在您的账户中配置用户池如需创建一个角色请参阅用户池入门 (p 19)

配置用户池

1 登录到Amazon Web Services Management Console并打开 Amazon Cognito 控制台httpsconsoleamazonawscncognito

2 选择 Manage User Pools (管理用户池)3 在 Your User Pools (您的用户池) 页面上选择要配置的用户池4 在左侧导航菜单中选择 MFA and verifications (MFA 和验证)

电子邮件或手机验证的选项显示在 Which attributes do you want to verify (您要验证哪些属性) 下

5 请选择以下任一选项

电子邮件

如果您选择此选项Amazon Cognito 会在用户注册时通过电子邮件发送验证码如果您通常通过电子邮件与用户通信请选择此选项例如如果您要发送账单订单摘要或特别优惠则将需要使用经过验证的电子邮件地址

111


电话号码

如果您选择此选项Amazon Cognito 会在用户注册时通过 SMS 发送验证码如果您通常通过SMS 与用户通信请选择此选项例如如果您要发送交付通知约会确认或提醒则将需要使用经过验证的电话号码

电子邮件或电话号码

如果您不要求所有用户都拥有相同的经验证的联系方式请选择此选项在这种情况下您的应用程序中的注册页面可能会要求用户仅验证其首选联系方式当 Amazon Cognito 发送验证码时它会将该代码发送到SignUp请求如果用户同时提供了电子邮件地址和电话号码并且您的应用程序在SignUp请求时Amazon Cognito 仅向电话号码发送验证码

如果您要求用户同时验证电子邮件地址和电话号码请选择此选项Amazon Cognito 将在用户注册时验证一种联系方式您的应用程序必须在用户登录后验证另一种联系方式有关更多信息请参阅在您要求用户确认电子邮件地址和电话号码的情况下 (p 112)

无

如果您选择此选项Amazon Cognito 不会在用户注册时发送验证码如果您使用的是自定义身份验证流程该流程将验证至少一种联系方式而不使用 Amazon Cognito 的验证码请选择此选项例如您可以使用一个预注册 Lambda 触发器该触发器将自动验证属于特定域的电子邮件地址

如果您不验证用户的联系人信息用户在某些情况下可能无法使用您的应用程序请记住用户需要经验证的联系人信息才能bull 重置其密码当用户在您的应用程序中执行调用ForgotPasswordAPI 操作时Amazon

Cognito 会向用户的电子邮件地址或电话号码发送临时密码仅当用户具有至少一种经过验证的联系方式时Amazon Cognito 才会发送此密码

bull 通过将电子邮件地址或电话号码用作别名来进行登录如果您将用户池配置为允许这些别名则用户只能在别名经过验证后使用别名进行登录有关更多信息请参阅别名概述 (p 155)


使用电子邮件或电话验证的身份验证流程如果您的用户池要求用户验证其联系人信息则当用户注册时您的应用程序必须促进以下流程

1 用户通过输入用户名称电话号码和或电子邮件地址及其他可能属性在您的应用程序中进行注册2 Amazon Cognito 服务收到来自应用程序的注册请求验证该请求包含注册所需的所有属性后该服务

将完成注册过程并向用户的手机 (通过 SMS) 或电子邮件发送确认代码代码的有效期为 24 小时3 该服务向应用程序返回信息表示注册过程已完成且用户账户正等待确认响应中包含关于确认代码所

发送到位置的信息此时用户账户处于未确认状态而且用户的电子邮件地址和电话号码未经验证4 现在应用程序会提示用户输入确认代码用户无需立即输入代码但是用户只有在输入确认代码后

才可登录5 用户在应用程序中输入确认代码6 应用程序调用ConfirmSignUp将代码发送到 Amazon Cognito 服务该服务将验证代码并在代码正确

时将用户账户设置为确认状态成功确认用户账户之后Amazon Cognito 服务会自动将用于确认 (电子邮件或电话号码) 的属性标记为已验证除非此属性的值发生更改否则用户无需再次进行验证

7 此时用户账户处于已确认状态用户可以登录

在您要求用户确认电子邮件地址和电话号码的情况下在用户注册时 Amazon Cognito 仅验证一种联系方式如果 Amazon Cognito 必须在验证电子邮件地址或电话号码之间进行选择它会选择通过 SMS 发送验证码来验证电话号码例如如果您将用户池配置为允许用户验证电子邮件地址或电话号码并且您的应用程序在注册时提供了这两个属性则 Amazon Cognito 将仅验证电话号码用户验证其电话号码后Amazon Cognito 会将用户的状态设置为CONFIRMED并允许用户登录您的应用程序

112


在用户登录后您的应用程序会提供相应选项来验证在注册期间未验证的联系方式为了验证第二种联系方式您的应用程序将调用 VerifyUserAttribute API 操作请注意此操作需要AccessToken参数Amazon Cognito 仅为经过身份验证的用户提供访问令牌因此您只能在用户登录后验证第二种联系方式

如果您要求用户同时验证电子邮件地址和电话号码请执行以下操作

1 配置用户池以允许用户验证电子邮件地址或电话号码2 在应用程序的注册流程中要求用户提供电子邮件地址和电话号码调用 SignUp API 操作并为

UserAttributes 参数提供电子邮件地址和电话号码此时Amazon Cognito 会向用户的手机发送一个验证码

3 在应用程序界面中会显示一个确认页面以供用户输入验证码通过调用 ConfirmSignUp API 操作来确认用户此时用户的状态为 CONFIRMED并且用户的电话号码已验证但电子邮件地址未验证

4 显示登录页并通过调用 InitiateAuth API 操作对用户进行身份验证用户身份验证后AmazonCognito 将向您的应用程序返回访问令牌

5 调用 GetUserAttributeVerificationCode API 操作在请求中指定以下参数

bull AccessTokenmdash 在用户登录时 Amazon Cognito 返回的访问令牌bull AttributeNamemdash 指定email作为属性值

Amazon Cognito 会向用户的电子邮件地址发送一个验证码6 显示一个确认页面以供用户输入验证码当用户提交代码时请调用 VerifyUserAttribute API 操

作在请求中指定以下参数

bull AccessTokenmdash 在用户登录时 Amazon Cognito 返回的访问令牌bull AttributeNamemdash 指定email作为属性值bull Codemdash 用户提供的验证码

此时电子邮件地址已验证

允许用户在您的应用程序中注册但以管理员身份进行确认1 用户通过输入用户名称电话号码和或电子邮件地址及其他可能属性在您的应用程序中进行注册2 Amazon Cognito 服务收到来自应用程序的注册请求验证该请求包含注册所需的所有属性之后该服

务将完成注册过程并向应用程序返回信息表示注册已完成且正在等待确认此时用户账户处于未确认状态账户经过确认后用户才可登录

3 管理员在 Amazon Cognito 控制台 (通过在用户选项卡然后选择确认按钮）或 CLI 中（通过使用admin-confirm-sign-up命令)Confirm (确认) 按钮和 admin-confirm-sign-up 命令都使用AdminConfirmSignUp API 来执行确认


计算 SecretHash 值以下 Amazon Cognito 用户池 API 具有SecretHash参数

bull ConfirmForgotPasswordbull ConfirmSignUpbull ForgotPasswordbull ResendConfirmationCodebull SignUp

113


SecretHash 值是的 Base 64 编码的加密哈希消息身份验证代码 (HMAC)使用用户池客户端的私有密钥用户名称以及消息中的客户端 ID 进行计算以下伪代码显示如何计算此值在此伪代码中+ 表示串联HMAC_SHA256 代表使用 HmacSHA256 生成 HMAC 值的函数Base64 代表生成哈希输出的 Base-64编码版本的函数

Base64 ( HMAC_SHA256 ( Client Secret Key Username + Client Id ) )

或者您可以在服务器端 Java 应用程序代码中使用以下代码示例

import javaxcryptoMacimport javaxcryptospecSecretKeySpec public static String calculateSecretHash(String userPoolClientId String userPoolClientSecret String userName) final String HMAC_SHA256_ALGORITHM = HmacSHA256 SecretKeySpec signingKey = new SecretKeySpec( userPoolClientSecretgetBytes(StandardCharsetsUTF_8) HMAC_SHA256_ALGORITHM) try Mac mac = MacgetInstance(HMAC_SHA256_ALGORITHM) macinit(signingKey) macupdate(userNamegetBytes(StandardCharsetsUTF_8)) byte[] rawHmac = macdoFinal(userPoolClientIdgetBytes(StandardCharsetsUTF_8)) return Base64getEncoder()encodeToString(rawHmac) catch (Exception e) throw new RuntimeException(Error while calculating )

无需验证电子邮件或电话号码即可确认用户账户预注册 Lambda 触发器可用于在注册时自动确认用户账户而无需提供确认代码或验证电子邮件或电话号码通过此方法进行确认的用户可立即登录而无需接收代码

您还可通过此触发器将用户的电子邮件或电话号码标记为已验证Note

虽然这种方法对刚入门的用户而言很方便但我们建议至少自动验证电子邮件或电话号码之一否则如果用户忘记密码可能就无法进行恢复

如果您不要求用户在注册时接收并输入确认代码也不在预注册 Lambda 触发器中自动验证电子邮件和电话号码则承担着不具备关于该用户账户的经验证电子邮件地址或电话号码的风险用户可以稍后验证电子邮件地址或电话号码但是如果用户忘记自己的密码且没有经过验证的电子邮件地址或电话号码则用户账户将被锁定因为ldquo忘记密码rdquo流程需要经验证的电子邮件或电话号码以便向用户发送验证代码

当用户更改其电子邮件或电话号码时应进行验证当用户在您的应用程序中更改其电子邮件地址或电话号码时该属性将标记为未经验证如果针对所更新的属性启用了自动验证则该服务将立即向用户发送包含验证代码的消息用户应输入此代码以验证更改您可以使用自定义消息 Lambda 触发器来自定义此消息有关更多信息请参阅使用 Lambda 触发器自定义用户池工作流 (p 63)每当用户的电子邮件地址或电话号码未经过验证时您的应用程序均应显示未经验证状态并为用户提供一个按钮或链接以验证其新的电子邮件或电话号码

针对由管理员或开发人员创建的用户账户的确认和验证过程由管理员或开发人员创建的用户账户已经处于已确认状态所以用户无需输入确认代码Amazon Cognito服务向这些用户发送的邀请消息包含用户名称和临时密码用户需要在登录前更改密码有关更多信息请

114

Amazon Cognito 开发人员指南以管理员身份创建用户

参阅Message Customizations 选项卡 (p 117)中的以管理员身份创建用户账户 (p 115)和使用 Lambda触发器自定义用户池工作流 (p 63)中的自定义消息触发器

针对导入的用户账户的确认和验证过程使用 Amazon Web Services Management ConsoleCLI 或 API 中的用户导入功能创建的用户账户（请参阅通过 CSV 文件将用户导入用户池中 (p 125)）已处于已确认状态因此用户无需输入确认代码没有发送邀请消息但是导入的用户账户要求用户首先调用 ForgotPassword API 来请求代码然后通过调用ConfirmForgotPassword API 来使用发送的代码创建密码之后方可登录有关更多信息请参阅要求导入的用户重置密码 (p 133)

导入用户账户时用户的电子邮件或电话号码必须已标记为已验证从而用户无需验证即可登录

在测试应用程序时发送电子邮件Amazon Cognito 在用户池的客户端应用程序中创建和管理其账户时向用户发送电子邮件如果您将用户池配置为要求电子邮件验证Amazon Cognito 将在以下情况下发送电子邮件

bull 用户注册bull 用户更新其电子邮件地址bull 用户执行一项调用 ForgotPassword API 操作的操作bull 您以管理员身份创建用户账户

根据发起电子邮件递送的操作电子邮件将包含验证码或临时密码您的用户必须接收这些电子邮件并理解消息否则他们可能无法登录并使用您的应用程序

要确保电子邮件成功发送并且邮件看起来正确请测试应用程序中的从 Amazon Cognito 启动电子邮件传送的操作例如通过使用应用程序中的注册页面或通过使用 SignUp API 操作您可以通过使用测试电子邮件地址进行注册来启动电子邮件传送在通过此方式进行测试时请记住以下几点

Important

当您使用电子邮件地址来测试从 Amazon Cognito 发送电子邮件的操作时请勿使用虚假的电子邮件地址（没有邮箱的电子邮件地址）使用真实的电子邮件地址以便接收来自 Amazon Cognito 的电子邮件而不创建硬退回邮件Amazon Cognito 未能将电子邮件传送到收件人邮箱时将出现硬退回如果邮箱不存在则这种情况始终出现Amazon Cognito 限制可发送的电子邮件的数量Amazon帐户持续发生硬反弹

当您测试启动电子邮件传送的操作时请使用下列电子邮件地址之一以防止出现查无此人的邮件

bull 您拥有的用于测试的电子邮件账户的地址当您使用自己的电子邮件地址时您将收到 Amazon Cognito发送的电子邮件利用此电子邮件您可以使用验证码来测试应用程序中的注册体验如果您为用户池自定义了电子邮件则可检查自定义项看起来是否正确

bull 邮箱模拟器地址successsimulatoramazonsescom如果您使用模拟器地址Amazon Cognito 将成功发送电子邮件但您无法查看它当您不需要使用验证码并且不需要检查电子邮件时此选项很有用

bull 添加任意标签的邮箱模拟器地址例如成功 + user1simulatoramazonsescom或者成功 +user2simulatoramazonsescomAmazon Cognito 已成功通过电子邮件成功发送这些地址但您无法查看其发送的电子邮件当您希望通过向用户池添加多个测试用户来测试注册过程并且每个测试用户都具有一个唯一的电子邮件地址时此选项很有用

以管理员身份创建用户账户创建用户池后您可以使用Amazon Web Services Management Console以及Amazon Command LineInterface或 Amazon Cognito API您可以为用户池中的新用户创建配置文件并通过 SMS 或电子邮件向用户发送带有注册说明的欢迎消息

115


开发人员和管理员可以执行以下任务

bull 通过使用 Amazon Web Services Management Console或调用 AdminCreateUser API 来创建新的用户配置文件

bull 指定临时密码或允许 Amazon Cognito 自动生成一个密码bull 指定是否将提供的电子邮件地址和电话号码标记已针对新用户进行验证bull 通过 Amazon Web Services Management Console或自定义消息 Lambda 触发器为新用户指定自定义

SMS 和电子邮件邀请消息有关更多信息请参阅使用 Lambda 触发器自定义用户池工作流 (p 63)bull 指定是否通过 SMS电子邮件或两者发送邀请消息bull 通过调用 AdminCreateUser API并为 RESEND 参数指定 MessageAction向现有用户重新发送欢迎

消息

Note

目前无法使用 Amazon Web Services Management Console执行此操作bull 创建用户时禁止发送邀请消息bull 为用户账户指定到期时间限制 (最多 90 天)bull 允许用户自行注册或要求只能由管理员添加新用户

针对由管理员或开发人员创建的用户的身份验证流程针对这些用户的身份验证流程包括提交新密码并提供必须属性的任何缺失值的额外步骤下面列出了相关步骤步骤 56 和 7 特定于这些用户

1 用户首次通过提交向其提供的用户名称和密码开始登录2 开发工具包调用 InitiateAuth(Username USER_SRP_AUTH)3 Amazon Cognito 返回PASSWORD_VERIFIER质询与盐与秘密块4 开发工具包执行 SRP 计算并调用 RespondToAuthChallenge(Username ltSRP variablesgt

PASSWORD_VERIFIER)5 Amazon Cognito 返回NEW_PASSWORD_REQUIRED挑战以及当前属性和必需属性6 系统提示用户输入新密码和必需属性的任何缺失值7 开发工具包调用 RespondToAuthChallenge(Username ltNew passwordgt ltUser

attributesgt)8 如果用户需要 MFA 的第二安全要素Amazon Cognito 将返回 SMS_MFA 质询并提交代码9 用户成功更改自己的密码并选择性地提供属性值或完成 MFA 之后用户将登录并且系统将发出令

牌

用户满足所有质询后Amazon Cognito 服务会将用户标记为已确认并为用户发出 ID访问和刷新令牌有关更多信息请参阅将令牌与用户池结合使用 (p 139)

在 Amazon Web Services Management Console中创建新用户用于管理用户池的 Amazon Cognito 控制台已进行更新以支持此功能如以下所示

策略Tab

策略选项卡包含以下相关设置

bull 指定所需的密码强度

116


bull 指定是否允许用户自己注册默认情况下设定此选项

bull 为新账户指定用户账户到期时间限制 (以天为单位)从用户账户的创建时间开始计算默认设置为 7 天最大设置为 90 天账户到期后用户将无法登录账户直至管理员更新用户配置文件

Note

用户登录后账户将永不过期

Message Customizations 选项卡

消息自定义选项卡包含用于指定自定义电子邮件验证消息和自定义用户邀请消息的模板

对于电子邮件 (验证消息或用户邀请消息)消息的最大长度为 2048 个 UTF-8 字符包括验证代码或临时密码对于 SMS最大长度为 140 个 UTF-8 字符包括验证代码或临时密码

验证代码的有效期为 24 小时

117

Amazon Cognito 开发人员指南向用户池添加组

Users 选项卡Users and groups 选项卡中的 Users 选项卡具有一个 Create user 按钮

选择创建用户后将会显示一个创建用户表单在此可以输入关于新用户的信息仅用户名字段为必填字段

Note

对于您在中使用 Create userAmazon Web Services Management Console 表单创建的用户账户只能在 Amazon Web Services Management Console中设置表单中显示的属性其他属性必须通过使用Amazon Command Line Interface或 Amazon Cognito API即使您已将它们标记为必需属性

向用户池添加组借助对 Amazon Cognito 用户池中组的 Support您可以创建和管理组将用户添加到组以及从组中删除用户使用组可创建用户集合以管理其权限或表示不同类型的用户您可以将Amazon Identity and AccessManagement(IAM) 角色添加到组以定义组成员的权限

您可以使用组以在用户池中创建用户集合这通常用于为这些用户设置权限例如您可以为作为您网站和应用程序的读者撰稿人或编辑的用户创建单独的组通过使用与组关联的 IAM 角色您还可以为那些不同的组设置不同的权限从而只有撰稿人可以将内容置于 Amazon S3 中并且只有编辑可以通过 Amazon APIGateway 中的 API 发布内容

您可以通过 Amazon Web Services Management ConsoleAPI 和 CLI 创建并管理用户池中的组作为开发人员 (使用 Amazon 凭证)您可以创建读取更新删除并列出用户池的组您还可以将用户添加到组和从组中删除用户

在用户池中使用组不会产生额外费用请参阅Amazon Cognito 定价了解更多信息

您可以看到 SpaceFinder 参考应用程序中使用的此功能

118


向组分配 IAM 角色您可以使用组来控制使用 IAM 角色的资源的权限IAM 角色包括信任策略和权限策略角色信任策略指定谁可使用该角色这些区域有权限策略指定组成员可以访问的操作和资源在您创建 IAM 角色时请设置角色信任策略以允许您的组用户代入该角色在角色权限策略中指定您希望组具有的权限

当您在 Amazon Cognito 中创建群组时您可以通过提供角色的进行筛选当群组成员使用 Amazon Cognito登录时他们可以从身份池接收临时证书他们的权限由关联的 IAM 角色决定

单个用户可处于多个组中作为开发人员当一个用户处于多个组中时您可以使用以下选项自动选择 IAM角色

bull 您可以为每个组分配优先级值将选择优先级较高 (值较低) 的组并应用其关联的 IAM 角色bull 通过身份池请求用户的 Amazon 凭证时您的应用程序还可以从可用角色中进行选择只需在

GetCredentialsForIdentity CustomRoleARN 参数中指定角色 ARN指定的 IAM 角色必须与适用于用户的角色相匹配

将优先级值分配到组一个用户可归属于多个组在用户的 ID 令牌中cognitogroups断言包含用户所属的所有组的列表cognitoroles 断言包含与这些组对应的角色列表

因为一位用户可以归属于多个组所以可向每个组分配一个优先级这是一个非负数值指定该组相对于用户所属的用户池中其他组的优先级零是代表最高优先级的值具有较低优先级值的组优先于具有较高或空优先级值的组如果一个用户属于两个或更多组则具有最低优先级值的组的 IAM 角色将应用于cognitopreferred_role声明中的用户 ID 令牌

两个组可以具有相同的优先级值如果发生这种情况则两个组之间不存在优先情况如果具有相同优先级值的两个组还具有相同的角色 ARN则该角色将用于cognitopreferred_role在每个组中的用户 ID 令牌中声明如果两个组具有不同的角色 ARN则不会在用户的 ID 令牌中设置 cognitopreferred_role断言

使用组来控制使用 Amazon API Gateway 的权限您可以使用用户池中的组来控制 Amazon API Gateway 的权限用户所属的组包含在用户登录时用户池提供的 ID 令牌中您可以将这些 ID 令牌和请求提交至 Amazon API Gateway使用自定义授权方 Lambda 函数来验证令牌然后检查用户所属的组请参阅此博客帖子了解将用户池令牌与 Amazon API Gateway 自定义授权方结合使用的示例

组的限制用户组受以下限制的约束

bull 您可以创建的组的数量受Amazon Cognito 服务限制 (p 317)bull 不能对组进行嵌套bull 不能搜索组中的用户bull 不能按名称搜索组但可以列出组bull 只能删除没有成员的组

在 Amazon Web Services Management Console中创建新组Users and groups 选项卡中的 Groups 选项卡具有一个 Create group 按钮

119

Amazon Cognito 开发人员指南管理和搜索用户

在您选择创建组a创建组窗体您可以在此表单中输入关于新组的信息只有名称字段为必填项如果您要将用户池与身份池集成则IAM 角色设置将确定在身份池配置为从令牌中选择角色时在用户 ID 令牌中分配哪个角色如果您尚未定义角色请选择创建新角色如果您有多个组并且可将您的用户分配到多个组则可以将优先顺序每个组的值优先级值可以是任何非负整数零是代表最高优先级的值

管理和搜索用户账户创建用户池后您可以使用Amazon Web Services Management Console以及Amazon Command LineInterface或 Amazon Cognito API本主题将介绍如何使用 Amazon Web Services Management Console查看和搜索用户

查看用户属性您可以在 Amazon Web Services Management Console中执行多项操作

bull 您可以查看池详细信息并编辑用户池属性密码策略MFA 设置应用程序和触发器有关更多信息请参阅用户池参考 (Amazon Web Services Management Console) (p 152)

bull 您可以查看用户池中的用户并进一步了解更多详细信息bull 您还可以查看关于用户池中个别用户的详细信息bull 您也可以搜索用户池中的用户

使用 Amazon Web Services Management Console管理用户池

1 从 Amazon Cognito 主页Amazon Web Services Management Console中选择管理您的用户身份2 从您的用户池页中选择用户池3 选择用户和组以查看用户信息4 选择用户名称以显示关于单个用户的更多信息在此屏幕中您可以执行以下任一操作

bull 将用户添加到组bull 重置用户密码bull 确认用户bull 启用或禁用 MFA

120


bull 删除用户

重置用户密码操作会导致立即向用户发送确认代码并通过将用户状态更改为 RESET_REQUIRED 来禁用用户的当前密码启用 MFA 操作会导致在用户尝试登录时立即向其发送确认代码重置用户密码代码的有效期为 1 小时MFA 代码的有效期为 3 分钟

搜索用户属性如果您已创建用户池则可以在的 UsersAmazon Web Services Management Console 面板中搜索您也可以使用 Amazon CognitoListUsers API它接受筛选条件参数

您可以搜索以下任何标准属性自定义属性不可搜索

bull username (区分大小写)bull emailbull phone_numberbull namebull given_namebull family_namebull preferred_usernamebull cognitouser_status（在控制台中称为状态）（区分大小写）bull status（在控制台中称为已启用）（区分大小写）bull sub

使用 Amazon Web Services Management Console搜索用户如果您已创建用户池则可以在的 UsersAmazon Web Services Management Console 面板中搜索

Amazon Web Services Management Console搜索始终为前缀 (ldquostarts withrdquo) 搜索

以下所有示例均使用同一个用户池

例如如果您要列出所有用户则将搜索框留空

如果您要搜索所有已确认的用户则从下拉菜单中选择状态在搜索框中输入单词ldquoconfirmedrdquo的第一个字母

121


请注意某些属性值区分大小写如用户名

使用 ListUsers API 搜索用户要从应用程序中搜索用户请使用 Amazon CognitoListUsers API此 API 使用以下参数

bull AttributesToGet一组字符串其中每个字符串均为将针对搜索结果中的每位用户返回的用户属性的名称如果字符串组为空将返回所有属性

bull Filter筛选条件字符串格式为 AttributeName Filter-Type AttributeValue筛选条件字符串中的引号必须使用反斜杠 () 字符进行转义例如family_name = Reddy如果筛选条件字符串为空ListUsers 将返回用户池中的所有用户bull AttributeName要搜索的属性的名称一次只能搜索一个属性

Note

您只能搜索标准属性自定义属性不可搜索这是因为只有索引属性可搜索而自定义属性不可索引

bull Filter-Type对于精确匹配请使用 =例如 given_name = Jon对于前缀 (ldquostarts withrdquo) 匹配请使用 ^=例如 given_name ^= Jon

bull AttributeValue必须为每位用户匹配的属性值bull Limit要返回的最大用户数bull PaginationToken可从之前的搜索中获取更多结果的令牌bull UserPoolId应对其执行搜索的用户池的用户池 ID

所有搜索都区分大小写搜索结果按以 AttributeName 字符串命名的属性进行升序排列

使用 ListUsers API 的示例以下示例将返回所有用户并包括所有属性

AttributesToGet [] Filter Limit 10 UserPoolId us-east-1_samplepool

122

Amazon Cognito 开发人员指南恢复用户帐户

以下示例将返回电话号码以ldquo+1312rdquo开头的所有用户并包括所有属性

AttributesToGet [] Filter phone_number ^= +1312 Limit 10 UserPoolId us-east-1_samplepool

以下示例将返回姓氏为ldquoReddyrdquo的前 10 位用户对于每个用户搜索结果包含用户的名字电话号码和电子邮件地址如果用户池中有 10 个以上相匹配的用户则响应将包含一个分页标记

AttributesToGet [ given_name phone_number email ] Filter family_name = Reddy Limit 10 UserPoolId us-east-1_samplepool

如果上一示例返回分页标记则以下示例将返回与同一筛选条件字符串相匹配的接下来的 10 位用户

AttributesToGet [ given_name phone_number email ] Filter family_name = Reddy Limit 10 PaginationToken pagination_token_from_previous_search UserPoolId us-east-1_samplepool

恢复用户帐户通过 AccountRecoverySetting 参数您可以自定义用户在调用 ForgotPassword API 时可用于恢复其密码的方法ForgotPassword 会将恢复码发送到已验证的电子邮件或已验证的电话号码当您指定时AccountRecoverySetting将从 AccountRecoverySetting 定义的优先选项中选择首选设置

当您定义 AccountRecoverySetting 并且用户配置了 SMS MFA 时不能将 SMS 用作账户恢复机制此设置的优先级已确定其中 1 为最高优先级Cognito 仅向指定方法之一发送验证

例如当管理员不希望用户自行恢复账户时可以使用值 admin_only这会改为要求用户联系管理员来重置账户您不能将 admin_only 与任何其他帐户恢复机制一起使用

如果您未指定 AccountRecoverySettingAmazon Cognito 会使用旧机制来确定恢复密码的方法在这种情况下Cognito 首先使用经过验证的手机如果找不到用户经过验证的手机Cognito 会退回接下来使用经验证的电子邮件

有关的更多信息AccountRecoverySetting请参阅CreateUserPool和UpdateUserPool中的AmazonCognito Identity Provider API 参考

忘记密码行为在给定的小时内我们允许用户 5 到 20 次尝试请求或输入密码重置代码作为忘记密码和确认忘记密码操作的一部分确切的值取决于与请求关联的风险参数请注意这种行为可能会发生变化

123

Amazon Cognito 开发人员指南将用户导入一个用户池

将用户导入一个用户池您可以使用以下两种方式将用户从现有用户目录或用户数据库导入或迁移到 Amazon Cognito 用户池中您可以利用用户迁移 Lambda 触发器在用户首次使用 Amazon Cognito 登录时迁移用户借助这种方法用户可以继续使用其现有的密码不必在迁移到用户池后重置密码或者您可以上传 CSV 文件 (包含所有用户的用户配置文件属性)批量迁移用户以下各部分分别介绍了这两种方法

主题bull 利用用户迁移 Lambda 触发器将用户导入用户池 (p 124)bull 通过 CSV 文件将用户导入用户池中 (p 125)

利用用户迁移 Lambda 触发器将用户导入用户池通过这种方法用户在首次使用启用了全新 Amazon Cognito 的应用程序时可在首次登录或忘记密码过程中从现有用户目录无缝迁移到用户池这种迁移由用户迁移 Lambda 函数实现需要您在用户池中进行配置有关此 Lambda 触发器的详细信息（包括请求和响应参数）以及示例代码请参阅迁移用户 Lambda 触发器参数 (p 94)

在开始用户迁移过程 Lambda请在Amazon帐户然后配置您的用户池以使用此 Lambda 函数的 ARN 作为用户迁移触发器为您的 Lambda 函数添加授权策略只允许 Amazon Cognito 服务账户委托人 (ldquocognito-idpamazonawscomrdquo) 和您的用户池的源 ARN 调用它以防止任何其他Amazon客户的用户池调用您的Lambda 函数有关更多信息请参阅对使用基于资源的策略AmazonLambda（Lambda 函数策略）

登录过程中的步骤

1 用户打开您的应用程序使用 Cognito 身份提供商 API通过应用程序中的原生登录 UI 屏幕进行登录Amazon移动开发工具包或使用 Amazon Cognito 提供的托管登录 UI您可以通过AmazonCognito 身份验证软件开发工具包

2 您的应用程序将用户名和密码发送至 Amazon Cognito如果您的应用程序具有原生登录 UI并使用 Cognito 身份提供商开发工具包那么您的应用程序必须使用 USER_PASSWORD_AUTH流程开发工具包通过该流程将密码发送至服务器 (您的应用程序不得使用默认USER_SRP_AUTH 流程因为在 SRP 身份验证流程中开发工具包不会将密码发送到服务器)将 AuthenticationDetailsauthenticationType 设置为 USER_PASSWORD即可启用USER_PASSWORD_AUTH 流程

3 Amazon Cognito 会检查用户名是否存在于用户池中包括作为别名的用户电子邮件电话号码或preferred_username如果用户不存在Amazon Cognito 会调用您的用户迁移 Lambda 函数 (其参数包括用户名称和密码)有关详细信息请参阅迁移用户 Lambda 触发器参数 (p 94)

4 您的用户迁移 Lambda 函数应调用现有的登录服务利用您的现有用户目录或用户数据库对用户进行身份验证还应返回用户属性存储在用户池的用户配置文件中如果您希望用户继续使用现有密码请将属性设置为finalUserStatus= Lambda 响应中的 ldquo确认rdquo有关响应的必要属性请参阅迁移用户Lambda 触发器参数 (p 94)

Important

请勿在您的用户迁移 Lambda 代码中记录整个请求事件对象 (因为这样会把密码包含在发送到CloudWatch 日志的日志记录中)并确保您会清理日志以便密码不会被记录

5 Amazon Cognito 在您的用户池中创建用户配置文件并将令牌返回您的应用程序客户端6 您的应用程序客户端现在可以继续执行登录后的正常功能

用户迁移完毕后我们建议您的原生移动应用程序使用 USER_SRP_AUTH 流程进行登录它使用安全远程密码 (SRP) 协议对用户进行身份验证不会通过网络发送密码还能通过迁移过程中所用的USER_PASSWORD_AUTH 流程提供安全优势

124


如果在迁移期间出现错误 (包括客户端设备问题或网络问题)您的应用程序会收到 Amazon Cognito 用户池API 的错误响应可能会在用户池中创建用户账户也可能不会用户应尝试再次登录如果反复失败则尝试在您的应用程序中使用忘记密码流程重置密码

忘记密码流程的工作原理是类似的但不会向您的用户迁移 Lambda 函数提供密码函数只会在现有用户目录中查找用户并返回属性存储在用户池中然后Amazon Cognito 会通过电子邮件或 SMS 向用户发送重置密码代码用户即可在您的应用程序中设置新密码如果您的应用程序有原生 UI它需要提供忘记密码流程的屏幕如果您的应用程序使用 Amazon Cognito 托管 UI我们会提供 UI 屏幕

通过 CSV 文件将用户导入用户池中您可以将用户导入 Amazon Cognito 用户池中用户信息从一个特殊格式的 csv 文件导入导入过程会设置所有用户属性的值不过 password 除外不支持导入密码因为安全妥善做法要求密码不能为纯文本而我们不支持导入哈希这意味着用户必须在首次登录时更改密码因此当使用此方法导入时您的用户将处于 RESET_REQUIRED 状态

Note

每个用户的创建日期就是将该用户导入用户池中的日期创建日期不是导入的属性之一

基本步骤如下

1 创建 Amazon CloudWatch Logs 角色Amazon Identity and Access Management(IAM) 控制台2 创建用户导入 csv 文件3 创建并运行用户导入任务4 上传用户导入 csv 文件5 启动并运行用户导入任务6 使用 CloudWatch 检查事件日志7 要求导入的用户重置密码

主题bull 创建 CloudWatch Logs IAM 角色 (Amazon CLI API) (p 125)bull 创建用户导入 csv 文件 (p 127)bull 创建并运行 Amazon Cognito 用户池导入 Job (p 129)bull 在 CloudWatch 控控制台中查看用户池导入结果 (p 132)bull 要求导入的用户重置密码 (p 133)

创建 CloudWatch Logs IAM 角色 (Amazon CLI API)

如果您使用的是 Amazon Cognito CLI 或 API则您需要创建一个 CloudWatch IAM 角色以下过程介绍了如何使 Amazon Cognito 在 CloudWatch Logs 中记录有关用户池导入任务的信息

Note

如果您使用的是Amazon Cognito 控制台因为控制台会为您创建该角色

为用户池导入创建 CloudWatch Logs IAM 角色 (Amazon CLI API)

1 登录到 Amazon Web Services Management Console然后通过以下网址打开 IAM 控制台httpsconsoleawsamazoncomiam

2 在 IAM 控制台的导航窗格中选择角色3 对于新角色选择创建角色

125


4 对于选择受信任实体的类型选择 Amazon 服务5 In常见使用案例中选择EC26 选择 NextPermissions (下一步权限)7 In附加权限策略中选择创建策略以打开新的浏览器选项卡并从头开始创建新策略8 在创建策略页面上选择 JSON 选项卡9 在JSON选项卡上复制以下文本并将其粘贴为角色访问策略从而替换所有现有文本

Version 2012-10-17 Statement [ Effect Allow Action [ logsCreateLogGroup logsCreateLogStream logsDescribeLogStreams logsPutLogEvents ] Resource [ arnawslogsREGIONACCOUNTlog-groupawscognito ] ]

10 选择查看策略添加名称和可选描述然后选择创建策略

在您创建策略后关闭该浏览器选项卡并返回到您的原始选项卡11 In附加策略中选择后续标签12 （可选）在标签中通过以键值对的形式输入标签来向角色添加元数据13 选择 Next审核14 In审核中输入角色名称15 （可选）输入角色描述16 选择 Create role (创建角色)17 在 IAM 控制台的导航窗格中选择角色18 In角色下选择您创建的角色19 In摘要中选择信任关系选项卡20 在信任关系选项卡上选择编辑信任关系21 将以下信任关系文本复制并粘贴到策略文档文本框中将替换所有现有文本

Version 2012-10-17 Statement [ Effect Allow Principal Service cognito-idpamazonawscom Action stsAssumeRole ]

22 选择 Update Trust Policy现在您已完成角色的创建23 记下角色 ARN在稍后创建导入任务时您将需要此信息

126


创建用户导入 csv 文件

您必须先创建 csv 文件作为输入然后才能将现有用户导入用户池中为此您需要下载用户导入 csv 标头信息然后按照设置 csv 文件的格式 (p 127) 中列出的格式要求编辑文件

下载 csv 文件标头（控制台）

1 导航到Amazon Cognito 控制台中选择管理用户池然后选择要向其中导入用户的用户池2 选择 Users 选项卡3 选择导入用户4 选择下载 CSV 标头以获取包含标头行（您必须在 csv 文件中添加这一内容）的 csv 文件

下载 csv 文件标头 (Amazon CLI）

要获取一系列正确的标头请运行以下 CLI 命令其中USER_POOL_ID 是要向其中导入用户的用户池的用户池标识符

aws cognito-idp get-csv-header --user-pool-id USER_POOL_ID

示例响应

CSVHeader [ name given_name family_name middle_name nickname preferred_username profile picture website email email_verified gender birthdate zoneinfo locale phone_number phone_number_verified address updated_at cognitomfa_enabled cognitousername ] UserPoolId USER_POOL_ID

设置 csv 文件的格式

下载的用户导入 csv 标头文件如下所示

cognitousernamenamegiven_namefamily_namemiddle_namenicknamepreferred_usernameprofilepicturewebsiteemailemail_verifiedgenderbirthdatezoneinfolocalephone_numberphone_number_verifiedaddressupdated_atcognitomfa_enabled

127


您需要编辑 csv 文件以使文件包含此标头和用户的属性值并根据以下规则设置格式

Note

有关属性值 (如电话号码的正确格式) 的更多信息请参阅配置用户池属性 (p 153)

bull 文件的第一行是已下载的包含用户属性名称的标头行bull csv 文件中列的顺序不重要bull 第一行之后的每一行都包含用户的属性值bull 标头中的所有列都必须存在但您不需要在每一列中提供值bull 以下属性为必需属性

bull cognitousernamebull cognitomfa_enabledbull email_verified 或 phone_number_verifiedbull email（如果 email_verified 为 true）bull phone_number（如果 phone_number_verified 为 true）bull 创建用户池时标记为必需的所有属性

bull 用户池必须至少有一个自动验证属性要么是 email_verified要么是 phone_number_verified每个用户至少有一个自动验证属性必须为 true如果用户池没有自动验证属性则导入任务不会启动如果用户池只有一个自动验证属性则该属性必须针对每个用户进行验证例如如果用户池只有 phone_number为自动验证属性则每个用户的 phone_number_verified 值都必须为 true

Note

为了便于用户重置密码用户必须拥有经过验证的电子邮件或电话号码Amazon Cognito 将包含重置密码代码的消息发送到 csv 文件中指定的电子邮件或电话号码如果将消息发送到电话号码则通过 SMS 发送

bull 字符串式的属性值不应该用引号括起来bull 如果属性值包含逗号则您必须在逗号前使用反斜杠 ()这是因为 csv 文件中的字段用逗号分隔了bull csv 文件内容应采用不含字节顺序标记的 UTF-8 格式bull cognitousername 字段是必填项并且在用户池中必须是唯一的它可以是任何 Unicode 字符串但是

它不能包含空格或制表符bull birthdate 值（如果存在）必须采用 mmddyyyy 格式也就是说如果生日日期为 1985 年 2 月 1 日则

必须编码为 02011985bull cognitomfa_enabled 字段为必填字段如果您已将用户池设置为需要进行多重验证 (MFA)则所有用户的

此字段都必须为 true如果您已将 MFA 设置为关闭则所有用户的此字段都必须为 false如果您已将MFA 设置为可选则此字段可以是 true 或 false但不能为空

bull 行的最大长度为 16000 个字符bull csv 文件的最大大小为 100MBbull 文件中的最大行 (用户) 数为 500000不含标头bull 这些区域有已更新的 _ 在字段值应为纪元时间 (用秒表示)例如1471453471bull 属性值中的所有前导空格或尾部空格均应去除

用户导入 csv 文件的完整示例如下所示

cognitousernamenamegiven_namefamily_namemiddle_namenicknamepreferred_usernameprofilepicturewebsiteemailemail_verifiedgenderbirthdatezoneinfolocalephone_numberphone_number_verifiedaddressupdated_atcognitomfa_enabledJohnJohnDoejohndoeexamplecomTRUE02011985+12345550100TRUE123 Any StreetFALSEJaneJaneRoejaneroeexamplecomTRUE01011985+12345550199TRUE100 Main StreetFALSE

128


创建并运行 Amazon Cognito 用户池导入 Job

本部分介绍如何使用 Amazon Cognito 控制台和创建并运行用户池导入任务Amazon Command LineInterface

主题bull 从 csv 文件导入用户（控制台） (p 129)bull 导入用户 (Amazon CLI） (p 129)

从 csv 文件导入用户（控制台）

以下过程介绍了如何从 csv 文件导入用户

从 csv 文件导入用户的步骤

1 选择创建导入任务2 键入任务名称任务名称可以包含大写和小写字母 (a-zA-Z)数字 (0-9) 和以下特殊字符+ =

-3 如果这是您首次创建用户导入任务则Amazon Web Services Management Console将自动为您创建

IAM 角色否则您可以从IAM 角色列表或者让Amazon Web Services Management Console为您创建新角色

4 选择上传 CSV 并选择要从中导入用户的 csv 文件5 选择创建作业6 要启动任务请选择开始

导入用户 (Amazon CLI）

以下 CLI 命令可用于将用户导入到用户池

bull create-user-import-job

bull get-csv-header

bull describe-user-import-job

bull list-user-import-jobs

bull start-user-import-job

bull stop-user-import-job

要获取这些命令的命令行选项列表请使用help命令行选项例如

aws cognito-idp get-csv-header help

创建用户导入任务

创建 csv 文件后请通过运行以下 CLI 命令创建用户导入任务其中JOB_NAME 是您为任务选择的名称USER_POOL_ID 是与之前相同的用户池 IDROLE_ARN 是您在创建 CloudWatch Logs IAM 角色(Amazon CLI API) (p 125)中收到的角色 ARN

aws cognito-idp create-user-import-job --job-name JOB_NAME --user-pool-id USER_POOL_ID --cloud-watch-logs-role-arn ROLE_ARN

响应中返回的 PRE_SIGNED_URL 在 15 分钟内有效在此之后它将过期而您必须创建新的用户导入任务以获取新的 URL

129


示例响应

UserImportJob Status Created SkippedUsers 0 UserPoolId USER_POOL_ID ImportedUsers 0 JobName JOB_NAME JobId JOB_ID PreSignedUrl PRE_SIGNED_URL CloudWatchLogsRoleArn ROLE_ARN FailedUsers 0 CreationDate 1470957431965

用户导入任务的状态值

在对用户导入命令的响应中您将看到以下 Status 值当中的其中一个值

bull ldquoCreatedrdquondash 任务已创建但未启动bull ldquoPendingrdquondash 一个转换状态您已启动任务但它尚未开始导入用户bull ldquoInProgressrdquondash 任务已启动正在导入用户bull ldquoStoppingrdquondash 您已停止任务但任务尚未停止导入用户bull ldquoStoppedrdquondash 您已停止任务且任务已停止导入用户bull ldquoSucceededrdquondash 任务已成功完成bull ldquoFailedrdquondash 任务因错误而停止bull ldquoExpiredrdquondash 您创建了一个任务但未在 24-48 小时内启动任务与任务关联的所有数据已删除且任务无

法启动

上传 csv 文件

使用以下curl命令将包含用户数据的 csv 文件上传到您从create-user-import-job命令

curl -v -T PATH_TO_CSV_FILE -H x-amz-server-side-encryptionawskms PRE_SIGNED_URL

在此命令的输出中查找 We are completely uploaded and fine 这一短语此短语表示文件已成功上传

描述用户导入任务

要获取用户导入任务的描述请使用以下命令其中USER_POOL_ID 是用户池 IDJOB_ID 是创建用户导入任务时返回的任务 ID

aws cognito-idp describe-user-import-job --user-pool-id USER_POOL_ID --job-id JOB_ID

示例响应

UserImportJob Status Created SkippedUsers 0 UserPoolId USER_POOL_ID

130


ImportedUsers 0 JobName JOB_NAME JobId JOB_ID PreSignedUrl PRE_SIGNED_URL CloudWatchLogsRoleArnROLE_ARN FailedUsers 0 CreationDate 1470957431965

在上一示例输出中PRE_SIGNED_URL 是您上传 csv 文件的目标 URL这些区域有ROLE_ARN是您创建角色时收到的 CloudWatch Logs 角色 ARN

列出用户导入任务

要列出用户导入任务请使用以下命令

aws cognito-idp list-user-import-jobs --user-pool-id USER_POOL_ID --max-results 2

示例响应

UserImportJobs [ Status Created SkippedUsers 0 UserPoolId USER_POOL_ID ImportedUsers 0 JobName JOB_NAME JobId JOB_ID PreSignedUrlPRE_SIGNED_URL CloudWatchLogsRoleArnROLE_ARN FailedUsers 0 CreationDate 1470957431965 CompletionDate 1470954227701 StartDate 1470954226086 Status Failed UserPoolId USER_POOL_ID ImportedUsers 0 SkippedUsers 0 JobName JOB_NAME CompletionMessage Too many users have failed or been skipped during the import JobId JOB_ID PreSignedUrlPRE_SIGNED_URL CloudWatchLogsRoleArnROLE_ARN FailedUsers 5 CreationDate 1470953929313 ] PaginationToken PAGINATION_TOKEN

任务按创建日期 (从近到远) 排列第二项任务之后的 PAGINATION_TOKEN 字符串表示此列表命令还有其他结果要列出更多结果请使用 --pagination-token 选项如下所示

aws cognito-idp list-user-import-jobs --user-pool-id USER_POOL_ID --max-results 10 --pagination-token PAGINATION_TOKEN

131


启动用户导入任务

要启动用户导入任务请使用以下命令

aws cognito-idp start-user-import-job --user-pool-id USER_POOL_ID --job-id JOB_ID

每个账户每次只能有一个导入任务处于活动状态

示例响应

UserImportJob Status Pending StartDate 1470957851483 UserPoolId USER_POOL_ID ImportedUsers 0 SkippedUsers 0 JobName JOB_NAME JobId JOB_ID PreSignedUrlPRE_SIGNED_URL CloudWatchLogsRoleArn ROLE_ARN FailedUsers 0 CreationDate 1470957431965

停止用户导入任务

要停止正在进行的用户导入任务请使用以下命令停止任务后无法重新启动该任务

aws cognito-idp stop-user-import-job --user-pool-id USER_POOL_ID --job-id JOB_ID

示例响应

UserImportJob CompletionDate 1470958050571 StartDate 1470958047797 Status Stopped UserPoolId USER_POOL_ID ImportedUsers 0 SkippedUsers 0 JobName JOB_NAME CompletionMessage The Import Job was stopped by the developer JobId JOB_ID PreSignedUrlPRE_SIGNED_URL CloudWatchLogsRoleArn ROLE_ARN FailedUsers 0 CreationDate 1470957972387

在 CloudWatch 控控制台中查看用户池导入结果您可以在 Amazon CloudWatch 控制台中查看导入任务的结果

主题bull 查看结果 (p 133)bull 解析结果 (p 133)

132


查看结果

以下步骤介绍了如何查看用户池导入结果

查看用户池导入结果的步骤

1 登录到 Amazon Web Services Management Console并通过以下网址打开 CloudWatch 控制台httpsconsoleawsamazoncomcloudwatch

2 选择 Logs (日志)3 为用户池导入任务选择日志组日志组名称的形式为 awscognito

userpoolsUSER_POOL_IDUSER_POOL_NAME4 为刚运行的用户导入任务选择日志日志名称的形式为 JOB_IDJOB_NAME日志中的结果按行号引用

用户日志中不会写入用户数据对于每个用户都将出现类似于以下内容的行

bull [SUCCEEDED] Line Number 5956 - The import succeeded

bull [SKIPPED] Line Number 5956 - The user already exists

bull [FAILED] Line Number 5956 - The User Record does not set any of the autoverified attributes to true (Example email_verified to true)

解析结果

已成功导入的用户的状态设置为ldquoPasswordResetrdquo

在以下情况下将不会导入用户但导入任务将继续

bull 自动验证属性未设置为 truebull 用户数据与架构不匹配bull 由于内部错误无法导入用户

在以下情况下导入任务将失败

bull Amazon CloudWatch Logs 角色无法承担没有正确的访问策略或已删除bull 用户池已删除bull Amazon Cognito 无法解析 csv 文件

要求导入的用户重置密码每个导入的用户第一次登录时系统都会要求他她输入新密码如下所示

要求导入的用户重置密码

1 用户尝试登录提供用户名和密码（通过InitiateAuth)2 Amazon Cognito 退货NotAuthorizedExceptionWHENPreventUserExistenceErrors处于启用

状态否则返回 PasswordResetRequiredException3 应用程序应将用户引导至 ForgotPassword 流程如以下过程中所述

a 应用程序调用 ForgotPassword(user name)b Amazon Cognito 向经过验证的电子邮件或电话号码 (具体取决于您在 csv 文件中为用户提供的内

容) 发送代码并在对ForgotPassword请求

Note

为了发送重置密码代码务必要确保用户池已开启电话号码或电子邮件验证c 应用程序向用户指出代码已发送及代码的发送位置并且应用程序提供 UI 以输入代码和新密码

133

Amazon Cognito 开发人员指南电子邮件设置

d 用户在应用程序中输入代码和新密码e 应用程序调用 ConfirmForgotPassword(code password)如果调用成功系统将设置新密

码f 现在应用程序应该将用户引导至登录页

Amazon Cognito 用户池的电子邮件设置您用户池的客户端应用程序中的某些事件可能导致 Amazon Cognito 向您的用户发送电子邮件例如如果您将用户池配置为需要电子邮件验证则当用户在应用程序中注册新账户或重置其密码时Amazon Cognito会发送电子邮件根据发起电子邮件递送的操作电子邮件将包含验证码或临时密码

为处理电子邮件递送您可以使用以下任一选项

bull 默认电子邮件功能 (p 134)它内置于 Amazon Cognito 服务中bull 您的 Amazon SES 配置 (p 134)

这些设置是可逆的如果需要您可以更新您的用户池以在这些设置之间切换

默认电子邮件功能您可以允许 Amazon Cognito 使用服务附带的默认电子邮件功能为您处理电子邮件递送当您使用默认选项时Amazon Cognito 针对您的用户池每天只允许有限数量的电子邮件有关特定限制的信息请参阅Amazon Cognito 中的配额 (p 317)对于典型的生产环境默认的电子邮件限制低于所需的递送量要启用更高的传输量您必须使用您的 Amazon SES 电子邮件配置

通过默认选项您可以使用以下任一电子邮件地址作为 FROM 地址

bull 默认电子邮件地址即 no-replyverificationemailcombull 您拥有的自定义电子邮件地址在可以使用您自己的电子邮件地址之前您必须向 Amazon SES 验证此地

址并且您必须向 Amazon Cognito 授予权限才能使用它

Amazon SES 电子邮件配置您的应用程序需要的递送量可能高于默认选项所提供的递送量要启用更高的传输量请将您的用户池配置为使用您的 Amazon SES 配置向用户发送电子邮件使用您的 Amazon SES 配置还可以提供更强大的功能监控您的电子邮件发送活动

在可以使用 Amazon SES 配置之前您必须向 Amazon SES 验证一个或多个电子邮件地址您可以将经验证的电子邮件地址用作您分配给用户池的 FROM 电子邮件地址然后Amazon Cognito 发送电子邮件时它通过代表您调用 Amazon SES 使用您的电子邮件地址

当您使用您的 Amazon SES 配置时用户池的电子邮件递送量限制就是适用于您的AmazonaccountNote

Amazon Cognito 的可用区域包括us-east-1us-east-2us-west-2eu-west-1eu-west-2eu-west-1ap-northeast-1ap-northeast-2ap-southeast-1ap-southeast-2 和 ca-southeast-1Amazon SES 可用区域包括us-east-1us-west-2eu-west-1

为您的用户池配置电子邮件完成以下步骤为用户池配置电子邮件设置根据您要使用的设置您可能需要通过 Amazon SES 完成步骤Amazon Identity and Access Management(IAM) 和亚 Amazon Cognito

134

Amazon Cognito 开发人员指南配置电子邮件账户

Note

在这些步骤中创建的资源无法跨 Amazon 账户进行共享例如您不能使用位于一个账户中的Amazon SES 电子邮件地址配置另一个账户中的用户池因此如果您在多个账户中使用 AmazonCognito请记得在每个账户中重复这些步骤

第 1 步使用 Amazon SES 验证您的电子邮件地址在配置您的用户池之前如果您要执行以下任一操作则必须向 Amazon SES 验证一个或多个电子邮件地址

bull 使用您自己的电子邮件地址作为 FROM 地址bull 使用您的 Amazon SES 配置来处理电子邮件递送

通过验证您的电子邮件地址您确认您拥有该电子邮件地址这有助于防止未经授权的使用

有关此过程的步骤请参阅验证电子邮件地址中的Amazon Simple Email Service 开发人员指南

第 2 步将您的账户移出 Amazon SES 沙盒当您首次开始使用 Amazon SES 时您的Amazon帐户被放置在 Amazon SES 沙箱中Amazon SES 使用沙盒来防止欺诈和滥用如果您使用 Amazon SES 配置来处理电子邮件递送则必须将您的Amazon账户然后 Amazon Cognito 才能向您的用户发送电子邮件

如果您使用的是默认 Amazon Cognito 电子邮件功能则可以跳过此步骤

Amazon SES 对您可以发送的电子邮件数量和可以发送电子邮件的位置施加限制您可以仅向已通过Amazon SES 验证的地址和域发送电子邮件也可以将其发送到 Amazon SES 邮箱模拟器地址虽然您的Amazon帐户仍保留在沙盒中请勿对生产环境中的应用程序使用您的 Amazon SES 配置在这种情况下Amazon Cognito 将无法将消息发送到您用户的电子邮件地址

有关移出沙盒的步骤请参阅脱离 Amazon SES 沙盒中的Amazon Simple Email Service 开发人员指南

第 3 步向 Amazon Cognito 授予电子邮件权限您可能需要向 Amazon Cognito 授予特定权限然后它才能向您的用户发送电子邮件您授予的权限以及用于授予权限的过程取决于您使用的是默认电子邮件功能还是您的 Amazon SES 配置

授予权限以使用默认的电子邮件功能

如果将您的用户池配置为使用默认电子邮件功能您可以使用以下任一地址作为 FRM 地址会通过该地址向您的用户发送电子邮件

bull 默认地址bull 自定义地址该地址必须是 Amazon SES 中已验证的地址

如果您使用的是默认电子邮件地址Amazon Cognito 不需要额外的权限您可以跳过此步骤

如果您使用的是自定义地址Amazon Cognito 需要额外的权限以便它可以使用此地址向您的用户发送电子邮件这些权限由发送授权策略它被附加到 Amazon SES 中的地址如果您使用 Amazon Cognito 控制台向您的用户池添加自定义地址它会自动为您附加此策略但是如果您在控制台外部配置您的用户池例如使用Amazon CLI或 Amazon Cognito API您必须自行附加策略

有关更多信息请参阅使用 Amazon SES 的发送授权中的Amazon Simple Email Service 开发人员指南

Example 发送授权策略

以下示例是一个发送授权策略该策略允许 Amazon Cognito 使用 Amazon SES 验证的电子邮件地址发送电子邮件

135


Version 2008-10-17 Statement [ Sid stmnt1234567891234 Effect Allow Principal Service cognito-idpamazonawscom Action [ sesSendEmail sesSendRawEmail ] Resource ltyour SES identity ARNgt ]

在此示例中ldquoSidrdquo值为唯一标识语句的任意字符串

有关策略语法的更多信息请参阅Amazon SES 发送授权策略中的Amazon Simple Email Service 开发人员指南

有关更多示例请参阅Amazon SES 发送授权策略示例中的Amazon Simple Email Service 开发人员指南

授予权限以使用您的 Amazon SES 配置

如果您将用户池配置为使用您的 Amazon SES 配置在向用户发送电子邮件时Amazon Cognito 需要额外的权限才能以您的身份调用 Amazon SES此授权将通过 IAM 服务授予

当您使用此选项配置您的用户池时Amazon Cognito 会创建一个服务相关角色这是 IAM 角色的一种类型在Amazonaccount 此角色包含允许 Amazon Cognito 访问 Amazon SES 并使用您的地址发送电子邮件的权限

Amazon Cognito 可以创建此角色之前您用来设置用户池的 IAM 权限必须包含iamCreateServiceLinkedRoleaction 有关更新 IAM 中的权限的更多信息请参阅更改 IAM 用户的权限中的IAM 用户指南

有关 Amazon Cognito 创建的服务相关角色的更多信息请参阅对 Amazon Cognito 使用服务相关角色 (p 281)

第 4 步配置您的用户池如果您要将您的用户池配置为使用以下内容请完成以下步骤

bull 自定义 FROM 地址（显示为电子邮件发件人）bull 自定义 REPLY-TO 地址用于接收您的用户发送到您的 FROM 地址的邮件bull 您的 Amazon SES 配置

如果您要使用 Amazon Cognito 电子邮件功能和地址则无需完成此过程

配置您的电子邮件地址


2 选择 Manage User Pools (管理用户池)3 在 Your User Pools (您的用户池) 页面上选择要配置的用户池4 在左侧导航菜单中选择 Message customizations (管理自定义)

136

Amazon Cognito 开发人员指南SMS 消息设置

5 如果您希望使用自定义 FROM 地址选择 Add custom FROM address (添加自定义 FROM 地址) 并执行以下操作

a 对于 SES region (SES 区域)选择包含验证的电子邮件地址的区域b 对于 Source ARN (源 ARN)请选择您的电子邮件地址Amazon Cognito 控制台可让您仅选择所

选区域中已通过 Amazon SES 验证的那些电子邮件地址c 对于 FROM email address (FROM 电子邮件地址)选择您的电子邮件地址您可以提供您的电子

邮件地址或电子邮件地址以及您的姓名6 在 Do you want to send emails through your Amazon SES Configuration (是否要通过 Amazon SES

配置发送电子邮件) 下选择 Yes - Use Amazon SES (是 - 使用 Amazon SES) 或 No - Use Cognito(Default) (否 -使用 Cognito (默认))

如果您选择使用 Amazon SESAmazon Cognito 将在您保存更改后创建服务相关角色7 如果您希望使用自定义 REPLY-TO 地址请选择 Add custom REPLY-TO address (添加自定义

REPLY-TO 地址)然后指定要用来接收用户发送到您的 FROM 地址的邮件的电子邮件地址8 当您完成设置您的电子邮件账户选项时选择 Save changes (保存更改)

Message customizations (消息自定义) 页面还提供了用于自定义验证消息 (p 162)和自定义邀请消息 (p 162)的选项

Amazon Cognito 用户池的 SMS 消息设置针对您的用户池的某些 Amazon Cognito 事件可能会导致 Amazon Cognito 向您的用户发送 SMS 短信例如如果您将用户池配置为需要电话验证则当用户在应用程序中注册新账户或重置其密码时AmazonCognito 会发送 SMS 文本消息根据发起 SMS 文本消息的操作消息将包含验证码临时密码或欢迎消息

Amazon Cognito 使用 Amazon Simple Notification Service (SNS) 来递送 SMS 文本消息如果这是您第一次通过 Amazon Cognito 或 Amazon SNS 发送短信您将被放置在 Amazon SNS 中的沙盒环境中这将允许您测试您的应用程序是否有短信在沙箱中邮件只能发送到已验证的电话号码

首次在 Amazon Cognito 用户池中设置 SMS 消息Amazon Cognito 使用 Amazon SNS 向您的用户池发送 SMS 消息当您首次设置 Amazon SNS 发送 SMS短信时您的Amazon帐户被放置在 Amazon SNS 沙箱中Amazon SNS 使用沙盒来防止欺诈和滥用并满足合规性要求在沙箱中Amazon SNS 规定了一些限制例如您最多可以将短信发送到 10 个已通过Amazon SNS 验证的电话号码虽然您的Amazon账户仍保留在沙盒中请勿对生产环境中的应用程序使用您的 Amazon SNS 配置当您处于沙箱中时Amazon Cognito 无法向用户的电话号码发送消息

要首次向生产环境中的用户池用户发送 SMS 文本消息您必须完成以下任务

1 确认您处于 SMS 沙箱中

2 在 Amazon SNS 中验证 Amazon Cognito 的电话号码

3 获取发送 SMS 消息到美国电话号码的来源身份

4 将您的账户从 Amazon SNS 沙箱中移出

5 在 Amazon Cognito 中完成用户池的设置

步骤 1 确认您处于 SMS 沙箱中1 登录到Amazon Web Services Management Console并在以下位置打开 Amazon Cognito 控制

台httpsconsoleawsamazoncomcognito

137

Amazon Cognito 开发人员指南首次在 Amazon Cognito 用户池中设置 SMS 消息

2 创建新用户池 (p 19)或者编辑现有用户池 (p 111)3 如果您的账户在 SMS 沙盒中您将在 Amazon Cognito 中看到以下消息

You are currently in a Sandbox environment in Amazon SNS

如果您没有看到此消息则表明某人已经执行了必要的步骤以便首次在您的帐户中设置 SMS 消息跳至步骤 5 在 Amazon Cognito 中完成用户池设置 (p 139)

4 选择Amazon SNS链接以在新选项卡中打开 Amazon SNS 控制台5 验证您是否在沙盒环境中控制台消息将指示您的沙箱状态Amazon区域例如

This account is in the SMS sandbox in US East (N Virginia)

在大多数Amazon区域来自用户池的 SMS 消息通过同一区域的 Amazon SNS 路由以下 Amazon Cognito区域中的 SMS 消息将通过相应的支持 Amazon SNS 区域进行重新路由

Amazon Cognito 地区支持的 Amazon SNS 区域

美国东部 (俄亥俄) 美国东部 (弗吉尼亚北部)

亚太地区 (孟买) 亚太地区 (悉尼)

亚太地区 (首尔) 亚太地区 (东京)

加拿大 (中部) 美国东部 (弗吉尼亚北部)

欧洲（法兰克福）欧洲（爱尔兰）

欧洲（伦敦）欧洲（爱尔兰）

步骤 2 在 Amazon SNS 中验证 Amazon Cognito 的电话号码要验证 SMS 目标电话号码以便使用您的应用程序进行测试您必须将目标电话号码添加到 Amazon SNS然后验证这些号码有关详细说明请参阅在 SMS 沙箱中添加和验证电话号码中的Amazon SimpleNotification Service 开发人员指南

Note

您可以添加到沙箱的目标电话号码数量有限制有关详细信息请参阅SMS 沙盒中的AmazonSimple Notification Service 开发人员指南

步骤 3 获取向美国电话号码发送 SMS 消息的发起身份如果您计划将 SMS 短信发送到美国电话号码则必须获取来源身份

自 2021 年 6 月 1 日起美国运营商要求提供发件人身份才能向美国电话号码发送消息如果您没有源身份则必须获得一个要了解如何获取源身份请参阅请求数字中的Amazon Pinpoint 用户指南

如果您在以下操作Amazon区域您必须打开Amazon Web Services Support票证以获取起始身份有关说明请参阅请求对 SMS 消息收发的支持中的Amazon Simple Notification Service 开发人员指南

bull 欧洲（斯德哥尔摩）bull 中东（巴林）bull 欧洲（巴黎）bull 南美洲（圣保罗）bull 美国西部 (加利福尼亚北部)

138

Amazon Cognito 开发人员指南使用令牌

步骤 4 将您的账户从 Amazon SNS 沙箱中移出当您的账户位于 Amazon SNS 的 SMS 沙箱中时Amazon Cognito 只能向已验证的电话号码发送短信而不是向您的最终用户发送短信

要向最终用户发送 SMS 消息您必须将您的账户移出沙盒并进入生产环境有关详细说明请参阅脱离Amazon SNS 沙盒中的Amazon Simple Notification Service 开发人员指南

步骤 5 在 Amazon Cognito 中完成用户池设置返回到您所在的浏览器选项卡creating (p 19)或者编辑 (p 111)您的用户池完成过程

将令牌与用户池结合使用通过令牌验证用户并授予对资源的访问权限令牌有声明这是关于用户的信息片段ID 令牌包含有关经过身份验证的用户的身份声明例如姓名和电子邮件Access 令牌包含有关经过身份验证的用户的声明用户组的列表以及作用域列表

Amazon Cognito 还有令牌您可以使用它来获取新的代币或撤销现有令牌刷新令牌 (p 143)来检索新的ID 令牌并访问令牌撤销令牌 (p 143)撤消刷新令牌允许的用户访问权限

使用令牌进行身份验证

当用户登录您的应用程序时Amazon Cognito 会验证登录信息如果登录成功Amazon Cognito 会创建会话并返回经过身份验证的用户的 ID 令牌访问令牌和刷新令牌您可以使用这些令牌向您的用户授予对您的服务器端资源或 Amazon API Gateway 的访问权限或者你可以将它们交换为临时Amazon凭证以访问其他Amazon服务

Important

我们强烈建议您在应用程序环境中保护传输和存储中的所有令牌

主题bull 使用 ID 令牌 (p 139)bull 使用访问令牌 (p 141)bull 使用刷新令牌 (p 143)bull RevokingTokens (p 144)bull 验证 JSON Web 令牌 (p 145)

使用 ID 令牌ID 令牌是JSON Web 令牌 (JWT)其中包含有关经过身份验证的用户的身份声明例如nameemail和phone_number您可以在应用程序中使用此身份信息ID 令牌还可用于向您的资源服务器或服务器应用程序验证用户您还可以将应用程序外部的 ID 令牌用于 Web API 操作在这些情况下您必须先验证 ID 令牌的签名然后才能信任 ID 令牌内的任何声明请参阅验证 JSON Web 令牌 (p 145)

您可以将 ID 令牌到期时间设置为 5 分钟到 1 天之间的任何值可以根据应用程序客户端设置此值

139

Amazon Cognito 开发人员指南使用 ID 令牌

Important

对于访问和 ID 令牌请勿指定最少少于一小时Amazon Cognito HosteDUi 使用有效期为一小时的 Cookie如果您输入的时间不到一小时您将无法获得较低的有效期

ID 令牌标头

标头包含两条令牌密钥 ID (kid) 和算法 (alg)

kid 1234example=alg RS256

密钥 ID (kid）

这些区域有kid参数是一个提示指示哪些密钥用于保护令牌的 JSON Web Signature (JWS)

有关 kid 参数的更多信息请参阅密钥标识符 (kid) 标头参数算法 (alg）

这些区域有alg参数表示用于保护 ID 令牌的加密算法用户池使用 RS256 加密算法这是一种采用SHA-256 的 RSA 签名

有关alg参数请参阅算法 (alg) 标头参数

ID 令牌负载

这是来自 ID 令牌的示例负载它包含有关经过身份验证的用户的声明有关 OIDC 标准声明的更多信息请参阅 OIDC 标准声明

sub aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee aud xxxxxxxxxxxxexample email_verified true token_use id auth_time 1500009400 iss httpscognito-idpus-east-1amazonawscomus-east-1_example cognitousername janedoe exp 1500013000 given_name Jane iat 1500009400 email janedoeexamplecom jti aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee origin_jti aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

主题 (sub）

这些区域有sub声明是经过身份验证的用户的唯一标识符 (UUID)声明不同于用户名后者可能不是唯一的

发布者 (iss）

iss 声明采用以下格式

httpscognito-idpregionamazonawscomuserPoolId

140

Amazon Cognito 开发人员指南使用访问令牌

例如假设您在us-east-1区域及其用户池 ID 为u123456在这种情况下为用户池的用户颁发的 ID令牌具有以下iss申请值

httpscognito-idpus-east-1amazonawscomu123456

受众 (aud）

这些区域有aud声明包含client_id用于用户身份验证令牌使用 (token_use）

The token_use 声明描述了该令牌的预期用途对于 ID 令牌它的值始终为 id身份验证时间 (auth_time）

这些区域有auth_time声明包含身份验证发生的时间其值是一个 JSON 数字代表从 1970-01-01T000 Z 开始以 UTC 格式为单位在刷新时它代表原始身份验证发生的时间而不是发布令牌的时间

源 JTI (origin_jti）

这些区域有源 JWT 标识符来自当original发生身份验证JTI (jti）

这些区域有jti声明是 JWT 的唯一标识符

ID 令牌可包含 OpenID Connect (OIDC) 标准声明在OIDC 标准声明它还可包含您在用户池中定义的自定义属性

Note

用户池自定义属性始终以为自定义前缀

ID 令牌签名

ID 令牌的签名根据 JWT 令牌的标头和负载计算在 Web API 中当您在应用程序外部使用时您必须始终先验证此签名然后才能接受该令牌请参阅验证 JSON Web Token验证 JSON Web 令牌 (p 145)

使用访问令牌用户池访问令牌包含有关经过身份验证的用户的声明用户组的列表以及作用域列表访问令牌的用途是在用户池中用户的环境中授予 API 操作权限例如您可以使用访问令牌向您的用户授予添加更改或删除用户属性的访问权限

访问令牌以 JSON Web Token (JWT) 表示访问令牌的标头与 ID 令牌具有相同的结构但是键 ID(kid）不同因为用于签署 ID 令牌和访问令牌的密钥不同与 ID 令牌一样您必须先在 Web API 中验证访问令牌的签名然后才能信任它的任何声明请参阅验证 JSON Web 令牌 (p 145)您可以将访问令牌过期时间设置为 5 分钟到 1 天之间的任何值可以根据应用程序客户端设置此值

Important


访问令牌标头标头包含两条令牌密钥 ID (kid) 和算法 (alg)


141


密钥 ID (kid）

kid 参数是一个提示指示哪些密钥用于保护令牌的 JSON Web Signature (JWS)

有关kid参数请参阅密钥标识符（子）标题参数算法 (alg）

这些区域有alg参数表示用于保护访问令牌的加密算法用户池使用 RS256 加密算法这是一种采用SHA-256 的 RSA 签名


访问令牌负载这是来自访问令牌的示例负载有关更多信息请参阅 JWT 声明

sub aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee device_key aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee cognitogroups [ admin ] token_use access scope awscognitosigninuseradmin auth_time 1562190524 iss httpscognito-idpus-west-2amazonawscomus-west-2_example exp 1562194124 iat 1562190524 origin_jti aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee jti aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee client_id 57cbishk4j24pabc1234567890 username janedoeexamplecom

主题 (sub）

sub 声明是经过身份验证的用户的唯一标识符 (UUID)声明不同于用户名后者可能不是唯一的Amazon Cognito 组 (cognitogroups）

这些区域有cognitogroups声明是用户属于的组的列表令牌使用 (token_use）

这些区域有token_use声明描述了该令牌的预期用途对于访问令牌它的值始终为 accessScope Laintscope）

范围声明是 Oauth 20 作用域的列表用于定义令牌提供的访问权限身份验证时间 (auth_time）


发布者 (iss）



142

Amazon Cognito 开发人员指南使用刷新令牌




访问令牌签名访问令牌的签名根据 JWT 令牌的标头和负载计算在 Web API 中当您在应用程序外部使用时您必须始终先验证此签名然后才能接受该令牌有关更多信息请参阅 JWT Token

使用刷新令牌您可以使用刷新令牌来检索新的 ID 令牌和访问令牌默认情况下刷新令牌会在您的应用程序用户登录用户池后的 30 天内过期当您为用户池创建应用程序时您可以将应用程序的刷新令牌到期时间设置为 60 分钟到 10 年之间的任何值

如果存在有效（未过期）刷新令牌适用于 SDK for iOS 的移动软件开发工具包适用于 Android 的移动软件开发工具包适用于 iOSAndroid 和 Flutter 的 Amplify 功能会自动刷新您的 ID 和访问令牌ID 和访问令牌的剩余有效期至少为 2 分钟如果刷新令牌已过期您的应用程序用户必须通过再次登录用户池来重新进行身份验证如果访问令牌和 ID 令牌的最小值设置为 5 分钟并且您正在使用 SDK则刷新令牌将持续刷新要查看预期的行为请将最少设置为 7 分钟而不是 5 分钟

Note

适用于 Android 的移动开发工具包提供的选项可将 ID 令牌和访问令牌的最短有效期更改为 0 到 30分钟之间的值请参阅setRefreshThreshold()的方法CognitoIdentityProviderClientConfig中的Amazon Mobile SDK for AndroidAPI 参考

只要用户在UnusedAccountValidityDays新帐户的时间限制

要结合使用刷新令牌与用户池 API 获取新的 ID 令牌和访问令牌请使用 AdminInitiateAuth 或 InitiateAuth方法PassREFRESH_TOKEN_AUTH(对于 )AuthFlow参数授权参数AuthParameters是键值映射其中键是REFRESH_TOKEN值是实际刷新令牌Amazon Cognito 使用新的 ID 令牌和访问令牌进行响应

Note

要更改使用 HosteDUI 登录的用户的令牌请使用 InitiateAuthAPI操作

撤销RefreshToken您可以撤销刷新属于用户的令牌有关撤消令牌的更多信息请参阅RevokingTokens (p 144)

Note

撤消刷新令牌将撤销所有Token这些都是发布的使用刷新令牌

当您撤消用户的所有令牌时用户可以从其当前登录的所有设备中注销方法是使用GlobalSignOut和AdminUserGlobalSignOutAPI 操作在用户之后为退出以下事物发生

bull 用户的刷新令牌无法用于为用户获取新的令牌bull 用户的访问令牌无法用于用户池服务bull 用户必须重新进行身份验证以获取新的令牌会话 cookie 不会自动过期作为最佳做法应用程序应将用

户重定向到注销终端节点以强制浏览器清除会话 Cookie

应用程序可以使用GlobalSignOutAPI 来允许单个用户将自行从所有设备注销通常应用程序会将此选项显示为一个选择例如从所有设备注销应用程序必须使用户的有效非过期的非撤消的访问令牌调用此方法此方法不能用于允许一个用户注销另一个用户

143

Amazon Cognito 开发人员指南撤销令牌

应用程序可以使用AdminUserGlobalSignOutAPI 来允许管理员将一个用户从所有设备注销管理员应用程序必须通过 AWS 开发人员凭证调用此方法并传递用户池 ID 和用户的用户名作为参数AdminUserGlobalSignOut API 可以在用户池中注销任何用户

RevokingTokens您可以撤销刷新用户令牌使用AmazonAPI撤消刷新令牌时先前由该刷新令牌颁发的所有访问令牌都将无效向用户颁发的其他刷新令牌不受影响

Note

JWT Token是独立的具有在创建令牌时分配的签名和过期时间撤销的令牌不能与任何需要令牌的 Cognito API 调用一起使用但是如果使用任何验证令牌签名和过期的 JWT 库进行验证吊销令牌仍然有效

您可以在启用令牌吊销的情况下撤消用户池客户端的刷新令牌当您创建新的用户池客户端时默认情况下会启用令牌撤消

启用令牌吊销必须启用令牌吊销然后才能撤消现有用户池客户端的令牌可以为现有用户池客户端启用令牌吊销使用Amazon CLI或AmazonAPI若要执行此操作请调用aws cognito update-user-pool-clientCLI 命令或UpdateUserPoolClientAPI 操作当您执行此操作时将EnableTokenRevocation参数true

当您使用创建新用户池客户端Amazon Web Services Management ConsoleAmazon CLI或AmazonAPI令牌撤销已默认启用

启用令牌撤销后Amazon Cognito JSON 网络令牌中会添加新的声明这些区域有origin_jti和jti声明添加到访问和 ID 令牌中这些声明会增加应用程序客户端访问和 ID 令牌的大小

以下JSON 示例显示启用令牌的请求撤销CreateUserPoolClientAPI

AccessTokenValidity 123 AllowedOAuthFlows [ string ] AllowedOAuthFlowsUserPoolClient true AllowedOAuthScopes [ string ] AnalyticsConfiguration ApplicationArn string ApplicationId string ExternalId string RoleArn string UserDataShared false CallbackURLs [ string ] ClientName string DefaultRedirectURI string ExplicitAuthFlows [ string ] GenerateSecret true IdTokenValidity 123 LogoutURLs [ string ]

144

Amazon Cognito 开发人员指南验证 JSON Web 令牌

PreventUserExistenceErrors string ReadAttributes [ string ] RefreshTokenValidity 456 SupportedIdentityProviders [ string ] TokenValidityUnits AccessToken string IdToken string RefreshToken string UserPoolId string WriteAttributes [ string ] EnableTokenRevocation true

Revoke 令牌您可以撤销刷新令牌使用 RevokeToken API操作您也可以使用aws cognito-idp revoke-token CLI命令撤销令牌You 也可以使用吊销终端节点这个终端节点是将域添加到您的用户池后将可用您可以在 Amazon Cognito 托管域或您自己的自定义域上使用吊销终端节点

Note

刷新令牌必须使用与获取令牌相同的客户端 ID 撤销

验证 JSON Web 令牌这些步骤描述了验证用户池 JSON Web Token (JWT) 的过程

主题bull Prerequisites (p 145)bull 第 1 步确认 JWT 的结构 (p 145)bull 第 2 步验证 JWT 签名 (p 146)bull 第 3 步验证声明 (p 147)

Prerequisites本部分中的任务可能已由您的库开发工具包或软件框架进行处理例如用户池令牌处理和管理在客户端上是通过 Amazon Cognito 开发工具包提供的同样如果满足以下两个条件SDK for iOS 的移动软件开发工具包和适用于 Android 的移动软件开发工具包会自动刷新您的 ID 和访问令牌必须存在有效的（未过期的）刷新令牌而且 ID 令牌和访问令牌至少有 5 分钟的剩余有效性有关开发工具包以及适用于JavaScriptAndroid 和 iOS 的示例代码请参阅Amazon Cognito 用户池软件开发工具包

许多好的库可用于解码和验证 JSON Web Token (JWT)如果您需要手动处理用于服务器 API 处理的令牌或者您使用的是其他编程语言此类库可以提供帮助请参阅用于处理 JWT 令牌的库的 OpenID Foundation列表

第 1 步确认 JWT 的结构一个 JSON Web 令牌 (JWT) 包含三个部分

1 标头

145


2 Payload3 签名

111111111112222222222233333333333

这些部分以 base64url 字符串的格式编码并且用点 () 字符分隔如果您的 JWT 不符合此结构请将其视为无效且不得接受它

第 2 步验证 JWT 签名JWT 签名是标头和负载的哈希组合Amazon Cognito 为每个用户池生成两对 RSA 加密密钥其中一对私有密钥用于对令牌进行签名

验证 JWT 令牌的签名

1 解码 ID 令牌

您可以使用 Amazon Lambda 解码用户池 JWT有关更多信息请参阅使用 Lambda 解码并验证Amazon Cognito JWT 令牌

OpenID Foundation 还维护用于处理 JWT 令牌的库列表2 比作本地密钥 ID (kid) 公有的孩子

a 下载并存储适用于用户池的对应的公有 JSON Web Key (JWK)它可作为 JSON Web KeySet (JWKS) 的一部分提供您可以在 httpscognito-idp 找到它区域 amazonawscomuserPoolId 知jwksjson

有关更多 JWK 和 JWK 集的更多信息请参阅 JSON Web Key (JWK)

Note

先完成这个一次性步骤然后您的 Web API 操作才可以处理令牌现在每当 ID 令牌或访问令牌用于 Web API 操作时您都可以执行以下步骤

这是一个示例jwksjsonfile

keys [ kid 1234example= alg RS256 kty RSA e AQAB n 1234567890 use sig kid 5678example= alg RS256 kty RSA e AQAB n 987654321 use sig ]

密钥 ID (kid）

这些区域有kid是一个提示指示哪些密钥用于保护令牌的 JSON Web Signature (JWS)

146

Amazon Cognito 开发人员指南在登录后访问资源

算法 (alg）

这些区域有alg标头参数表示用于保护 ID 令牌的加密算法用户池使用 RS256 加密算法这是一种采用 SHA-256 的 RSA 签名有关 RSA 的更多信息请参阅RSA 加密

密钥类型 (kty）

这些区域有kty参数标识与密钥结合使用的加密算法系列例如在本示例中为 ldquoRSArdquoRSA 指数 (e）

这些区域有e参数包含 RSA 公有密钥的指数值它表示为采用 Base64urlUInt 编码的值RSA 模量 (n）

这些区域有n参数包含 RSA 公有密钥的模数值它表示为采用 Base64urlUInt 编码的值使用 (use）

这些区域有use参数描述了公有密钥的预期用途对于这个示例use值sig表示签名b 搜索公有 JSON Web 密钥以获取kid匹配kid你的智威汤逊

3 使用公有密钥来利用您的 JWT 库验证签名您可能首先需要将 JWK 转换为 PEM 格式本示例采用JWT 和 JWK 格式并且使用 Nodejs 库jsonwebtoken来验证 JWT 签名

Nodejs

var jwt = require(jsonwebtoken)var jwkToPem = require(jwk-to-pem)var pem = jwkToPem(jwk)jwtverify(token pem algorithms [RS256] function(err decodedToken) )

第 3 步验证声明验证 JWT 声明

1 确认该令牌没有过期2 受众 (aud) 声明应与在 Amazon Cognito 用户池中创建的应用程序客户端 ID 匹配3 发布者 (iss) 声明应与您的用户池匹配例如在us-east-1区域将具有以下iss值

httpscognito-idpus-east-1amazonawscomltuserpoolIDgt4 检查 token_use 声明

bull 如果您在 Web API 操作中只接受访问令牌则其值必须为accessbull 如果您只使用 ID 令牌则其值必须为 idbull 如果您同时使用 ID 令牌和访问令牌则 token_use 声明必须为 id 或 access

您现在可以信任该令牌内的声明

在成功进行用户池身份验证后访问资源您的应用程序用户可以通过用户池直接登录也可以通过第三方身份提供商 (IdP) 联合登录用户池管理处理以下令牌的开销从通过 FacebookGoogleAmazon 和苹果进行的社交登录返回的令牌以及从OpenID Connect (OIDC) 和 SAML IIdPs ter 返回的令牌有关更多信息请参阅将令牌与用户池结合使用 (p 139)

147

Amazon Cognito 开发人员指南访问服务器端资源

成功进行身份验证后您的应用程序将收到来自 Amazon Cognito 的用户池令牌您可以使用这些令牌检索Amazon凭证允许您的应用程序访问其他Amazon服务也可以选择使用它们来控制对您自己的服务器端资源或 Amazon API Gateway 的访问


主题bull 在登录后访问服务器端资源 (p 9)bull 使用 API Gateway 和 Lambda 访问资源 (p 148)bull 在登录后使用身份池访问 Amazon 服务 (p 149)

在登录后访问服务器端资源成功进行身份验证后您的 Web 或移动应用程序将收到来自 Amazon Cognito 的用户池令牌您可以使用这些令牌控制对您的服务器端资源的访问您也可以创建用户池组来管理权限以及表示不同类型的用户有关使用组控制资源访问权限的更多信息请参阅向用户池添加组 (p 118)

在为用户池配置域后Amazon Cognito 预置一个托管 Web UI您可使用此 UI 向应用程序添加注册页和登录页使用此 OAuth 20 基础您可以创建自己的资源服务器从而使您的用户能够访问受保护的资源有关更多信息请参阅为您的用户池定义资源服务器 (p 41)


使用 API Gateway 和 Lambda 访问资源您可以允许用户通过 API Gateway 访问您的 APIAPI Gateway 会验证来自成功的用户池身份验证的令牌并使用它们向您的用户授予对资源 (包括 Lambda 函数) 或您自己的 API 的访问权限

148

Amazon Cognito 开发人员指南访问Amazon使用身份池的资源

您可以使用用户池中的组控制使用 API Gateway 的权限方法是将组成员资格映射到 IAM 角色用户所属的组包含在您的 Web 或移动应用程序用户登录时用户池提供的 ID 令牌中有关用户池组的更多信息请参阅向用户池添加组 (p 118)

您可以将您的用户池令牌随请求一起提交到 API Gateway以便 Amazon Cognito 授权方 Lambda 函数进行验证有关 API Gateway 的更多信息请参阅将 API Gateway 与 Amazon Cognito 用户池一起使用

在登录后使用身份池访问 Amazon 服务您可以允许用户使用用用用户池登录然后访问Amazon服务

成功进行身份验证后您的 Web 或移动应用程序将收到来自 Amazon Cognito 的用户池令牌您可以使用这些令牌检索Amazon凭证允许您的应用程序访问其他Amazon服务有关更多信息请参阅AmazonCognito 身份池入门 (联合身份) (p 174)

149


有关使用身份池和用户池组控制对Amazon资源请参阅向用户池添加组 (p 118)和基于角色的访问控制 (p 193)有关身份池和 Amazon Identity and Access Management 的更多信息另请参阅身份池概念(联合身份) (p 180)

使用 Amazon Web Services Management Console设置用户池创建 Amazon Cognito 用户池并记下用户池 ID和应用程序客户端 ID为您的每个客户端应用程序有关创建用户池的更多信息请参阅用户池入门 (p 19)

使用 Amazon Web Services Management Console设置身份池以下过程介绍了如何使用 Amazon Web Services Management Console 将一个身份池与一个或多个用户池和客户端应用程序集成

要配置身份池

1 打开Amazon Cognito 控制台2 选择 Manage Identity Pools (管理身份池)3 选择想要针对其启用 Amazon Cognito 用户池作为提供商的身份池的名称4 在控制面板页上选择编辑身份池5 展开 Authentication providers 部分6 选择 Cognito7 键入用户池 ID8 键入应用程序客户端 ID这必须与您在您的用户池的部分Amazon Web Services Management

ConsoleAmazon Cognito

150


9 如果您有其他应用程序或用户池请选择添加其他提供商并针对每个用户池中的每个应用程序键入用户池 ID 和应用程序客户端 ID

10 如果您没有更多应用程序或用户池要添加请选择保存更改

如果成功您将看到已成功保存更改上控制面板页

将用户池与身份池集成对您的应用程序用户进行身份验证后将用户的身份令牌添加到凭证提供程序中的登录映射中提供程序名称取决于 Amazon Cognito 用户池 ID结构如下所示

cognito-idpltregiongtamazonawscomltYOUR_USER_POOL_IDgt

ltregiongt 的值与用户池 ID 中的区域相同例如cognito-idpus-east-1amazonawscomus-east-1_123456789

JavaScript

var cognitoUser = userPoolgetCurrentUser()

if (cognitoUser = null) cognitoUsergetSession(function(err result) if (result) consolelog(You are now logged in)

Add the Users Id Token to the Cognito credentials login map AWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId YOUR_IDENTITY_POOL_ID Logins cognito-idpltregiongtamazonawscomltYOUR_USER_POOL_IDgt resultgetIdToken()getJwtToken() ) )

Android

cognitoUsergetSessionInBackground(new AuthenticationHandler() Override public void onSuccess(CognitoUserSession session) String idToken = sessiongetIdToken()getJWTToken()

MapltString Stringgt logins = new HashMapltString Stringgt() loginsput(cognito-idpltregiongtamazonawscomltYOUR_USER_POOL_IDgt sessiongetIdToken()getJWTToken()) credentialsProvidersetLogins(logins)

)

iOS - Objective-C

AWSServiceConfiguration serviceConfiguration = [[AWSServiceConfiguration alloc] initWithRegionAWSRegionUSEast1 credentialsProvidernil]AWSCognitoIdentityUserPoolConfiguration userPoolConfiguration = [[AWSCognitoIdentityUserPoolConfiguration alloc] initWithClientIdYOUR_CLIENT_ID clientSecretYOUR_CLIENT_SECRET poolIdYOUR_USER_POOL_ID]

151

Amazon Cognito 开发人员指南用户池控制台参考

[AWSCognitoIdentityUserPool registerCognitoIdentityUserPoolWithConfigurationserviceConfiguration userPoolConfigurationuserPoolConfiguration forKeyUserPool]AWSCognitoIdentityUserPool pool = [AWSCognitoIdentityUserPool CognitoIdentityUserPoolForKeyUserPool]AWSCognitoCredentialsProvider credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionTypeAWSRegionUSEast1 identityPoolIdYOUR_IDENTITY_POOL_ID identityProviderManagerpool]

iOS - Swift

let serviceConfiguration = AWSServiceConfiguration(region USEast1 credentialsProvider nil)let userPoolConfiguration = AWSCognitoIdentityUserPoolConfiguration(clientId YOUR_CLIENT_ID clientSecret YOUR_CLIENT_SECRET poolId YOUR_USER_POOL_ID)AWSCognitoIdentityUserPoolregisterCognitoIdentityUserPoolWithConfiguration(serviceConfiguration userPoolConfiguration userPoolConfiguration forKey UserPool)let pool = AWSCognitoIdentityUserPool(forKey UserPool)let credentialsProvider = AWSCognitoCredentialsProvider(regionType USEast1 identityPoolId YOUR_IDENTITY_POOL_ID identityProviderManagerpool)

用户池参考 (Amazon Web Services ManagementConsole)

您可以根据应用程序的需要自定义用户池设置本节介绍设置的每个类别并为您提供有关属性策略电子邮件和电话验证多重验证应用程序触发器和信任设备的详细信息

主题bull 添加用户池名称 (p 153)bull 导入和创建用户与组 (p 153)bull 配置用户池属性 (p 153)bull 添加用户池密码要求 (p 158)bull 配置ldquo管理员创建用户策略rdquo (p 159)bull 配置电子邮件或电话验证 (p 159)bull 配置 SMS 和电子邮件验证消息以及用户邀请消息 (p 160)bull 将成本分配标签添加到您的用户池 (p 163)bull 指定用户池设备跟踪设置 (p 163)bull 配置用户池应用程序客户端 (p 164)bull 配置用户池 Lambda 触发器 (p 165)bull 查看您的用户池创建设置 (p 165)bull 配置用户池分析 (p 166)bull 配置应用程序客户端设置 (p 167)bull 为用户池添加域名 (p 167)bull 自定义内置应用程序 UI 以便注册用户和让用户登录 (p 168)bull 为用户池添加资源服务器 (p 168)bull 为用户池配置身份提供商 (p 168)bull 为用户池配置属性映射 (p 171)

152

Amazon Cognito 开发人员指南用户池名称

添加用户池名称您必须指定池名称对于 Amazon Cognito 用户池的Amazon Web Services Management Console用户池的名称在创建后将无法更改

池名称的长度必须介于 1 到 128 个字符之间它们可以包含大写和小写字母 (a-zA-Z)数字 (0-9) 和以下特殊字符+ = -

导入和创建用户与组在用户和组选项卡上您可以导入用户创建用户创建组并将用户分配到其中以及搜索用户

有关更多信息请参阅

bull 通过 CSV 文件将用户导入用户池中 (p 125)bull 向用户池添加组 (p 118)bull 以管理员身份创建用户账户 (p 115)

配置用户池属性您将获得一组适用于所有用户池的默认属性称为ldquo标准属性rdquo您也可以在 Amazon Web ServicesManagement Console 中为您的用户池定义添加自定义属性本主题将详细介绍这些属性并为您提供有关如何设置用户池的提示

属性是各种条目的信息用于帮助您标识单个用户如名称电子邮件和电话号码

并非所有与用户相关的信息都应存储在属性中例如频繁变化的用户数据 (如使用情况统计数据或游戏分数) 应当保存在单独的数据存储 (如 Amazon Cognito Sync 或 Amazon DynamoDB) 中

标准属性以下是适用于用户池中所有用户的标准属性这些属性是按照 OpenID Connect 规范来实施的

bull address

bull birthdate

bull email

bull family_name

bull gender

bull given_name

bull locale

bull middle_name

bull name

bull nickname

bull phone_number

bull picture

bull preferred_username

bull profile

bull updated_at

bull website

153

Amazon Cognito 开发人员指南Attributes

bull zoneinfo

这些属性作为所有用户的可选属性提供要将某个属性设置为必需属性请选中该属性旁的复选框

Note

如果某个标准属性被标记为必需属性则用户必须为该属性提供一个值才能注册通过使用AdminCreateUser API管理员无需为必需属性提供值就可以创建用户在用户池创建完成后属性就不能在必需与非必需之间切换

默认情况下标准和自定义属性值可以是任何不超过 2048 个字符的字符串但是某些属性值（例如updated_at）有格式限制只能验证电子邮件和电话

Note

在此规范中属性被称为成员

以下是有关上述某些字段的一些附加说明

email

电子邮件地址值可以进行验证

具有适当的管理员Amazon帐户权限可以更改用户的电子邮件并将其标记为已验证这一操作可通过使用 AdminUpdateUserAttributes API 或 admin-update-user-attributes CLI 命令将 email_verified属性更改为 true 来完成

phone

如果启用了 SMS 多重验证 (MFA)则电话号码为必需属性有关更多信息请参阅向用户池添加多重验证 (MFA) (p 300)

电话号码值可以进行验证

具有适当的管理员Amazon帐户权限可以更改用户的电话号码并将其标记为已验证这一操作可通过使用 AdminUpdateUserAttributes API 或 admin-update-user-attributes CLI 命令将phone_number_verified 属性更改为 true 来完成

Important

电话号码必须遵循以下格式规则电话号码必须以加号开头 (+) 符号后面紧跟国家地区代码电话号码只能包含 + 号和数字您必须先删除电话号码中的任何其他字符如圆括号空格或短划线 (-)然后才能将该值提交给服务例如美国境内的电话号码必须遵循以下格式+14325551212

preferred_username

不能同时将 preferred_username 选为必需属性和别名如果 preferred_username 是一个别名用户可以通过使用 UpdateUserAttributes API 进行确认后再添加属性值

编辑标准属性

1 在属性选项卡上选择用户注册所需的属性如果某个属性为必需属性则用户在未提供该必需属性的情况下将无法注册

Important

在创建用户池后将无法更改这些要求

154


2 要为电子邮件电话号码地址或首选用户名创建别名请选择别名有关别名的更多信息请参阅别名概述 (p 155)

3 继续创建自定义属性 (p 157)

用户名和首选用户名username 值是一个单独的属性与 name 属性不同在注册用户时username 始终为必需项并且在用户创建后无法更改

开发人员可以使用 preferred_username 属性让用户设置一个可以更改的用户名有关更多信息请参阅别名概述 (p 155)

如果您的应用程序不需要用户名就不必要求用户提供用户名您的应用程序可以在后台为用户创建唯一的用户名这非常有用例如当您希望用户使用电子邮件地址和密码注册和登录时有关更多信息请参阅别名概述 (p 155)

在用户池中username 必须是唯一的username 可重复使用但只能是在已删除且不再使用的情况下

别名概述您可以允许最终用户通过使用别名使用多个标识符登录

默认情况下用户使用他们的用户名和密码登录用户名是一个固定值用户无法更改如果您将某个属性标记为别名用户就可以使用该属性代替用户名来登录电子邮件地址电话号码和首选用户名属性都可以标记为别名

例如如果电子邮件和电话被选为用户池的别名该用户池中的用户就可以将用户名电子邮件地址或电话号码与密码一起使用进行登录

Note

当您将用户池配置为不区分用户名大小写时您可以选择在别名中使用小写或大写字母登录或注册有关更多信息请参阅 CreateUserPool中的Amazon Cognito 用户池 API 参考

如果电子邮件被选为别名用户名将无法匹配有效的电子邮件格式同样如果电话号码被选为别名该用户池的服务将不接受与有效的电话号码模式相匹配的用户名

Note

在用户池中别名值必须是唯一的如果为电子邮件地址或电话号码配置了别名那么提供的值只能在一个账户中处于已验证状态在注册期间如果电子邮件地址或电话号码从一个已被使用的其他账户中作为别名提供注册会成功然而当用户尝试使用此电子邮件 (或电话号码) 确认账户并输入有效的代码时会引发 AliasExistsException 错误该错误向用户指出已存在使用此电子邮件 (或电话号码) 的账户此时用户可以放弃新账户的创建然后尝试重置旧账户的密码如果用户继续创建新账户您的应用程序应使用 ConfirmSignUp 选项调用 forceAliasCreationAPI这会将别名从以前的账户移至新创建的账户还会将该属性在以前的账户中标记为未经验证

电话号码和电子邮件地址只有经过验证之后才能成为用户的有效别名因此如果您将电子邮件地址和电话号码用作别名我们建议您选择对其进行自动验证使用 preferred_username 属性用户便可拥有更改用户名的体验但实际上用户的实际用户名值不可更改

如果您想实现这种用户体验请提交新的 username 值作为 preferred_username并选择preferred_username 作为别名这样用户就可以使用输入的新值登录

如果选择 preferred_username 作为别名只有在确认账户后才能提供该值在注册期间无法提供该值

155


使用别名简化用户注册信息和登录在属性控制台选项卡中您可以选择是否允许用户使用电子邮件地址或电话号码作为其用户名登录

Note

创建用户池后此设置无法更改

主题bull 选项 1用户使用用户名注册并使用用户名或别名登录 (p 156)bull 选项 2用户使用电子邮件或电话号码注册和登录而不是用户名 (p 156)

选项 1用户使用用户名注册并使用用户名或别名登录

在这种情况下用户使用用户名注册此外您可以选择性地允许用户使用以下一个或多个别名登录

bull 经过验证的电子邮件地址bull 经过验证的电话号码bull 首选的用户名

用户注册后可以更改这些别名

使用以下步骤在控制台中配置您的用户池以允许使用别名登录

配置用户池使用别名登录

1 在属性选项卡中在您希望您的最终用户如何注册和登录中选择用户名2 请选择以下任一选项

bull 还允许使用已验证的电子邮件地址登录此选项允许用户使用其电子邮件地址进行登录bull 还允许使用已验证的电话号码登录此选项允许用户使用其电话号码进行登录bull 还允许使用首选用户名登录此选项允许用户使用首选的用户名进行登录用户可以更改此用户名

选项 2用户使用电子邮件或电话号码注册和登录而不是用户名

在这种情况下用户使用电子邮件地址或电话号码作为其用户名注册您可以选择是否允许仅使用电子邮件地址仅使用电话号码或使用任意一项进行注册

电子邮件或电话号码必须是唯一的并且不能已被其他用户使用它不必经过验证用户使用电子邮件或电话号码注册之后用户将无法使用相同的电子邮件或电话号码创建新账户用户只能重复使用现有的账户(并在必要时重置密码)但是用户可以将电子邮件或电话号码更改为新的电子邮件或电话号码如果未被使用它将成为新的用户名

Note

如果用户使用电子邮件地址作为用户名注册则可以将用户名更改为另一个电子邮件地址他们无法将用户名更改为电话号码如果用户使用电话号码注册他们可以将用户名更改为另一个电话号码他们无法将用户名更改为电子邮件地址

使用以下步骤在控制台中配置您的用户池以允许使用电子邮件或电话号码注册和登录

配置用户池使用电子邮件或电话号码注册和登录

1 在属性选项卡中的您希望您的最终用户如何注册和登录下选择电子邮件地址或电话号码

156



bull 允许电子邮件地址此选项允许用户使用电子邮件作为用户名注册bull 允许电话号码此选项允许用户使用电话号码作为用户名注册bull 同时允许电子邮件地址和电话号码（用户可以选择一个）此选项允许用户在注册过程中使用电子邮

件地址或电话号码作为用户名

Note

您不需要将电子邮件或电话号码标记为用户池的必需属性

在应用程序中实施选项 2

1 调用 CreateUserPool API以创建用户池将 UserNameAttributes 参数设置为phone_numberemail 或 phone_number | email

2 调用 SignUp API 并在 API 的 username 参数中传递电子邮件地址或电话号码此 API 可执行以下操作

bull 如果 username 字符串采用有效的电子邮件格式用户池将使用 email 值自动填充用户的username 属性

bull 如果 username 字符串采用有效的电话号码格式用户池将使用 phone_number 值自动填充用户的username 属性

bull 如果 username 字符串格式不是电子邮件或电话号码格式SignUp API 将引发异常bull SignUp API 为用户生成一个持久性 UUID并将其作为内部不可变的用户名属性此 UUID 与用户身

份令牌中的 sub 声明具有相同的值bull 如果 username 字符串包含已被使用的电子邮件地址或电话号码SignUp API 将引发异常

您可以使用电子邮件地址或电话号码作为别名在除 ListUsers API 之外的所有 API 中代替用户名当您调用 ListUsers 时您可以按 email 或 phone_number 属性搜索如果您按 username 搜索则必须提供实际的用户名而不是别名

自定义属性您可以将最多 25 个自定义属性添加到您的用户池您可以为自定义属性指定一个最小和或最大长度但是任何自定义属性的最大长度不能超过 2048 个字符

每个自定义属性

bull 可以定义为一个字符串或数字bull 不能是必需的bull 一旦添加到用户池就不能删除或更改bull 可以有一个名称此名称的字符长度符合 Amazon Cognito 接受的限制有关更多信息请参阅 Amazon

Cognito 中的配额 (p 317)

Note

在您的代码和基于角色的访问控制 (p 193) 的规则设置中自定义属性需要使用 custom 前缀以便将它们与标准属性区分开来

使用控制台添加自定义属性

1 在左侧的导航栏中选择属性2 对于每个新属性

157

Amazon Cognito 开发人员指南密码要求

a 选择是否要添加自定义属性下的添加其他属性b 为每个自定义属性选择特性例如数据类型（字符串或数字）名称最小长度和最大长度c 如果您想让用户能够在为自定义属性提供值后更改该值请选择可变

属性权限和范围您可以为每个用户属性设置每个应用程序的读取和写入权限这使您能够控制哪些应用程序可以对存储的每个用户属性进行查看和或修改例如您可以设置一个自定义属性用于指明用户是否为付费客户您的应用程序可以查看此属性但无法直接修改相反您可以使用管理工具或后台进程更新此属性可以通过Amazon Cognito 控制台API 或 CLI 设置用户属性的权限默认情况下任何新的自定义属性都不可用直到您为其设置读取和写入权限

使用控制台设置或更改属性权限

1 在左侧的导航栏中选择应用程序客户端2 为要更新的应用程序客户端选择显示详细信息3 选择为每个属性设置属性读取和写入权限4 选择保存应用程序客户端更改

使用自定义属性对每个应用程序客户端重复这些步骤

可以针对每个应用程序将属性标记为可读或可写这对于标准属性和自定义属性均适用应用程序可以读取标记为可读的属性也可以编写标记为可写的属性如果应用程序尝试更新不可写的属性就会收到NotAuthorizedException 异常当应用程序调用 GetUser 时只能收到该应用程序可读的属性经过身份验证后发出的 ID 令牌仅包含与可读属性相对应的声明用户池上的必需属性始终为可写属性如果您使用 CLI 或管理 API 来设置可写属性但不提供必需属性就会引发 InvalidParameterException 异常

您可以在创建用户池后更改属性权限和范围

添加用户池密码要求指定至少包含 8 个字符的最小密码长度要求包含大写字母数字和特殊字符以便为您的应用程序用户创建强密码复杂的密码更难被猜中因此我们建议您将复杂密码作为一项最佳安全做法

密码中允许使用以下字符

bull 大写字母和小写字母bull 数字bull 在下一部分中列出的特殊字符

创建密码策略您可以在 Amazon Web Services Management Console 中指定以下密码要求

bull Minimum length必须至少包含 6 个字符不超过 99 个字符bull Require numbersbull Require a special character (需要特殊字符)该字符来自以下字符集

= + - ^ $ [ ] ( ) amp gt lt | _ ~ `

bull 所需大写字母bull 所需小写字母

158

Amazon Cognito 开发人员指南管理员创建用户策略

配置ldquo管理员创建用户策略rdquo您可以为管理员创建用户指定以下策略

bull 指定是否允许用户自己注册默认情况下设定此选项如果未设定则只有管理员才能在该池中创建用户并且对 SignUp API 的调用会失败并引发 NotAuthorizedException

bull 为新账户指定用户账户到期时间限制 (以天为单位)从用户账户的创建时间开始计算默认设置为 7 天最大设置为 90 天账户到期后在管理员通过更新属性或重新给用户发送密码来更新用户的配置文件之前用户无法登录账户

Note


配置电子邮件或电话验证您可以在 MFA and verifications (MFA 和验证) 选项卡中选择电子邮件或电话验证的设置有关 MFA 的更多信息请参阅SMS 文本消息 MFA (p 301)

Amazon Cognito 使用 Amazon SNS 发送 SMS 文本消息如果您从未从 Amazon Cognito 或任何其他Amazon服务时Amazon SNS 可能会将您的帐户置于 SMS 沙箱中Amazon建议您先测试将消息发送到已验证的电话号码然后再将您的帐户从沙箱移除到生产环境此外如果您计划向美国目的地电话号码发送SMS 消息则必须从 Amazon Pinpoint 获取发件人 ID 或发件人 ID要配置 SMS 的 Amazon Cognito 用户池请参阅Amazon Cognito 用户池的 SMS 消息设置 (p 137)

Amazon Cognito 可以通过发送验证码来自动验证电子邮件地址或手机号码对于电子邮件则发送验证链接对于电子邮件地址将通过电子邮件发送代码或链接对于电话号码则以 SMS 文本消息形式发送代码

如果用户忘记了密码电话或电子邮件验证对于自动确认用户并启用恢复是必不可少的或者您也可以通过预注册 Lambda 触发或使用AdminConfirmSignUpAPI有关更多信息请参阅注册并确认用户账户 (p 109)

验证代码或链接的有效期为 24 小时

如果选择了必须进行电子邮件或电话验证则在用户注册时将自动发送验证代码或链接

Notes

bull 使用 SMS 文本消息来验证电话号码由 Amazon SNS 另行收费(向电子邮件地址发送验证代码是不收费的) 有关 Amazon SNS 定价的信息请参阅SMS 全球定价有关提供 SMS 消息发送服务的最新国家地区列表请参阅支持的区域和国家地区

bull 当您测试应用程序中的从 Amazon Cognito 发送电子邮件的操作时请使用 Amazon Cognito 可以发送到而不会生成硬退回的真实电子邮件地址有关更多信息请参阅 the section called ldquo在测试应用程序时发送电子邮件rdquo (p 115)

bull 忘记密码流程要求验证用户的电子邮件或电话号码

Important

如果用户同时使用电话号码和电子邮件地址注册且用户池设置需要验证这两个属性验证代码会通过 SMS 发送到手机上电子邮件地址未经验证因此您的应用程序需要调用 GetUser 以查看电子邮件地址是否在等待验证如果是则该应用程序应调用 GetUserAttributeVerificationCode 来启动电子邮件验证流然后通过调用 VerifyUserAttribute 提交验证代码

支出限制可以指定Amazon帐户和单个消息且该限额仅适用于发送 SMS 消息的费用有关更多信息请参阅 Amazon SNS 常见问题解答

159

Amazon Cognito 开发人员指南消息自定义

除非下表说明否则来自 Amazon Cognito 用户池的 SMS 消息将通过同一地区的 Amazon SNS 路由

Amazon Cognito 地区支持的 SNS 区域

美国东部（俄亥俄）us-east-2 us-east-1

亚太地区（孟买）ap-south-1 ap-southeast-1

亚太地区（首尔）ap-northeast-2 ap-notheast-1

加拿大（中部）ca-central-1 us-east-1

欧洲（法兰克福）eu-central-1 eu-west-1

欧洲（伦敦）eu-west-2 eu-west-1

例如如果您的 Cognito 用户池位于美国东部 1 区域您可以在美国东部 1 区域更新 Amazon SNS 限制

例如如果您的 Cognito 用户池位于 AP-南1 区域您可以在东南 1 区域更新 Amazon SNS 限制

授权 Amazon Cognito 代表您发送 SMS 消息要代表您向您的用户发送 SMS 消息Amazon Cognito 需要您的权限要授予该权限您可以创建AmazonIdentity and Access Management(IAM) 角色MFA 和验证选项 Amazon Cognito 方法是选择创建角色

配置 SMS 和电子邮件验证消息以及用户邀请消息在消息自定义选项卡中您可以自定义

bull 您的 SMS 文本消息 MFA 消息bull 您的 SMS 和电子邮件验证消息bull 电子邮件的验证类型-代码或链接bull 您的用户邀请消息bull 流经用户池的电子邮件的 From 和 Reply-To 电子邮件地址

Note

只有在验证选项卡上选择要求进行电话号码和电子邮件验证之后才会显示 SMS 和电子邮件验证消息模板同样只有 MFA 设置为ldquoREQUIREDrdquo或ldquoOPTIONALrdquo时才会显示 SMS MFA 消息模板

主题bull 消息模板 (p 160)bull 自定义 SMS 消息 (p 161)bull 自定义电子邮件验证消息 (p 162)bull 自定义用户邀请消息 (p 162)bull 自定义您的电子邮件地址 (p 162)bull 授权 Amazon Cognito 代表您发送 Amazon SES 电子邮件 (从自定义 FROM 电子邮件地址) (p 162)

消息模板消息模板允许您使用占位符 (将被相应值替换) 在消息中插入一个字段

160


模板占位符

描述 Token

验证代码

临时密码

用户名 username

Note

不能在验证电子邮件中使用 usernameusername 可在 AdminCreateUser 调用后发送的邀请电子邮件中使用这些邀请电子邮件提供两种占位符用户名 username 和临时密码

您可以使用高级安全模板占位符

bull 包括某个事件的特定详细信息 (如 IP 地址城市国家地区登录时间设备名称)用于供 AmazonCognito 的高级安全功能进行分析

bull 验证一键式链接是否有效bull 使用事件 ID反馈令牌和用户名构建您自己的一键式链接

高级安全模板占位符

描述 Token

IP 地址 ip-address

城市 city

国家地区 country

登录时间登录时间

设备名称设备名称

一键式链接有效一键式链接有效

一键式链接无效一键式链接无效

事件 ID 事件 id

反馈令牌反馈令牌

自定义 SMS 消息您可以通过编辑是否要自定义您的 SMS 消息标题下的模板来自定义用于 MFA 身份验证的 SMS 消息

Important

您的自定义消息必须包含占位符该占位符会在消息发送之前替换为身份验证代码

消息的最大长度为 140 个 UTF-8 字符其中包括身份验证代码

自定义 SMS 验证消息

您可以通过编辑是否要自定义您的 SMS 验证消息标题下的模板来自定义用于电话号码验证的 SMS 消息

161


Important

您的自定义消息必须包含占位符该占位符会在消息发送之前替换为验证代码

消息的最大长度为 140 个 UTF-8 字符其中包括验证代码

自定义电子邮件验证消息您可以选择电子邮件验证的验证类型代码或链接

您可以通过编辑是否要自定义您的电子邮件验证消息标题下的模板来自定义用于电子邮件地址验证的电子邮件主题和消息

Important

如果您选择了代码作为验证类型则您的自定义消息必须包含占位符在发送消息之前将会用验证代码替换占位符

消息的最大长度为 20000 个 UTF-8 字符其中包括验证代码 (如果存在)可以在这些电子邮件中使用HTML 标签

自定义用户邀请消息您可以通过编辑 Amazon Cognito 通过 SMS 或电子邮件发送给新用户的用户邀请消息方法是编辑是否要自定义用户邀请消息标题

Important

您的自定义消息必须包含 username 和占位符这些占位符会在消息发送之前替换为该用户的用户名和密码

SMS 的最大长度为 140 个 UTF-8 字符其中包括验证码对于电子邮件消息的最大长度为 20000 个UTF-8 字符其中包括验证代码可以在这些电子邮件中使用 HTML 标签

自定义您的电子邮件地址默认情况下Amazon Cognito 向您的用户池中的用户发送的电子邮件消息来自no-replyverificationemailcom您可以指定要使用的自定义 FROM 和 REPLY-TO 电子邮件地址来代替 no-replyverificationemailcom

要自定义 FROM 电子邮件地址请在控制台中选择一个用户池接下来选择 Message customizations (邮件自定义)在 Message customizations (邮件自定义) 中选择 SES Region (SES 区域)在 FROM emailaddress ARN (FROM 电子邮件地址 ARN) 字段中输入您的电子邮件地址通过选择发件人电子邮件地址ARN 字段有关更多信息请参阅在 Amazon SES 中验证电子邮件地址和域中的Amazon Simple EmailService 开发人员指南

要自定义 REPLY-TO 电子邮件地址请在 REPLY-TO email address (REPLY-TO 电子邮件地址) 字段中输入有效的电子邮件地址

授权 Amazon Cognito 代表您发送 Amazon SES 电子邮件 (从自定义 FROM 电子邮件地址)如果您要从自定义 (而不是默认的) FLOM 电子邮件地址发送电子邮件Amazon Cognito 需要您的权限来代表您的 Amazon SES 验证身份向用户发送电子邮件消息要授予该权限请创建发送授权策略有关更多信息请参阅使用 Amazon SES 的发送授权中的Amazon Simple Email Service 开发人员指南

162

Amazon Cognito 开发人员指南标签

下面是 Amazon SES 为 Amazon Cognito 用户池发送授权策略的一个示例有关更多示例请参阅AmazonSES 发送授权策略示例中的Amazon Simple Email Service 开发人员指南

Note

在此示例中ldquoSidrdquo值为唯一标识语句的任意字符串有关策略语法的更多信息请参阅AmazonSES 发送授权策略中的Amazon Simple Email Service 开发人员指南


当您从下拉菜单中选择 Amazon SES 身份时Amazon Cognito 控制台会为您添加此策略如果您使用 CLI或 API 来配置用户池则必须将此策略附加到您的 Amazon SES 身份中

将成本分配标签添加到您的用户池在标签选项卡中您可以添加成本分配标签对 Amazon 成本进行分类和跟踪将标签应用到Amazon资源（例如 Amazon Cognito 用户池）Amazon成本分配报告包括按标签汇总的使用率和成本您可以应用代表业务类别（如成本中心应用程序名称或所有者）的标签以便在多项服务中组织您的成本有关更多信息请参阅 Amazon Billing and Cost Management 用户指南中的使用成本分配标签

要添加标签请选择添加标签指定标记密钥和标签值遵循标签限制选择保存更改以保存您的标签

Important

为了使标签显示在您的账单报告上您必须在账单控制台中激活您应用的标签有关更多信息请参阅激活用户定义的成本分配标签中的Amazon Billing and Cost Management用户指南

指定用户池设备跟踪设置作为进一步提高安全性的一种方式您可以跟踪用户登录的设备本主题介 Amazon Cognito 何在AmazonWeb Services Management Console

设置记忆设备借助 Amazon Cognito 用户池您可以选择让 Amazon Cognito 记住用于访问您的应用程序的设备并在用户池中将这些记住的设备与应用程序用户关联如果您设置了多重验证 (MFA)还可以选择使用记忆设备来停止向用户发送代码

通过 Amazon Cognito 控制台设置记忆设备功能时您有三种选择ALWAY用户选择加入和否

bull No (默认值) - 不记住设备bull Always - 记住应用程序用户使用的每台设备

163

Amazon Cognito 开发人员指南应用程序客户端

bull User Opt-In - 只有当您的用户选择记住设备时该设备才会被记住

如果选择了始终或用户选择加入那么对于每台设备系统都会在用户首次使用该设备登录时为其分配一个设备标识符（键和密钥）除了识别设备此密钥不会用于其他任何地方但会被服务跟踪

如果您选择ALWAYAmazon Cognito 将使用设备标识符 (密钥和私有密钥) 在每个用户使用设备登录时对该设备进行身份验证

如果您选择用户选择加入则只有当应用程序的用户选择记住设备时您才能记住该设备当用户使用新设备登录时请求启动跟踪的响应将指示是否应该提示用户记住他们的设备您必须创建用户界面来提示用户如果用户选择记住设备则系统会将设备状态更新为ldquo已记住rdquo状态

这些区域有Amazon移动软件开发工具包还有其他 API 来查看记住的设备（ListDevicesGetDevice）请将设备标记为已记住或未记住（UpdateDeviceStatus）并停止跟踪设备（ForgetDevice)在 REST API中还提供了这些 API 的管理员版本这些版本的 API 具备提升的权限适用于任何用户它们的 API 名称分别为 AdminListDevicesAdminGetDevice等等它们不通过开发工具包提供

使用记忆设备停止多重验证 (MFA)如果您选择了始终或用户选择加入则还可以选择为应用程序的用户在记住的设备上停止 MFA 质询要使用此功能您必须为您的用户池启用 MFA有关更多信息请参阅向用户池添加多重验证(MFA) (p 300)

Note

如果设备记住功能设置为始终并且是否要使用记忆设备隐藏多重验证 (MFA) 的第二安全要素设置为是则在基于风险的 MFA 中会忽略中高风险的 MFA 设置

配置用户池应用程序客户端应用程序是用户池中的一个实体它有权调用未经身份验证的 API 操作 (没有经过身份验证的用户的操作)示例包括注册登录和处理忘记密码的操作要调用这些 API 操作您需要应用程序客户端 ID 和可选的客户端私有密钥您有责任确保任何应用程序客户端 ID 或密钥的安全以便只有经过授权的客户端应用程序才能调用这些未经身份验证的操作

您可以为用户池创建多个应用程序通常应用程序对应于应用程序的平台例如您可以为服务器端应用程序和其他 Android 应用程序创建一个应用程序每个应用程序都有各自的应用程序客户端 ID

创建应用程序时您可以选择为该应用程序创建一个私有密钥如果为应用程序创建了一个私有密钥则必须提供该私有密钥才能使用应用程序使用 JavaScript 编写的基于浏览器的应用程序可能不需要带有私有密钥的应用程序

私有密钥在应用程序创建后即无法更改如果您要轮换正在使用的私有密钥可以创建一个具备新私有密钥的新应用程序您也可以删除应用程序以便阻止使用该应用程序客户端 ID 的应用程序的访问

创建应用程序客户端（控制台）

1 在用户池仪表板上选择创建用户池2 输入池名称3 选择 Review defaults4 选择添加应用程序客户5 选择 Add an app client6 输入App 客户端名称7 指定应用程序的刷新令牌过期默认值是 30您可以将其更改为 1 小时到 10 年之间的任何值8 指定应用程序的访问令牌过期默认值为 1 小时您可以将其更改为 5 分钟到 24 小时之间的任何值9 指定应用程序的ID 令牌过期默认值为 1 小时您可以将其更改为 5 分钟到 24 小时之间的任何值

164

Amazon Cognito 开发人员指南触发

Important

如果您使用托管 UI 并设置令牌不到一小时最终用户将能够根据其会话 cookie 获取新令牌该 cookie 当前固定在一小时内

10 默认情况下用户池会为您的应用程序生成一个客户端密钥如果您不希望出现这种情况请清除生成客户端密钥

11 如果您的服务器应用需要开发人员凭据（使用签名版本 4）并且不使用安全远程密码 (SRP) 身份验证选择启用用于身份验证的管理 API 的用户名密码身份验证（允许 _ 管理员 _ 用户 _ 密码 _ 身份验证）以启用服务器端身份验证有关更多信息请参阅管理员身份验证流程 (p 288)

12 Unth防止用户存在错误中选择传统或者Enabled (已启用)有关更多信息请参阅管理错误响应13 默认情况下用户池会允许您的应用程序读取和写入所有属性如果您要为应用程序设置不同的权限

请执行以下步骤或选择Create app 客户端以完成操作

a 选择设置属性读取和写入权限b 请执行以下任一操作来设置读取和写入权限

bull 选择一个或多个范围每个范围都是一组标准属性有关更多信息请参阅标准 OIDC 范围列表

bull 选择单个标准或自定义属性

Note

您无法删除任何应用程序中写入权限的必需属性14 选择 Create app client15 如果您希望创建另一个应用程序请选择添加应用程序16 创建完您需要的所有应用程序后选择返回池详细信息更新任何其他字段然后选择创建池

要在用户池中创建和更新应用程序客户端（APIAmazon CLI）

请执行下列操作之一

bull APImdash 使用CreateUserPoolClient和UpdateUserPoolClient操作bull Amazon CLImdash 在命令行处运行create-user-pool-client和update-user-pool-client命令

配置用户池 Lambda 触发器您可以使用Amazon Lambda触发器自定义工作流和 Amazon Cognito 用户体验您可以创建以下 Lambda触发器注册前身份验证前自定义消息身份验证后确认后定义身份验证质询创建身份验证质询验证身份验证质询响应和用户迁移

可使用用户迁移 Lambda 触发器轻松地将用户从现有用户管理系统迁移到您的用户池

有关每个 Lambda 触发器的示例请参阅使用 Lambda 触发器自定义用户池工作流 (p 63)Note

自定义消息 Amazon Lambda 触发器是自定义电子邮件和 SMS 消息的一种高级方式有关更多信息请参阅使用 Lambda 触发器自定义用户池工作流 (p 63)

查看您的用户池创建设置创建用户池之前您可以在 Amazon Web Services Management Console 中查看不同的设置并对其进行编辑Amazon Cognito 将验证用户池设置并提醒您是否需要更改例如

165

Amazon Cognito 开发人员指南分析

Warning

该用户池没有定义 IAM 角色无法允许 Amazon Cognito 发送 SMS 消息因此在 2016 年 8 月 31日以后就无法对电话号码或 MFA 进行确认您可以通过在 Verifications 面板上选择一个角色来定义 IAM 角色

如果您看到一条消息请按照说明解决相应的问题然后再选择创建池

配置用户池分析Note

只有在您编辑现有用户池时才会显示分析选项卡

使用 Amazon Pinpoint 分析您可以跟踪 Amazon Cognito 用户池的注册登录失败的身份验证日活跃用户 (DAU) 和月活跃用户 (MAU)您还可以使用Amazon Mobile SDK for Android或Amazon Mobile SDK foriOS设置特定于您的应用程序的用户属性然后可以使用这些属性在 Amazon Pinpoint 中对用户进行细分并向他们发送有针对性的推送通知

在分析选项卡上您可以为 Amazon Cognito 应用程序客户端指定 Amazon Pinpoint 项目有关更多信息请参阅将 Amazon Pinpoint 分析与 Amazon Cognito 用户池结合使用 (p 107)

Note

Amazon Pinpoint 可在多个Amazon北美欧洲亚洲和大洋洲的区域Amazon Pinpoint 区域包括 Amazon Pinpoint API如果 Amazon Cognito 支持亚马逊 Pinpoint 地区那么 AmazonCognito 会将事件发送到相同Amazon Pinpoint 区域如果区域不是由 Amazon Pinpoint 支持那么Amazon Cognito 将仅限支持在 us-east-1 中发送事件有关 Amazon Pinpoint 详细地区信息请参阅Amazon Pinpoint 终端节点和配额和将 Amazon Pinpoint 分析与 Amazon Cognito 用户池结合使用

添加分析和市场活动

1 选择添加分析和活动2 从列表中选择 Cognito app client3 要将您的 Amazon Cognito 应用程序映射到Amazon Pinpoint 项目中从列表中选择 Amazon Pinpoint

项目Note

Amazon Pinpoint 项目 ID 是 Amazon Pinpoint 项目特有的由 32 个字符组成的字符串它被列出 Amazon Pinpoint 控制台您可以将多个 Amazon Cognito 应用程序映射到单个 Amazon Pinpoint 项目但是每个Amazon Cognito 应用程序只能映射到一个 Amazon Pinpoint 项目在 Amazon Pinpoint 中每个项目都应该是单个应用程序例如如果游戏开发人员有两款游戏则每款游戏都应是单独的 Amazon Pinpoint 项目即使两款游戏使用同一 AmazonCognito 用户池

4 选择与 Amazon Pinpoint 共享用户属性数据如果您希望 Amazon Cognito 向 Amazon Pinpoint 发送电子邮件地址和电话号码以便为用户创建额外的终端节点

Note

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的终端节点唯一地标识可以使用Amazon Pinpoint 向其发送推送通知的用户设备有关终端节点的更多信息请参阅添加终端节点中的Amazon Pinpoint 开发人员指南

5 输入IAM 角色或选择创建新角色在 IAM 控制台中创建新角色6 选择保存更改7 要指定额外的应用程序映射请选择添加应用程序映射8 选择保存更改

166

Amazon Cognito 开发人员指南应用程序客户端设置

配置应用程序客户端设置Note

这些区域有常规设置选项卡仅在您编辑现有用户池时才会显示

在存储库的常规设置选项卡上如果您希望使用内置托管页面注册和登录用户或者希望使用 OAuth20流则必须至少为应用程序配置一个身份提供商 (IdP)有关更多信息请参阅配置用户池应用程序客户端 (p 30)

为用户池指定应用程序客户端设置

1 在 Enabled Identity Providers 中为您在 App Clients 选项卡中配置的应用程序选择您所需的身份提供商

2 输入回调 URL你想要的用逗号分隔这些 URL 应用到所有选定的身份提供商Note

您必须先在控制台中或者使用 CLI 或 API 来注册 URL然后才能在应用程序中使用它们3 输入您所需的 Sign out URLs (以逗号分隔)

Note

您必须先在控制台中或者使用 CLI 或 API 来注册 URL然后才能在应用程序中使用它们4 UnthOauth 20请从以下选项中选择有关更多信息请参阅应用程序客户端设置 (p 32) 和

OAuth 20 规范

bull 适用于允许的 OAuth 流程选择授予授权代码和隐式授予只有在您的应用程序需要代表自己而不是代表用户请求访问令牌时才选择 Client credentials

bull 适用于允许的 OAuth 范围中选择您所需的范围每个范围是包含一个或多个标准属性的集合bull 适用于允许的自定义范围下从您定义的任何自定义范围中选择您所需的范围自定义范围是在资源

服务器选项卡有关更多信息请参阅为您的用户池定义资源服务器 (p 41)

为用户池添加域名Note

只有在您编辑现有用户池时才会显示域名选项卡

在域名选项卡上您可以输入自己的前缀域名您应用程序的域为httpsltdomain_prefixgtauthltregiongtamazoncognitocom

您的应用程序的完整 URL 类似于此示例httpsexampleauthus-east-1amazoncognitocomloginredirect_uri=httpswwwgooglecomampresponse_type=codeampclient_id=ltclient_id_valuegt

有关更多信息请参阅配置用户池域 (p 33)Important

您必须先指定应用程序客户端设置 (例如回调和重定向 URL)然后才能访问应用程序的 URL有关更多信息请参阅配置应用程序客户端设置 (p 167)

为用户池指定域名

1 在前缀域名框中输入您所需的域名2 根据需要选择检查可用性3 选择保存更改

167

Amazon Cognito 开发人员指南UI 自定义

自定义内置应用程序 UI 以便注册用户和让用户登录Note

只有在您编辑现有用户池时才会显示 UI customization 选项卡

在 UI customization 选项卡上您可以将自己的自定义项添加到默认应用程序 UI

有关每个自定义字段的详细信息请参阅自定义内置登录网页和注册网页 (p 38)Note

通过利用您的用户池的特定信息构建以下 URL 并将它键入到浏览器中您可以查看具有自定义项的托管 UI httpsltyour_domaingtloginresponse_type=codeampclient_id=ltyour_app_client_idgtampredirect_uri=ltyour_callback_urlgt您可能必须等待长达 1 分钟才能刷新浏览器之后才会显示在控制台中进行的更改您的域显示在域名选项卡上您的应用程序客户端 ID 和回调 URL 将显示在常规设置选项卡

自定义内置应用程序 UI

1 在 App client to customize 下选择要从您之前在 App clients 选项卡中创建的应用程序客户端的下拉菜单自定义的应用程序

2 要将徽标添加到默认应用程序 UI请选择 Choose a file 或者将文件拖动到 Logo 框上3 在 CSS customizations (optional) 下您可以通过更改各种属性的默认值来自定义应用程序的外观4 选择保存更改

为用户池添加资源服务器Note

只有在您编辑现有用户池时才会显示资源服务器选项卡

资源服务器是访问受保护的资源的服务器它处理从具有访问令牌的应用程序发送的身份验证请求范围是应用程序可请求的对资源的访问权限的级别

在资源服务器选项卡中您可以定义您的用户池的自定义资源服务器和范围有关更多信息请参阅为您的用户池定义资源服务器 (p 41)

定义自定义资源服务器

1 选择添加资源服务器2 输入您的资源服务器的名称 (例如Photo Server)3 输入您的资源服务器的标识符 (例如comexamplephotos)4 输入您的资源的自定义范围的名称例如 read 和 write5 对于每个范围名称输入一个描述如 view your photos 和 update your photos


为用户池配置身份提供商Note

只有在您编辑现有用户池时才会显示 Identity providers 选项卡

在身份提供商选项卡上可指定用户池的身份提供商 (IIdPs)有关更多信息请参阅通过第三方添加用户池登录 (p 43)

168

Amazon Cognito 开发人员指南身份提供商

主题bull 允许用户使用社交身份提供商登录 (p 169)bull 允许用户使用 OpenID Connect (OIDC) 身份提供商进行登录 (p 169)bull 允许用户使用 SAML 登录 (p 170)

允许用户使用社交身份提供商登录您可以使用 Amazon Cognito 用户池的联合功能来与社交身份提供商如 FacebookGoogle 和 Login withAmazon

要添加社交身份提供商您首先要通过该身份提供商创建一个开发人员账户在拥有开发人员账户后您应向该身份提供商注册您的应用程序身份提供商为您的应用程序创建应用程序 ID 和应用程序密钥然后您在Amazon Cognito 用户池中配置这些值

以下是帮助您开始使用社交身份提供商的链接

bull Google Identity Platformbull Facebook for Developersbull Login with Amazonbull 使用 Apple 登录gt

允许用户使用社交身份提供商登录

1 选择一个社交身份提供商例如FacebookGoogleLogin with Amazon或者SignInWithApple2 对于 FacebookGoogle 或 Amazon 应用程序 ID 和应用程序密码输入您创建 FacebookGoogle 或

Login with Amazon 客户端应用程序时收到的应用程序 ID 和应用程序密码对于使用 Apple 服务 ID团队 ID密钥 ID 和私有密钥请输入您提供给 Apple 的服务 ID 以及您在创建 ldquo使用 Apple 客户端登录rdquo应用时收到的团队 ID密钥 ID 和私钥

3 对于应用程序密钥输入您创建客户端应用程序时收到的应用程序密钥4 适用于授权范围中输入要映射到用户池属性的社交身份提供商范围的名称范围定义了您要

通过应用程序访问的用户属性 (如 name 和 email)对于 Facebook这些属性应采用逗号分隔(例如public_profile email)对于 GoogleLogin with Amazon 和 Sign in with Apple(CLI)它们应该用空格分隔（Google 的示例profile email openid Login with Amazon 示例profile postal_code Login with Apple 示例name email) 对于 ldquo使用 Apple 登录rdquo（控制台）请使用复选框选中它们

最终用户需要同意向您的应用程序提供这些属性关于范围的更多信息请参阅 GoogleFacebook 和Login with Amazon 或ldquo使用 Apple 登录rdquo的文档

5 选择启用 Facebook启用 Google启 Login with Amazon或者启用 Sign in with Apple

有关社交 IdP 的更多信息请参阅向用户池添加社交身份提供商 (p 44)

允许用户使用 OpenID Connect (OIDC) 身份提供商进行登录您可以允许您的用户通过 OIDC 身份提供商 (IdP) (如 Salesforce 或 Ping Identity) 进行登录

1 转到Amazon Cognito 控制台系统可能会提示您输入 Amazon 凭证2 Manage User Pools (管理用户池)3 从列表中选择现有用户池或创建用户池4 在左侧导航栏上选择身份提供商5 选择 OpenID Connect

169


6 在提供商名称中键入一个唯一名称7 将 OIDC IdP 的客户端 ID 键入到客户端 ID8 将 OIDC IdP 的客户端密钥键入到客户端密钥9 在下拉列表中选择用于将 userinfo 终端节点中的用户的详细信息提取到属性请求方法的 HTTP 方法




例如Salesforce 使用以下 URL

httpsloginsalesforcecom

Note

URL 应该以 https 开头并且不应以下斜杠结尾


12 选择创建提供商13 在左侧导航栏上选择应用程序客户端设置14 选择您的 OIDC 提供商作为其中一个启用身份提供商15 键入 Amazon Cognito 授权服务器在用户通过身份验证之后进行调用这是页面的 URL在页面中您

的用户在成功登录后将被重定向

httpswwwexamplecom





有关 OIDC IdP 的更多信息请参阅向用户池添加 OIDC 身份提供商 (p 55)

允许用户使用 SAML 登录您可以将联合 Amazon Cognito 份验证用户池以便与 SAML 身份提供商 (IdP) 集成您通过上传文件或输入元数据文档终端节点 URL 来提供元数据文档有关获取第三方 SAML IdP 元数据文档的信息请参阅将第三方 SAML 身份提供商与 Amazon Cognito 用户池集成 (p 54)

允许用户使用 SAML 登录

1 选择 SAML 以显示 SAML 身份提供商选项

170

Amazon Cognito 开发人员指南属性映射

2 要上传元数据文档请选择选择文件或者输入元数据文档终端节点 URL元数据文档必须是有效的XML 文件

3 输入您的 SAML提供商名称例如SAML_provider_1以及任何标识符你想要的提供商名称是必需的标识符是可选的有关更多信息请参阅向用户池添加 SAML 身份提供商 (p 49)

4 Select启用 IdP 注销流当您希望用户在从 Amazon Cognito 注销的同时从 SAML IdP 注销时


Note


5 选择创建提供商6 要创建其他提供商请重复前面的步骤

Note




有关 SAML IdP 的更多信息请参阅向用户池添加 SAML 身份提供商 (p 49)

为用户池配置属性映射Note

只有在您编辑现有用户池时才会显示属性映射选项卡

在属性映射选项卡上您可以将身份提供商 (IdP) 属性或断言映射到用户池属性有关更多信息请参阅指定适用于用户池的身份提供商属性映射 (p 60)

Note

目前仅 Facebook idGoogle subLogin with Amazon user_id 和 Sign in with Apple sub 属性可映射到 Amazon Cognito 用户池 username 属性

Note

用户池中的属性必须足够大以容纳映射的身份提供商属性的值否则用户登录时将发生错误如果将自定义属性映射到身份提供商令牌则应将其大小设置为最大 2048 个字符您必须为您的用户池所需的任何属性创建映射

为您的用户池指定社交身份提供商属性映射

1 选择 FacebookGoogleAmazon 或 Apple 选项卡2 对于需要映射的每个属性请执行以下步骤

171

Amazon Cognito 开发人员指南管理错误响应

a 选中截取复选框b 在用户池属性字段中从下拉列表中选择要将社交身份提供商属性映射到的用户池属性c 对于 FacebookGoogle 和 Login with Amazon如果您需要更多属性请选择添加 Facebook 属

性添加 Google 属性或添加 Amazon 属性然后执行以下步骤

Note

Sign in with Apple 目前不提供其他属性

i 在 Facebook 属性Google 属性或 Amazon 属性字段中输入要映射的属性的名称ii 对于用户池属性从下拉列表中选择要映射到社交身份提供商属性的用户池属性

d 选择保存更改

为您的用户池指定 SAML 身份提供商属性映射

1 选择 SAML 选项卡2 对于需要映射的每个属性请执行以下步骤

a 选择添加 SAML 属性b 在 SAML 属性字段中输入要映射的 SAML 属性的名称c 对于用户池属性从下拉列表中选择要映射到 SAML 属性的用户池属性d 选择保存更改

管理错误响应Amazon Cognito 支持自定义用户池返回的错误响应自定义错误响应可用于与身份验证确认和密码恢复相关的操作使用PreventUserExistenceErrors设置以启用或禁用与用户存在相关的错误

启用自定义错误响应后Amazon Cognito 身份验证 API 将返回一个通用的身份验证失败响应错误响应告知您用户名或密码不正确Amazon Cognito 账户确认和密码恢复 API 返回一个响应指示代码已发送到模拟的传递媒介错误响应在状态为ENABLED并且用户不存在以下是 Amazon Cognito 操作的详细行为当PreventUserExistenceErrors设置为ENABLED

用户身份验证操作

您可以将任一身份验证流方法与以下操作一起使用

bull AdminInitiateAuth

bull AdminRespondToAuthChallenge

bull InitiateAuth

bull RespondToAuthChallenge

基于用户名密码的身份验证

在身份验证流程中ADMIN_USER_PASSWORD_AUTH和USER_PASSWORD_AUTH用户名和密码返回时只需调用InitiateAuthAmazon Cognito 返回一个通用NotAuthorizedExceptionError指示用户名或密码不正确

基于安全远程密码 (SRP) 的身份验证

在 USER_SRP_AUTH 身份验证流程中Amazon Cognito 在第一步中收到用户名以及 SRP参数 ldquoArdquo作为响应Amazon Cognito 根据 SRP 协议为用户返回 SRP 参数 ldquoBrdquo 和 ldquosaltrdquo如果找不到用户Amazon Cognito 会在第一步中返回一个模拟响应如RFC 5054Amazon

172


Cognito 返回相同的盐和内部用户 ID通用唯一标识符 (UUID)格式相同的用户名和用户池组合当下一个操作RespondToAuthChallenge运行密码证明时Amazon Cognito 会返回一个通用NotAuthorizedExceptionError指示用户名或密码不正确

Note

您可以使用UsernamePassword来模拟通用响应如果您使用的是基于验证的别名并且不可变用户名的格式不是 UUID

ForgotPassword

当找不到用户用户被禁用或用户没有恢复其密码的机制时Amazon Cognito 会返回CodeDeliveryDetails为用户提供模拟交付介质模拟的传递媒介由用户池的输入用户名格式和验证设置决定

ConfirmForgotPassword

Amazon Cognito 返回CodeMismatchException错误的用户不存在或已禁用的用户如果在使用ForgotPassword时Amazon Cognito 将返回ExpiredCodeExceptionError

ResendConfirmationCode

Amazon Cognito 退货CodeDeliveryDetails对于已禁用的用户或不存在的用户Amazon Cognito会向现有用户的电子邮件或电话号码发送确认码

ConfirmSignUp

ExpiredCodeException如果代码已过期则返回Amazon Cognito 退货NotAuthorizedException当用户未被授权时如果代码与服务器期望的代码不匹配 AmazonCognito 返回CodeMismatchException

SignUp

这些区域有SignUp操作返回UsernameExistsException当已使用用户名时为防止在 SignUp 期间对于电子邮件或电话号码发生 UsernameExistsException 错误您可以使用基于验证的别名有关更多信息请参阅 AliasAttributesAmazon Cognito API 参考指南有关别名的更多信息请参阅别名概述

导入的用户

如果PreventUserExistenceErrors则在对导入用户进行身份验证期间通用NotAuthorizedException返回错误指示用户名或密码不正确而不是返回PasswordResetRequiredException请参阅要求导入的用户重置密码了解更多信息

迁移用户 Lambda 触发器

Amazon Cognito 为 Lambda 触发器在原始事件上下文中设置了空响应时不存在的用户返回模拟响应有关更多信息请参阅迁移用户 Lambda 触发器


如果您使用自定义身份验证质询 Lambda 触发器并启用错误响应然后LambdaChallenge返回一个名为UserNotFound然后它被传递到DefineAuthChallengeVerifyAuthChallenge和CreateAuthChallengeLambda 触发器您可以使用此触发器模拟不存在的用户的自定义授权挑战如果您为不存在的用户调用身份验证前 Lambda 触发器则 Amazon Cognito 将返回UserNotFound

173

Amazon Cognito 开发人员指南身份池入门

Amazon Cognito 身份池 (联合身份)Amazon Cognito 身份池 (联合身份) 使您能够为您的用户创建唯一身份并将他们与身份提供商联合有了身份池您便可以获取权限受限的临时权限Amazon凭证以访问其他Amazon服务Amazon Cognito 身份池支持以下身份提供商

bull 公共提供商Login with Amazon (身份池) (p 208)Facebook (身份池) (p 204)Google (身份池) (p 211)Sign in with Apple（身份池） (p 217)

bull Amazon Cognito user pools (p 18)bull Open ID Connect 提供商 (身份池) (p 221)bull SAML 身份提供商 (身份池) (p 223)bull 经过开发人员验证的身份 (身份池) (p 224)

有关 Amazon Cognito 身份池区域可用性的信息请参阅Amazon服务区域可用性

有关 Amazon Cognito 身份池的更多信息请参阅以下主题

主题bull Amazon Cognito 身份池入门 (联合身份) (p 174)bull 使用身份池 (联合身份) (p 176)bull 身份池概念 (联合身份) (p 180)bull 使用访问控制的属性作为基于属性的访问控制的一种形式 (p 189)bull 基于角色的访问控制 (p 193)bull 获取凭证 (p 196)bull 访问Amazon服务 (p 202)bull 身份池 (联合身份) 外部身份提供商 (p 203)bull 经过开发人员验证的身份 (身份池) (p 224)bull 将未经身份验证的用户切换为经过身份验证的用户（身份池） (p 235)

Amazon Cognito 身份池入门 (联合身份)Amazon Cognito 身份池使您能够为用户创建唯一身份并分配权限您的身份池可以包括

bull Amazon Cognito 用户池bull 使用 FacebookGoogleApple 等外部身份提供商或基于 SAML 的身份提供商进行身份验证的用户bull 通过您自己的现有身份验证流程进行身份验证的用户

有了身份池您便可以获取临时Amazon凭据具有您定义的权限以直接访问其他Amazon服务或通过Amazon API Gateway 访问资源

主题bull 注册 Amazon 账户 (p 175)

174

Amazon Cognito 开发人员指南注册 Amazon 账户

bull 在 Amazon Cognito 中创建一个身份池 (p 175)bull 安装移动或 JavaScript 开发工具包 (p 175)bull 整合身份提供商 (p 176)bull 获取凭证 (p 176)

注册 Amazon 账户要使用 Amazon Cognito 身份池您需要一个Amazonaccount 如果您还没有账户请按照以下步骤注册

注册Amazon账户



在 Amazon Cognito 中创建一个身份池您可以通过 Amazon Cognito 控制台创建身份池或者您还可以使用Amazon命令行界面 (CLI) 或 AmazonCognito API

在控制台中创建新的身份池

1 登录到Amazon Cognito 控制台中选择管理身份池然后选择创建新的身份池2 为身份池键入一个名称3 要启用未经身份验证的身份请从 Unauthenticated identities 可折叠部分中选择 Enable access to

unauthenticated identities4 如果需要请在身份验证提供商部分中配置身份验证提供商5 选择 Create Pool

Note

有效身份池至少需要一个身份6 系统将提示您访问Amazon资源的费用

选择Allow以创建两个与您的身份池关联的默认角色一个用于未经身份验证的用户另一个用于经过身份验证的用户这些默认角色会向您的身份池提供对 Amazon Cognito 同步的访问权限您可以在 IAM控制台中修改与身份池关联的角色

安装移动或 JavaScript 开发工具包要使用 Amazon Cognito 身份池您必须安装并配置Amazon移动或 JavaScript 开发工具包有关更多信息请参阅以下主题

bull 设置Amazon适用于 Android 的移动开发工具包bull 设置Amazon适用于 iOS 的移动开发工具包bull 设置Amazon适用于 JavaScript 的开发工具包bull 设置Amazon适用于 Unity 的 Mobile SDKbull 设置Amazon适用于 NET 和 Xamarin 的移动软件开发工具包

175

Amazon Cognito 开发人员指南整合身份提供商

整合身份提供商Amazon Cognito 身份池（联合身份）支持通过 Amazon Cognito 用户池联合身份提供商（包括AmazonFacebookGoogleApple 和 SAML 身份提供商）以及未经身份验证的身份进行的用户身份验证此功能还支持经过开发人员验证的身份 (身份池) (p 224)这让您能够通过自己的后端身份验证流程注册并对用户进行身份验证

要了解有关使用 Amazon Cognito 用户池创建自己的用户目录的更多信息请参阅Amazon Cognito userpools (p 18)和在登录后使用身份池访问 Amazon 服务 (p 149)

要了解有关使用外部身份提供商的更多信息请参阅身份池 (联合身份) 外部身份提供商 (p 203)

要了解有关集成自己的后端身份验证流程的更多信息请参阅经过开发人员验证的身份 (身份池) (p 224)

获取凭证Amazon Cognito 身份池提供临时Amazon身份验证 (未经身份验证) 和经过身份验证并收到了令牌的用户的凭证有了那些Amazon凭证您的应用程序可以安全地访问Amazon或外部Amazon通过 Amazon APIGateway请参阅获取凭证 (p 196)

使用身份池 (联合身份)Amazon Cognito 身份池提供临时Amazon身份验证 (未经身份验证) 和经过身份验证并收到了令牌的用户的凭证身份池是用于存储特定于您的账户的用户身份数据的存储区




Note

有效身份池至少需要一个身份6 系统将提示您访问您的Amazon资源的费用

选择Allow以创建两个与您的身份池关联的默认角色一个用于未经身份验证的用户另一个用于经过身份验证的用户这些默认角色会向您的身份池提供对 Amazon Cognito 同步的访问权限您可以在IAM 控制台中修改与身份池关联的角色有关使用 Amazon Cognito 控制台的更多说明请参阅使用Amazon Cognito 控制台 (p 3)

用户 IAM 角色IAM 角色定义您的用户访问权限Amazon资源如Amazon Cognito 同步 (p 238)您的应用程序用户将担任您创建的角色您可以为经过身份验证和未经身份验证的用户指定不同角色要了解有关 IAM 角色的更多信息请参阅 IAM 角色 (p 184)

176

Amazon Cognito 开发人员指南经过身份验证和未经身份验证的身份

经过身份验证和未经身份验证的身份Amazon Cognito 身份池同时支持经过身份验证和未经身份验证的身份经过身份验证的身份属于已通过任何受支持的身份提供商进行身份验证的用户未经身份验证的身份通常属于来宾用户

bull 要使用公共登录提供商配置经过身份验证的身份请参阅身份池 (联合身份) 外部身份提供商 (p 203)bull 要配置您自己的后端身份验证流程请参阅经过开发人员验证的身份 (身份池) (p 224)

启用或禁用未经身份验证的身份Amazon Cognito 身份池可以支持未经身份验证的身份具体方法是提供唯一标识符和Amazon凭证针对每个未使用身份提供商进行身份验证的身份如果应用程序允许未登录的用户则您可以针对未经身份验证的身份启用访问权限要了解更多信息请参阅ldquoAmazon Cognito 身份池入门 (联合身份) (p 174)rdquo

选择管理身份池来自的Amazon Cognito 控制台

1 单击想要针对其启用或禁用未经身份验证的身份的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的右上角单击编辑身份池此时将显示编辑身份池页3 向下滚动并单击未经验证的身份以将其展开4 选中复选框以启用或禁用对未经身份验证的身份的访问权限5 单击保存更改

更改与身份类型关联的角色身份池定义了两种类型的身份经过身份验证的身份和未经身份验证的身份身份池中的每个身份要么经过身份验证要么未经过身份验证经过身份验证的身份属于由公共登录提供商（Amazon Cognito 用户池Login with AmazonSign with AppleFacebookGoogleSAML 或任何 OpenID Connect 提供商）或开发人员提供商（自己的后端身份验证流程）验证身份的用户未经身份验证的身份通常属于来宾用户

每个身份类型都有一个分配的角色此角色附加了一个策略策略指示了哪个策略Amazon角色可以访问的服务Amazon Cognito 收到请求后服务将确定身份类型确定分配给该身份类型的角色并使用附加到该角色的策略进行响应通过修改策略或向身份类型分配不同的角色您可以控制Amazon身份类型可以访问的服务要查看或修改与身份池中的角色关联的策略请参阅AmazonIAM 控制台

您可以使用 Amazon Cognito 身份池 (联合身份) 控制台更改与身份类型关联的角色选择管理身份池来自的Amazon Cognito 控制台

1 单击想要针对其修改角色的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的右上角单击编辑身份池此时将显示编辑身份池页3 使用未经身份验证的角色和经过身份验证的角色旁边的下拉菜单更改角色单击创建新角色以创建或修改

与每个身份类型相关联的角色AmazonIAM 控制台有关更多信息请参阅 IAM 角色

启用或编辑身份验证提供商如果您允许用户使用公共身份提供商 (如 Amazon Cognito 用户池Login with AmazonSign withAppleFacebookGoogle) 进行身份验证则您可以在 Amazon Cognito 身份池 (联合身份) 控制台中指定应用程序标识符上述操作会将应用程序 ID (由公共登录提供商提供) 与身份池关联

您还可以从此页面为每个提供商配置身份验证规则每个提供商最多可以有 25 个规则规则按您为各个提供商保存的顺序应用有关更多信息请参阅基于角色的访问控制 (p 193)

177

Amazon Cognito 开发人员指南删除身份池

Warning

更改与身份池关联的应用程序 ID 将禁止现有用户通过该身份池进行身份验证了解有关身份池 (联合身份) 外部身份提供商 (p 203)的更多信息


1 单击想要针对其启用外部提供商的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的右上角单击编辑身份池此时将显示编辑身份池页3 向下滚动并单击身份验证提供商以将其展开4 单击相应提供商的选项卡然后输入与该身份验证提供商相关的所需信息

删除身份池选择管理身份池来自的Amazon Cognito 控制台

1 单击要删除的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的右上角单击编辑身份池此时将显示编辑身份池页3 向下滚动并单击删除身份池以将其展开4 单击删除身份池5 单击删除池

Warning

单击删除按钮后您将永久删除身份池和其中包含的所有用户数据删除身份池将导致使用身份池的应用程序和其他服务停止工作

从身份池删除身份选择管理身份池来自的Amazon Cognito 控制台

1 单击包含要删除的身份的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的左侧导航窗格中单击身份浏览器此时将显示身份页3 在身份页面上输入要删除的身份 ID然后单击搜索4 在身份详细信息页面上单击删除身份按钮然后单击删除

管理数据集如果您在应用程序中实施了 Amazon Cognito Sync 功能则 Amazon Cognito 身份池控制台允许您手动创建和删除各个身份的数据集和记录您在 Amazon Cognito 身份池控制台中对身份的数据集或记录做出的任何更改只有当您在控制台中单击 ldquo同步rdquo 后才会保存并且在身份调用同步后才对最终用户可见一旦刷新特定身份的列表数据集页面从其他设备同步的有关各个身份的数据即会显示

为身份创建数据集选择管理身份池Amazon Cognito 身份池Amazon Cognito 控制台

1 单击包含想要为其创建数据集的身份的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的左侧导航窗格中单击身份浏览器此时将显示身份页

178

Amazon Cognito 开发人员指南批量发布数据

3 在身份页面上输入想要为其创建数据集的身份 ID然后单击搜索4 在该身份的身份详细信息页面上单击创建数据集按钮输入数据集名称然后单击创建和编辑数据集5 在当前数据集页面上单击创建记录以创建记录来存储在该数据集中6 为该数据集输入一个密钥（有效的 JSON 值或要存储的值）然后单击 JSON 格式以修饰输入的值并确

认值是格式正确的 JSON完成后单击保存更改7 单击同步来同步数据集您做出的更改在您单击ldquoSynchronizerdquo后才会保存并且在身份调用同步后才对用

户可见要放弃未同步的更改请选择您想放弃的更改然后选择放弃更改

删除与身份关联的数据集选择管理身份池来自的Amazon Cognito 控制台

1 单击包含想要删除其数据集的身份的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的左侧导航窗格中单击身份浏览器此时将显示身份页3 在身份页面上输入包含想要删除的数据集的身份 ID然后单击搜索4 在身份详细信息页面上选中想要删除的数据集旁边的复选框单击删除选定项然后单击删除

批量发布数据批量发布可用于将存储在 Amazon Cognito Sync 存储空间中的数据导出到 Kinesis 流有关如何批量发布所有流的说明请参阅 Amazon Cognito 流 (p 262)

启用推送同步Amazon Cognito 会自动跟踪身份和设备之间的关联通过使用推送同步功能您可以确保在身份数据发生更改时通知给定身份的每个实例推送同步可以确保无论特定身份的同步存储数据何时发生更改与该身份关联的所有设备都会收到一个静音推送通知通知它们所发生的更改

您可以通过 Amazon Cognito 控制台启用推送同步选择管理身份池来自的Amazon Cognito 控制台

1 单击您需要启用推送同步的身份池的名称此时将显示身份池的控制面板页2 在ldquo控制面板rdquo页的右上角单击编辑身份池此时将显示编辑身份池页3 向下滚动并单击推送同步以将其展开4 在服务角色下拉菜单中选择授予 Amazon Cognito 发送 SNS 通知的权限的 IAM 角色单击创建角色以

创建或修改与身份池相关联的角色具体方法是AmazonIAM 控制台5 选择一个平台应用程序然后单击保存更改

设置 Amazon Cognito 流Amazon Cognito 流让开发人员能够控制和了解他们存储在 Amazon Cognito 同步中的数据开发人员现在可以配置 Kinesis 流以接收数据形式的事件Amazon Cognito 可以实时向您拥有的 Kinesis 流推送每个数据集更改有关如何在 Amazon Cognito 控制台中设置 Amazon Cognito 流的说明请参阅Amazon Cognito流 (p 262)

设置 Amazon Cognito 活动Amazon Cognito 事件让您能够执行Amazon Lambda函数以响应 Amazon Cognito 同步中的重要事件当数据集得到同步时Amazon Cognito Sync 会引发同步触发事件当用户更新数据时您可以使用同步触发事件采取行动有关从控制台设置 Amazon Cognito 事件的说明请参阅Amazon Cognito 事件 (p 264)

179

Amazon Cognito 开发人员指南身份池概念

要了解有关 Amazon Lambda 的更多信息请参阅Amazon Lambda

身份池概念 (联合身份)Amazon Cognito 身份池可让您为用户创建唯一身份并通过身份提供商对其进行身份验证有了身份您便可以获取具有有限权限的临时权限Amazon凭证以访问其他Amazon服务Amazon Cognito 身份池支持公共身份提供商 (AmazonAppleFacebook 和 Google) 以及未经身份验证的身份此外它还支持已经过开发人员验证的身份这让您能够通过自己的后端身份验证流程注册并对用户进行身份验证

有关 Amazon Cognito 身份池区域可用性的信息请参阅Amazon服务区域可用性有关 Amazon Cognito 身份池概念的更多信息请参阅以下主题

主题bull 身份池 (联合身份) 身份验证流程 (p 180)bull IAM 角色 (p 184)bull 角色信任和权限 (p 188)

身份池 (联合身份) 身份验证流程Amazon Cognito 可帮助您为最终用户创建可在多个设备和平台间保持一致的唯一标识符Amazon Cognito还可以为您的应用程序提供具有有限权限的临时凭证以访问Amazon资源的费用此页面介绍有关Amazon Cognito 中的身份验证如何工作的基础知识并解释了身份池中身份的生命周期

外部提供商身份验证流程

使用 Amazon Cognito 进行身份验证的用户将通过一个多步骤流程来引导启动凭证Amazon Cognito 有两个不同的通过公有提供商进行身份验证的流程增强型流程和基本流

完成其中的一个流程后您便可以访问其他Amazon服务由您角色的访问策略定义默认情况下AmazonCognito 控制台将创建可访问 Amazon Cognito 同步商店和 Amazon Mobile Analytics 的角色有关如何授予额外访问权限的更多信息请参阅IAM 角色 (p 184)

增强型（简化的）身份验证流程

1 GetId2 GetCredentialsForIdentity

180

Amazon Cognito 开发人员指南身份池身份验证流程

基本（经典）工作流程

1 GetId2 GetOpenIdToken3 AssumeRoleWithWebIdentity

已经过开发人员验证的身份验证流程

使用经过开发人员验证的身份 (身份池) (p 224)客户端将使用包括 Amazon Cognito 外部代码的不同身份验证流程在您自己的身份验证系统中验证用户Amazon Cognito 外部代码如此处所示

增强型身份验证流程

1 通过开发人员提供商 (Amazon Cognito 外部代码) 登录2 验证用户的登录名 (Amazon Cognito 外部代码)3 GetOpenIdTokenForDeveloperIdentity4 GetCredentialsForIdentity

基本身份验证流程

181


1 通过开发人员提供商 (Amazon Cognito 外部代码) 登录2 验证用户的登录名 (Amazon Cognito 外部代码)3 GetOpenIdTokenForDeveloperIdentity4 AssumeRoleWithWebIdentity

我应该使用哪种身份验证流程

对于大多数客户增强型流程是正确的选择因为它与基本流程相比可提供很多优势

bull 用来在设备上获取凭证的网络调用少一个bull 所有调用都面向 Amazon Cognito这意味着它的网络连接也少一个bull 角色不再需要嵌入到应用程序中只需一个身份池 ID 和区域即可开始引导启动凭证

自二零一五年二月起Amazon Cognito 控制台显示使用增强型流程的示例代码此外如果您的身份池没有使用增强型流程所需的角色关联控制台将显示一条通知

以下是支持增强型流程的最低开发工具包版本

开发工具包（最低版本）

bull AmazonSDK for iOS (2014)bull Amazon适 SDK for Android (218)bull Amazon适用于 JavaScript 的开发工具包 (217)bull AmazonSDK for Unity 开发工具包 (103)bull Amazon适用于 Xamarin 的开发工具包 (3005)

如果您要使用的角色不只是在控制台中创建新身份池时配置的两个默认角色您可能还是需要使用基本流程

API 摘要

GetId

GetId API 调用是在 Amazon Cognito 中建立新身份所必需的第一个调用

未经身份验证的访问

Amazon Cognito 能够在您的应用程序中允许未经身份验证的来宾访问如果您的身份池中已启用此功能用户可以随时通过 GetId API 请求新的身份 ID该应用程序应缓存此身份 ID以对 Amazon Cognito 发出后

182


续调用这些区域有Amazon移动软件开发工具包以及AmazonSDK for JavaScript in the Browser 开发工具包拥有可为您处理此缓存的凭证提供商

经过身份验证的访问

在您将应用程序配置为支持公共登录提供商（FacebookGoogle+Login with Amazon 或 Sign in withApple）后用户也可以提供用于在这些提供商中识别它们的令牌（OAuth 或 OpenID Connect）在对GetId 的调用中使用时Amazon Cognito 将创建一个经过身份验证的新身份或者是返回已与该特定登录名关联的身份Amazon Cognito 通过向提供商验证令牌并确保以下各项来实现此目的

bull 令牌有效且来自已配置的提供商bull 令牌未过期bull 令牌与使用该提供商创建的应用程序标识符 (如 Facebook 应用程序 ID) 匹配bull 令牌与用户标识符匹配

GetCredentialsForIdentity

在建立身份 ID 后即可调用 GetCredentialsForIdentity API此 API 在功能上等效于调用GetOpenIdToken后跟 AssumeRoleWithWebIdentity

为了使 Amazon Cognito 代表您调用 AssumeRoleWithWebIdentity您的身份池必须具有与之关联的 IAM 角色为此您可以使用 Amazon Cognito 控制台也可以通过 SetIdentityPoolRoles 操作手动实现此目的 (请参阅 API 参考)

GetOpenIdToken

在建立身份 ID 后即可调用 GetOpenIdToken API如果您有缓存身份 ID那么这可能是您在应用程序会话期间首先执行的调用


要为未经身份验证的身份获取令牌您只需身份 ID 本身无法为经过身份验证的身份或禁用的身份获取未经身份验证的令牌


如果您有一个经过身份验证的身份您必须为已与该身份关联的登录名传递至少一个令牌在GetOpenIdToken 调用期间所有传入的令牌都必须通过之前提到的同一验证如果有任何令牌失败整个调用都会失败GetOpenIdToken 调用的响应中还包括身份 ID这是因为您传入的身份 ID 可能不是返回的那个身份 ID

关联登录名

如果您为未与任何身份关联的登录名传入令牌该登录名将视为已ldquo链接rdquo到关联身份您只能为每个公共提供商链接一个登录名如果尝试将多个登录名链接到一个公共提供商将导致 ResourceConflictException如果登录名只链接到一个现有身份则 GetOpenIdToken 返回的身份 ID 将与传入的相同

合并身份

如果您为目前未链接到给定身份但链接到另一身份的登录名传入令牌这两个身份将合并两个身份一旦合并其中一个身份会成为所有关联登录名的父项所有者另一个身份会被禁用在这种情况下将返回父项所有者的身份 ID如果这个值不一致您需要更新您的本地缓存 (如果您使用的提供商位于Amazon移动开发工具包或AmazonSDK for JavaScript in the Browser 工具包)

GetOpenIdTokenForDeveloperIdentity

使用已经过开发人员验证的身份时GetOpenIdTokenForDeveloperIdentity API 将替代设备使用的 GetId 和GetOpenIdToken因为这个 API 调用是由Amazon凭证Amazon Cognito 可以信任 API 调用中提供的用户标识符是有效的这将替代 Amazon Cognito 对外部提供商执行的令牌验证

183

Amazon Cognito 开发人员指南IAM 角色

此 API 的负载包含一个登录映射其中必须包含您的开发人员提供商密钥以及作为系统中用户标识符的值如果用户标识符尚未链接到现有身份Amazon Cognito 将创建一个新身份并为该身份返回新身份 ID以及 OpenId Connect 令牌如果用户标识符已链接Amazon Cognito 将返回预先存在的身份 ID 和 OpenIdConnect 令牌

关联登录名

与外部提供商一样提供尚未与身份关联的额外登录名会将这些登录名隐式关联到该身份请务必注意如果您将一个外部提供商链接到一个身份用户可以对该提供商使用外部提供商身份验证流程但他们无法在调用 GetId 或 GetOpenIdToken 时使用登录映射中的开发人员提供商名称

合并身份

借助已经过开发人员验证的身份Amazon Cognito 支持隐式合并以及通过 MMergeDeveloperIdentities API进行显式合并通过显式合并您可以使用系统中的用户标识符将两个身份标识为单个身份您只需提供源和目标用户标识符Amazon Cognito 就可以将其合并您下次为任一用户标识符请求 OpenId Connect 令牌时系统都会返回同一身份 ID

AssumeRoleWithWebIdentity

一旦拥有了 OpenID Connect 令牌您就可以将这个令牌换为临时Amazon凭据中AssumeRoleWithWebIdentity API 调用Amazon Security Token Service(STS) 这个调用与直接使用FacebookGoogle+Login with Amazon 或 Sign in with Apple 的情况并无不同只不过您是在传递Amazon Cognito 令牌而不是其他某个公共提供商的令牌

由于可以创建的身份数量没有限制请务必了解向用户授予的权限我们建议您为应用程序部署两个不同的角色一个用于未经身份验证的用户一个用于经过身份验证的用户默认情况下在您首次设置身份池时Amazon Cognito 控制台会为您创建这些角色这两个角色的访问策略将完全相同它将授予用户访问Amazon Cognito Sync 以及将事件提交到 Amazon Mobile Analytics 的权限我们欢迎并鼓励您修改这些角色以满足自己的需求

了解有关角色信任和权限 (p 188)的更多信息

IAM 角色在创建身份池的过程中系统会提示您更新用户承担的 IAM 角色IAM 角色的工作方式如下所示当用户登录您的应用程序时Amazon Cognito 生成临时Amazon用户的凭证这些临时凭证与特定 IAM 角色相关联IAM 角色让您可以定义一组权限以访问Amazon资源的费用

您可以为经过身份验证的用户和未经身份验证的用户指定默认 IAM 角色此外您可以定义规则以便基于用户 ID 令牌中的声明为每个用户选择角色有关更多信息请参阅基于角色的访问控制 (p 193)

默认情况下Amazon Cognito Console 会创建 IAM 角色以提供访问 Amazon Mobile Analytics 和 AmazonCognito Sync 的权限或者您也可以选择使用现有的 IAM 角色

要修改 IAM 角色从而允许或限制访问其他服务登录 IAM 控制台然后单击ldquoRolesrdquo选择一个角色ldquoPermissionsrdquo选项卡中会列出选定角色所附加的策略您可以单击相应的ldquoManage Policyrdquo链接自定义访问策略要了解如何使用和定义策略的更多信息请参阅 IAM 策略概述

Note

作为最佳实践定义策略时应遵循授予最低权限的原则换言之策略只包含用户执行其任务所需的权限有关更多信息请参阅授予最低权限中的IAM 用户指南请记住未经验证的身份会被未登录应用的用户所利用通常情况下为未经验证的身份分配的权限应该比为经过验证的身份分配的权限更严格

主题bull 设置信任策略 (p 185)bull 访问策略 (p 185)

184


设置信任策略Amazon Cognito 利用 IAM 角色来为您的应用程序的用户生成临时凭证对权限的访问由角色的信任关系控制了解有关角色信任和权限 (p 188)的更多信息

跨身份池重复使用角色

要跨多个身份池重复使用某个角色由于它们共享一个通用权限集您可以添加多个身份池如下所示

StringEquals cognito-identityamazonawscomaud [ us-east-112345678-abcd-abcd-abcd-123456790ab us-east-198765432-dcba-dcba-dcba-123456790ab ]

限制对特定身份的访问权限

要创建限制为一组特定应用用户的策略请检查 cognito-identityamazonawscomsub 的值

StringEquals cognito-identityamazonawscomaud us-east-112345678-abcd-abcd-abcd-123456790ab cognito-identityamazonawscomsub [ us-east-112345678-1234-1234-1234-123456790ab us-east-198765432-1234-1234-1243-123456790ab ]

限制对特定提供商的访问权限

要创建仅限于已使用特定提供商 (可能是您自己的登录提供商) 登录的用户的策略请检查 cognito-identityamazonawscomamr 的值

ForAnyValueStringLike cognito-identityamazonawscomamr loginmyprovidermyapp

例如一个仅信任 Facebook 的应用程序将具有以下 amr 子句

ForAnyValueStringLike cognito-identityamazonawscomamr graphfacebookcom

访问策略附加到角色的权限对承担该角色的所有用户都有效如果您希望区分用户的访问权限则可以通过策略变量来实现在访问策略中添加用户的身份 ID 时请务必小心特别是对未经身份验证的身份因为它们可能会在用户选择登录时发生变化

为提供额外的安全保护Amazon Cognito 对提供的凭证应用范围缩小的策略GetCredentialForIdentity以阻止未经身份验证的用户访问除下面列出的服务以外的服务换句话说此策略允许使用这些凭证的身份仅访问以下服务

AmazonAppSync

AmazonComprehend

GameLift Amazon Lex AmazonPolly

AmazonSimpleDB

AmazonTranscribe

185


CloudWatch DynamoDB Amazon IoT AmazonMachineLearning

AmazonRekognition

AmazonSES

AmazonTranslate

AmazonCognitoIdentity

AmazonKinesis DataFirehose

AmazonKMS

AmazonMobileAnalytics

AmazonSumerian

AmazonSNS

AmazonCognito 同步

AmazonKinesis DataStreams

AmazonLambda

AmazonPinpoint

Amazon S3 AmazonSQS

如果您需要支持未经身份验证的用户访问除这些服务以外的服务您必须使用基本身份验证流程如果您收到 NotAuthorizedException并且您在未经身份验证的角色策略中启用了对该服务的访问权限那么这可能就是原因所在

访问策略示例在此部分中您可以找到示例 Amazon Cognito 访问策略这些策略仅授予您的身份完成特定操作所需的权限您可以在可能的情况下使用策略变量进一步限制给定标识 ID 的权限例如使用 $cognito-identityamazonawscomsub有关更多信息请参阅了解 Amazon Cognito 身份验证第 3 部分角色和策略上AmazonMobile 博客

Note

作为安全性最佳实践策略应仅包括用户执行其任务所需的权限这意味着您应该尽可能始终为对象限定单个身份的访问范围

示例 1允许身份在 S3 中具有对单个对象的读取访问权限

以下访问策略向身份授予读取权限以便从给定的 S3 存储桶中检索单个对象

Version 2012-10-17 Statement [ Action [ s3GetObject ] Effect Allow Resource [arnawss3mybucketassetsmy_picturejpg] ]

示例 2允许身份在 S3 中对身份特定路径具有读写访问权限

以下访问策略通过将前缀映射到 $cognito-identityamazonawscomsub 变量来授予读取和写入权限以访问 S3 存储桶中的特定前缀ldquo文件夹rdquo

利用此策略通过 $cognito-identityamazonawscomsub 插入的身份（例如 us-east-112345678-1234-1234-1234-123456790ab）将能够在 arnawss3mybucketus-east-112345678-1234-1234-1234-123456790ab 中获取放置和列出对象但是不会授予身份访问 arnawss3mybucket 中的其他对象的权限

Version 2012-10-17 Statement [

186


Action [s3ListBucket] Effect Allow Resource [arnawss3mybucket] Condition StringLike s3prefix [$cognito-identityamazonawscomsub] Action [ s3GetObject s3PutObject ] Effect Allow Resource [arnawss3mybucket$cognito-identityamazonawscomsub] ]

示例 3为 Amazon DynamoDB 分配身份细粒度访问权限

以下访问策略使用 Amazon Cognito 变量为 Amazon DynamoDB 资源提供细粒度访问控制这些变量通过身份 ID 授予对 DynamoDB 中的项的访问权限有关更多信息请参阅使用 IAM 策略条件实现精细访问控制中的Amazon DynamoDB 开发人员指南

Version 2012-10-17 Statement [ Effect Allow Action [ dynamodbGetItem dynamodbBatchGetItem dynamodbQuery dynamodbPutItem dynamodbUpdateItem dynamodbDeleteItem dynamodbBatchWriteItem ] Resource [ arnawsdynamodbus-west-2123456789012tableMyTable ] Condition ForAllValuesStringEquals dynamodbLeadingKeys [$cognito-identityamazonawscomsub] ]

示例 4允许身份执行Amazon Lambda函数调用

以下访问策略向身份授予执行Amazon Lambdafunction

Version 2012-10-17 Statement [ Effect Allow Action lambdaInvokeFunction Resource [ arnawslambdaus-west-2123456789012functionMyFunction ]

187

Amazon Cognito 开发人员指南角色信任和权限

]

示例 5允许身份将记录发布到 Amazon Kinesis 数据流

以下访问策略允许身份将 PutRecord 操作与任何 Kinesis 数据流结合使用它可以应用于需要将数据记录添加到账户中所有流的用户有关更多信息请参阅使用 IAM 控制对 Amazon Kinesis Data Streams 资源的访问中的Amazon Kinesis Data Streams 开发人员指南

Version 2012-10-17 Statement [ Effect Allow Action kinesisPutRecord Resource [ arnawskinesisus-east-1111122223333streamstream1 ] ]

示例 6允许身份访问 Amazon Cognito Sync 存储中的数据

以下访问策略仅向身份授予对 Amazon Cognito Sync 存储中其数据的权限

Version 2012-10-17 Statement[ EffectAllow Actioncognito-sync Resource[arnawscognito-syncus-east-1123456789012identitypool$cognito-identityamazonawscomaudidentity$cognito-identityamazonawscomsub] ]

角色信任和权限这些角色的区别在于其信任关系让我们来看一下未经身份验证的角色的示例信任策略

Version 2012-10-17 Statement [ Sid Effect Allow Principal Federated cognito-identityamazonawscom Action stsAssumeRoleWithWebIdentity Condition StringEquals cognito-identityamazonawscomaud us-east-112345678-corner-cafe-123456790ab ForAnyValueStringLike cognito-identityamazonawscomamr unauthenticated

188

Amazon Cognito 开发人员指南使用属性进行访问控制

]

这个策略定义了我们希望允许来自 cognito-identityamazonawscom (OpenID Connect 令牌的发布者) 的联合身份用户承担此角色此外我们限制令牌的受众 (在我们的示例中为身份池 ID) 与我们的身份池匹配最后我们指定令牌的 amr 包含未经身份验证的值

当 Amazon Cognito 创建一个令牌时它将设置amr如果是 ldquo未经身份验证rdquo 或 ldquo经过身份验证rdquo如果是经过身份验证的情况它将包含身份验证过程中使用的所有提供商这意味着您可以创建一个角色它只信任通过 Facebook 登录的用户这只需将 amr 子句更改为如下所示即可


在更改角色的信任关系或尝试跨身份池使用角色时请务必谨慎如果您的角色未配置为正确信任身份池您将看到 STS 发出的类似以下内容的异常

AccessDenied -- Not authorized to perform stsAssumeRoleWithWebIdentity

如果您看到这种异常请仔细检查是否为身份池和身份验证类型使用了正确的角色

使用访问控制的属性作为基于属性的访问控制的一种形式

您可以使用 IAM 策略控制对Amazon基于用户属性的 Amazon Cognito 身份池中的资源这些属性可以来自社会和企业身份提供者您可以将提供商的访问权限和 ID 令牌或 SAML 断言中的属性映射到可在 IAM 权限策略中引用的标签

您可以选择默认映射或在 Amazon Cognito 身份池中创建自己的自定义映射默认映射允许您根据一组固定的用户属性编写 IAM 策略自定义映射允许您选择 IAM 权限策略中引用的自定义用户属性集这些区域有属性名称在 Amazon Cognito 控制台中映射委托人的标签密钥这些标签是 IAM 权限策略中引用的标签

例如假设您拥有一个免费的付费会员资格的媒体流服务您可以将媒体文件存储在 Amazon S3 中并使用免费或高级标签对其进行标记您可以使用属性进行访问控制以允许访问基于用户成员资料级别的免费和付费内容这是用户配置文件的一部分您可以将成员资格属性映射到要传递给 IAM 权限策略的委托人的标签密钥通过这种方式您可以创建单个权限策略并根据内容文件上的成员资格级别和标记的值有条件地允许访问高级内容

主题bull 将属性用于访问控制与 Amazon Cognito 身份池一起使用 (p 190)bull 使用属性作为访问控制策略示例 (p 190)bull 禁用访问控制的属性（控制台） (p 192)bull 默认提供商映射 (p 192)

使用属性控制访问有几个优势

bull 使用属性进行访问控制时权限管理会更加简单您可以创建使用用户属性的基本权限策略而不是为不同的作业职能创建多个策略

bull 无论何时为应用程序添加或删除资源或用户都无需更新策略权限策略只会向具有匹配用户属性的用户授予访问权限例如您可能需要根据用户的作业标题控制对某些 S3 存储桶的访问权限在这种

189

Amazon Cognito 开发人员指南将属性用于访问控制与 Amazon Cognito 身份池一起使用

情况下您可以创建权限策略以便仅允许定义作业标题中的用户访问这些文件有关更多信息请参阅 IAM 教程将 SAML 会话标签用于 ABAC

bull 属性可以作为主要标记传递给策略该策略基于这些属性的值允许或拒绝权限

将属性用于访问控制与 Amazon Cognito 身份池一起使用在使用属性进行访问控制之前请确保满足以下先决条件

bull Amazon 账户bull 用户池bull 身份池bull 移动或 JavaScript 开发工具包bull 集成身份提供商bull 凭证

要使用属性进行访问控制您必须配置委托人的标签密钥和属性名称In委托人的标签密钥值用于匹配PrincipalTag条件The value in 属性名称是要在策略中评估其值的属性的名称

将属性用于身份池的访问控制

1 打开 Amazon Cognito 控制台2 选择 Manage Identity Pools (管理身份池)3 在仪表板上选择要使用属性进行访问控制的身份池的名称4 选择编辑身份池5 展开 Authentication providers 部分6 在身份证提供商部分中选择要使用的提供商选项卡7 In访问控制属性中选择默认属性映射或者自定义属性映射每个提供商的默认映射有所不同有关更

多信息请参阅默认提供商映射 (p 192)获取访问控制属性8 如果选择自定义属性映射请完成以下步骤

1 In委托人的标签密钥中输入您的自定义文本最大长度为 128 个字符2 In属性名称中输入来自提供程序令牌或 SAML 断言的属性名称您可以从提供商开发人员指南中获

取 IdPs 的属性名称属性名称最多包含 256 个字符此外所有属性的聚合字符限制为 460 字节3 （可选）添加其他提供商您可以在控制台中为 Amazon Cognito 用户池OIDC 和 SAML 提

供商添加多个提供商例如您可以将两个 Amazon Cognito 用户池添加为两个独立的身份提供商Amazon Cognito 将每个选项卡视为不同的 IIdPs您可以为每个 IdP 单独配置访问控制的属性

4 要完成操作请使用 IAM 控制台创建包含默认映射或您在委托人的标签密钥有关在 IAM 中创建权限策略的教程请参阅IAM 教程定义访问权限Amazon基于标签的资源中的IAM 用户指南

使用属性作为访问控制策略示例考虑一种情况即公司法律部门的员工需要列出存储桶中属于其部门并按其安全级别进行分类的所有文件假定此员工从身份提供商获得的令牌包含以下声明

申请

190

Amazon Cognito 开发人员指南使用属性作为访问控制策略示例

sub 57e7b692-4f66-480d-98b8-45a6729b4c88 department legal clearance confidential

这些属性可以映射到标签并在 IAM 权限策略中作为主要标签引用现在您可以通过更改身份提供商端的用户配置文件来管理访问权限或者您可以通过使用名称或标签来更改资源端的属性而无需更改策略本身

以下权限策略执行两项操作

bull 允许列表访问以与用户的部门名称匹配的前缀结尾的所有 s3 存储桶bull 允许对这些存储桶中的文件进行读取访问只要文件上的间隙标签与用户的清除属性相匹配

权限策略

Version 2012-10-17 Statement [ Effect Allow Action s3List Resource arnawss3-$awsPrincipalTagdepartment Effect Allow Action s3GetObject Resource arnawss3-$awsPrincipalTagdepartment Condition StringEquals s3ExistingObjectTagclearance $awsPrincipalTagclearance ]

信任策略决定谁可担任此角色信任关系策略允许使用stsAssumeRoleWithWebIdentity和stsTagSession允许访问它添加了一些条件以便将策略限制在您创建的身份池中并确保该策略适用于经过身份验证的角色

信任策略

Version 2012-10-17 Statement [ Effect Allow Principal Federated cognito-identityamazonawscom Action [

191

Amazon Cognito 开发人员指南禁用访问控制的属性

stsAssumeRoleWithWebIdentity stsTagSession ] Condition StringEquals cognito-identityamazonawscomaud IDENTITY-POOL-ID ForAnyValueStringLike cognito-identityamazonawscomamr authenticated ]

禁用访问控制的属性（控制台）按照此过程禁用访问控制的属性

禁用访问控制的属性

1 打开 Amazon Cognito 控制台2 选择 Manage Identity Pools (管理身份池)3 在仪表板上选择要禁用其属性的身份池的名称4 选择编辑身份池在页面的右上角5 展开 Authentication providers 部分6 在身份验证的角色选择中选择禁用7 要完成请滚动至页面底部并选择保存更改

默认提供商映射下表提供了 Amazon Cognito 支持的身份验证提供商的默认映射信息

Provider 令牌类型委托人标签值示例

Amazon Cognito 用户池 ID 令牌 Aud（客户端 ID）和子（用户 ID）

ldquo6 英寸国际货币基础设施rdquoldquo国际货币基础设施rdquoldquo国际货币基础设施rdquo

Facebook 访问令牌澳元（应用程序编号）子（用户 ID）

ldquo第九十八届会议rdquoldquo第三届会议rdquo

Google ID 令牌 Aud（客户端 ID）和子（用户 ID）

ldquo应用程序用户内容网站rdquoldquo

SAML 断言 ldquohttpschemasxmlsoaporgws200505identityclaimsnameidentifier httpschemasxmlsoaporgws200505identityclaimsnamerdquo

ldquo授权书rdquoldquouser123gmailcomrdquo

192

Amazon Cognito 开发人员指南基于角色的访问控制


Apple ID 令牌 Aud（客户端 ID）和子（用户 ID）

ldquo计算机 1 客户端rdquoldquo客户端rdquo

Amazon 访问令牌 aud（Amzn 开发交流中的客户端 ID）用户ID（用户 ID）

ldquo应用程序-OA2 客户端rdquo

标准 OIDC 提供商 ID 令牌和访问令牌 Aud（作为客户端ID）子（作为用户ID）


Twitter 访问令牌 aud（应用程序 ID应用程序密钥）子（用户ID）

ldquo中华人民共和国电子商务中心rdquoldquo12690038842976

德沃特映射不适用 ldquo标签 1rdquoldquo标记 2rdquo

Note

默认属性映射选项会自动填充委托人的标签密钥和属性名称无法更改默认映射

基于角色的访问控制Amazon Cognito 身份池为经过身份验证的用户分配了一组具有有限权限的临时凭证以访问您的Amazon资源的费用每个用户的权限通过IAM 角色你创建的您可以定义规则以便基于用户 ID 令牌中的声明为每个用户选择角色您可以为经过身份验证的用户定义一个默认角色您也可以为未经身份验证的来宾用户定义一个具有有限权限的单独的 IAM 角色

为角色映射创建角色请务必为每个角色添加适当的信任策略使其只能由 Amazon Cognito 针对您的身份池中经过身份验证的用户担任下面是此类信任策略的示例

Version 2012-10-17 Statement [ Sid Effect Allow Principal Federated cognito-identityamazonawscom Action stsAssumeRoleWithWebIdentity Condition StringEquals cognito-identityamazonawscomaud us-east-112345678-corner-cafe-123456790ab ForAnyValueStringLike cognito-identityamazonawscomamr authenticated ]

193

Amazon Cognito 开发人员指南授予传递角色权限

此策略允许来自 cognito-identityamazonawscom (OpenID Connect 令牌的发布者) 的联合身份用户担任该角色此外策略限制令牌的 aud (在此示例中为身份池 ID) 匹配身份池最后策略指定令牌的amr 包含值 authenticated

授予传递角色权限要允许 IAM 用户为角色设置超过该用户在身份池上的现有权限的权限您需授予该用户iamPassRole权限将角色传递到set-identity-pool-rolesAPI例如如果用户无法写入 Amazon S3但用户在身份池上设置的 IAM 角色可向 Amazon S3 授予写入权限则用户只能在iamPassRole权限以下示例策略介绍了如何提供 iamPassRole 权限

Version 2012-10-17 Statement [ Sid Stmt1 Effect Allow Action [ iamPassRole ] Resource [ arnawsiam123456789012rolemyS3WriteAccessRole ] ]

在此策略示例中将 iamPassRole 权限授予了角色 myS3WriteAccessRole该角色使用角色的 ARN指定您还必须将此策略附加到您的用户或用户所属的角色有关更多信息请参阅使用管理的策略

Note

Lambda 函数使用基于资源的策略该策略直接附加至 Lambda 函数本身创建调用 Lambda 函数的规则时您未传递角色因此创建规则的用户无需iamPassRole权限有关 Lambda 函数授权的更多信息请参阅管理权限使用 Lambda 函数策略

使用令牌向用户分配角色对于通过 Amazon Cognito 用户池登录的用户角色可在用户池分配的 ID 令牌中进行传递角色将显示在ID 令牌的以下声明中

bull cognitopreferred_role 声明是角色 ARNbull cognitoroles 声明是一个以逗号分隔的字符串其中包含一组允许的角色 ARN

声明按如下方式设置

bull cognitopreferred_role 声明设置为组中具有最大 (最小) Precedence 值的角色如果只有一个允许的角色则 cognitopreferred_role 设置为该角色如果存在多个角色且没有一个角色具有最高优先级则此声明未设置

bull 如果至少存在一个角色则 cognitoroles 声明已设置

使用令牌分配角色时如果存在多个可向用户分配的角色Amazon Cognito 身份池 (联合身份) 将按以下方式选择角色

194

Amazon Cognito 开发人员指南使用基于规则的映射向用户分配角色

bull 使用 GetCredentialsForIdentity CustomRoleArn 参数（在参数已设置且与 cognitoroles 声明中的角色相匹配的情况下）如果此参数与 cognitoroles 中的角色不匹配则拒绝访问

bull 如果 cognitopreferred_role 声明已设置请使用它bull 如果 cognitopreferred_role 声明未设置cognitoroles 声明已设置但 CustomRoleArn

未在 GetCredentialsForIdentity 的调用中指定则使用控制台中的 Role resolution 设置或AmbiguousRoleResolution 字段 (在 RoleMappingsSetIdentityPoolRoles API 的参数中) 来确定要分配的角色

使用基于规则的映射向用户分配角色规则允许您将身份提供商令牌的声明映射到 IAM 角色

每个规则指定一个令牌声明 (例如 Amazon Cognito 用户池的 ID 令牌中的用户属性)匹配类型值和 IAM角色匹配类型可以是 EqualsNotEqualStartsWith 或 Contains如果用户拥有声明的匹配值则该用户可在获取凭证后担任该角色例如您可以创建一个规则为具有customdept自定义属性值Sales

Note

在规则设置中自定义属性需要使用 custom 前缀以便将它们与标准属性区分开来

规则按顺序进行评估并使用第一条匹配规则的 IAM 角色除非CustomRoleArn被指定为覆盖订单有关Amazon Cognito 用户池中用户属性的更多信息请参阅配置用户池属性 (p 153)

您可以在身份池 (联合身份) 控制台中为身份验证提供商设置多条规则按顺序应用规则您可以拖动规则以更改其顺序第一条匹配规则优先如果匹配类型为 NotEqual 且声明不存在则不会对规则进行评估如果没有规则匹配则角色解析设置应用到使用经过身份验证的默认角色或拒绝

在 API 和 CLI 中您可以指定在以下情况下要分配的角色AmbiguousRoleResolutionRoleMapping 类型 (在 SetIdentityPoolRolesRoleMappings API 的参数中指定) 的字段中没有规则匹配

对于每个用户池或为某个身份池配置的其他身份验证提供商您可以创建最多 25 条规则如果您需要为提供商创建超过 25 条规则请提交请求提高服务限制支持案例

基于规则的映射中使用的令牌声明Amazon Cognito

Amazon Cognito ID 令牌以 JSON Web Token (JWT) 表示令牌包含有关经过身份验证的用户的身份声明例如 namefamily_name 和 phone_number有关标准声明的更多信息请参阅 OpenID Connect 规范除了标准声明之外以下是特定于 Amazon Cognito 的额外声明

bull cognitogroups

bull cognitoroles

bull cognitopreferred_role

Amazon

以下声明以及这些声明可能的值可与 Login with Amazon 配合使用

bull isswwwamazoncombull aud应用程序 IDbull subLogin with Amazon 令牌中的 sub

195

Amazon Cognito 开发人员指南基于角色的访问控制的最佳实践

Facebook

以下声明以及这些声明可能的值可与 Facebook 配合使用

bull issgraphfacebookcombull aud应用程序 IDbull subFacebook 令牌中的 sub

Google

Google 令牌包含 OpenID Connect 规范中的标准声明OpenID 令牌中的所有声明均可用于基于规则的映射请参阅 Google 的 OpenID Connect 网站了解 Google 令牌中包含的声明

Apple

Apple 令牌包含 OpenID Connect 规范中的标准声明请参阅 Apple 文档中的使用 Sign in with Apple 对用户进行身份验证详细了解有关 Apple 令牌提供的声明Apple 的令牌并不总是包含 email

OpenID

OpenID 令牌中的所有声明均可用于基于规则的映射有关标准声明的更多信息请参阅 OpenID Connect规范请参阅您的 OpenID 提供商文档了解其中包含的任何额外声明

SAML

根据收到的 SAML 断言分析声明SAML 断言中包含的所有声明均可在基于规则的映射中使用

基于角色的访问控制的最佳实践Important

如果最终用户可修改您映射到角色的声明则任何最终用户均可担任您的角色并相应地设置策略仅将无法由最终用户直接设置的声明映射到具有提升的权限的角色在 Amazon Cognito 用户池中您可以为每个用户属性设置每个应用程序的读取和写入权限

Important

如果您在 Amazon Cognito 用户池中为组设置角色这些角色将通过用户的 ID 令牌进行传递要使用这些角色您还必须为身份池中选择的通过身份验证的角色设置使用令牌选择角色您可以使用控制台中的 Role resolution 设置以及 RoleMappingsSetIdentityPoolRoles API 的参数指定无法确定令牌中的正确角色时的默认行为

获取凭证您可以使用 Amazon Cognito 将具有有限权限的临时凭证传输到应用程序以便您的用户访问Amazon资源的费用本部分介绍如何获取凭证以及如何从身份池检索 Amazon Cognito 身份

Amazon Cognito 同时支持经过身份验证和未经身份验证的身份未经身份验证的用户的身份未经过验证因此该角色很适合您的应用程序的来宾用户或用户身份验证与否无关紧要的情形经过身份验证的用户可以通过第三方身份提供商或证实其身份的用户池登录到您的应用程序确保您的资源的权限范围适当让未经身份验证的用户无权访问这些资源

Amazon Cognito 身份不是凭据可以在 Amazon Security Token Service (Amazon STS) 中使用 Web 联合身份验证支持来用它们交换凭证推荐的方法来获得Amazon凭证的身份是使用AWSCognitoIdentityCredentials然后使用 Amazon STS 用凭证对象中的身份交换凭证

196

Amazon Cognito 开发人员指南Android

Note

如果您的身份池是在 2015 年 2 月前创建的则您需要将您的角色与身份池重新关联以便在没有角色作为参数的情况下使用 AWSCognitoIdentityCredentials 构造函数为此请打开Amazon Cognito 控制台中选择管理身份池选择身份池选择编辑身份池指定您的经过身份验证和未经身份验证的角色然后保存更改

Android

您可以使用 Amazon Cognito 将具有有限权限的临时凭证传输到应用程序以便您的用户访问Amazon资源的费用Amazon Cognito 同时支持经过身份验证和未经身份验证的身份提供Amazon凭证添加到应用程序中请执行以下步骤

1 选择管理身份池来自的Amazon Cognito 控制台创建一个身份池并复制启动器代码段2 如果您尚未完成此操作请将 Amazon Mobile SDK for Android 添加到您的项目中有关说明请参阅设

置适用于 Android 的移动软件开发工具包3 包括以下导入语句

import comamazonawsauthCognitoCachingCredentialsProviderimport comamazonawsregionsRegions

4 使用 Amazon Cognito 控制台生成的代码段初始化 Amazon Cognito 凭证提供程序IDENTITY_POOL_ID 的值将特定于您的账户

CognitoCachingCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider( getApplicationContext() Context IDENTITY_POOL_ID Identity Pool ID RegionsUS_EAST_1 Region)

5 将初始化的 Amazon Cognito 凭证提供商传递给Amazon要使用的客户端所需的代码取决于要初始化的服务客户端将使用此提供程序获取用于访问的凭证Amazon资源的费用

Note

如果您在 2015 年 2 月之前创建了身份池您将需要将您的角色与身份池重新关联才能在没有角色作为参数的情况下使用此构造函数为此请打开Amazon Cognito 控制台中选择管理联合身份依次选择身份池并依次选择编辑身份池指定您的经过身份验证和未经身份验证的角色然后保存更改

检索 Amazon Cognito 身份

如果您允许未经身份验证的用户则可以立即检索最终用户的唯一 Amazon Cognito 标识符 (身份 ID)如果您正在对用户进行身份验证则可以在设置完凭证提供程序中的登录令牌后检索身份 ID

String identityId = credentialsProvidergetIdentityId()Logd(LogTag my ID is + identityId)

Note

请勿在应用程序的主线程中调用 getIdentityId()refresh() 或 getCredentials()自Android 30（API 级别 11）起如果您在应用程序的主线程上执行网络 IO您的应用程序将自动失败并引发 NetworkOnMainThreadException您将需要使用 AsyncTask 将您的代码移至后台线程有关更多信息请参阅 Android 文档您也可以调用 getCachedIdentityId() 以检索 ID但前提是已缓存在本地否则该方法将返回 null 值

197

Amazon Cognito 开发人员指南iOS - Objective-C

iOS - Objective-C您可以使用 Amazon Cognito 将具有有限权限的临时凭证传输到应用程序以便您的用户访问Amazon资源的费用Amazon Cognito 身份池同时支持经过身份验证和未经身份验证的身份提供Amazon凭证添加到应用程序中请执行以下步骤

1 选择管理身份池来自的Amazon Cognito 控制台创建一个身份池并复制启动器代码段2 如果您尚未完成此操作请将 Amazon Mobile SDK for iOS 添加到您的项目中有关说明请参阅设置

适用于 iOS 的移动软件开发工具包3 在您的源代码中请包括 AWSCore 标头

import ltAWSCoreAWSCorehgt


AWSCognitoCredentialsProvider credentialsProvider = [[AWSCognitoCredentialsProvider alloc]initWithRegionTypeAWSRegionUSEast1 identityPoolIdIDENTITY_POOL_ID]AWSServiceConfiguration configuration = [[AWSServiceConfiguration alloc]initWithRegionAWSRegionUSEast1 credentialsProvidercredentialsProvider]AWSServiceManagerdefaultServiceManagerdefaultServiceConfiguration = configuration

Note

如果您在 2015 年 2 月之前创建了身份池您将需要将您的角色与身份池重新关联才能在没有角色作为参数的情况下使用此构造函数为此请打开Amazon Cognito 控制台中选择管理身份池选择身份池选择编辑身份池指定您的经过身份验证和未经身份验证的角色然后保存更改


如果您允许未经身份验证的用户或者已设置完凭证提供程序中的登录令牌 (如果您正在对用户进行身份验证)则可以立即检索最终用户的唯一 Amazon Cognito 标识符 (身份 ID)

Retrieve your Amazon Cognito ID[[credentialsProvider getIdentityId] continueWithBlockîd(AWSTask task) if (taskerror) NSLog(Error taskerror) else the task result will contain the identity id NSString cognitoId = taskresult return nil]

Note

getIdentityId 为异步调用如果您已在提供程序上设置身份 ID则可以调用credentialsProvideridentityId 以检索已缓存在本地的身份但是如果您未在提供程序上设置身份 ID则调用 credentialsProvideridentityId 将返回 nil有关更多信息请参阅适用于 iOS 的移动开发工具包 API 参考

iOS - Swift

198

Amazon Cognito 开发人员指南JavaScript


1 选择管理身份池来自的Amazon Cognito 控制台创建一个身份池并复制启动器代码段2 如果您尚未完成此操作请将适用于 iOS 的移动开发工具包添加到您的项目中有关说明请参阅设置

适用于 iOS 的开发工具包3 在您的源代码中请包括 AWSCore 标头

import AWSCore


let credentialsProvider = AWSCognitoCredentialsProvider(regionType USEast1 identityPoolId IDENTITY_POOL_ID)let configuration = AWSServiceConfiguration(region USEast1 credentialsProvider credentialsProvider)AWSServiceManagerdefault()defaultServiceConfiguration = configuration

Note




Retrieve your Amazon Cognito IDcredentialsProvidergetIdentityId()continueWith(block (task) -gt AnyObject in if (taskerror = nil) print(Error + taskerrorlocalizedDescription) else the task result will contain the identity id let cognitoId = taskresult print(Cognito id (cognitoId)) return task)

Note


JavaScript如果您尚未创建身份池请在Amazon Cognito 控制台在使用之前AWSCognitoIdentityCredentials

199

Amazon Cognito 开发人员指南Unity

通过您的身份提供商配置身份池后您可以使用 AWSCognitoIdentityCredentials 验证用户身份要将应用程序凭证配置为使用 AWSCognitoIdentityCredentials则为 credentials 或基于每个服务配置设置 AWSConfig 属性以下示例使用 AWSConfig

Set the region where your identity pool exists (us-east-1 eu-west-1)AWSconfigregion = us-east-1

Configure the credentials provider to use your identity poolAWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId IDENTITY_POOL_ID Logins optional tokens used for authenticated login graphfacebookcom FBTOKEN wwwamazoncom AMAZONTOKEN accountsgooglecom GOOGLETOKEN appleidapplecom APPLETOKEN )

Make the call to obtain credentialsAWSconfigcredentialsget(function()

Credentials will be available when this function is called var accessKeyId = AWSconfigcredentialsaccessKeyId var secretAccessKey = AWSconfigcredentialssecretAccessKey var sessionToken = AWSconfigcredentialssessionToken

)

可选的 Logins 属性是身份提供商名称到这些提供商身份令牌的映射您如何从身份提供商获得令牌的方式取决于您使用的提供商例如如果 Facebook 是您的身份提供商之一则您可以使用来自FBloginFacebook 软件开发工具包的函数获取身份提供商令牌

FBlogin(function (response) if (responseauthResponse) logged in AWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId us-east-11699ebc0-7900-4099-b910-2df94f52a030 Logins graphfacebookcom responseauthResponseaccessToken )

consolelog(You are now logged in) else consolelog(There was a problem logging you in) )



var identityId = AWSconfigcredentialsidentityId

Unity您可以使用 Amazon Cognito 将具有有限权限的临时凭证传输到应用程序以便您的用户访问Amazon资源的费用Amazon Cognito 同时支持经过身份验证和未经身份验证的身份提供Amazon凭证添加到应用程序中请执行以下步骤

200

Amazon Cognito 开发人员指南Xamarin

1 选择管理身份池来自的Amazon Cognito 控制台创建一个身份池并复制启动器代码段2 如果您尚未完成此操作请下载并导入Amazon适用于 Unity 的 Mobile SDK软件包添加到您的项目中您

可以通过菜单ldquoAssetsrdquogtldquoImport PackagerdquogtldquoCustom Packagerdquo执行此操作3 将控制台中的启动器代码段粘贴到要从中调用 Amazon Cognito 的脚本中IDENTITY_POOL_ID 的值将

特定于您的账户

CognitoAWSCredentials credentials = new CognitoAWSCredentials ( IDENTITY_POOL_ID Cognito Identity Pool ID RegionEndpointUSEast1 Region )

4 将初始化的 Amazon Cognito 凭证传递到Amazon要使用的客户端所需的代码取决于要初始化的服务客户端将使用此提供程序获取用于访问的凭证Amazon资源的费用

Note




credentialsGetIdentityIdAsync(delegate(AmazonCognitoIdentityResultltstringgt result) if (resultException = null) Exception string identityId = resultResponse)

Xamarin您可以使用 Amazon Cognito 将具有有限权限的临时凭证传输到应用程序以便您的用户访问Amazon资源的费用Amazon Cognito 同时支持经过身份验证和未经身份验证的身份提供Amazon凭证添加到应用程序中请执行以下步骤

1 选择管理身份池来自的Amazon Cognito 控制台创建一个身份池并复制启动器代码段2 如果您尚未完成此操作请将Amazon适用于 Xamarin 的移动软件开发工具包到您的项目中有关说明

请参阅设置适用于 Xamarin 的开发工具包3 包括以下使用语句

using AmazonCognitoIdentity

4 将控制台中的启动器代码段粘贴到要从中调用 Amazon Cognito 的脚本中IDENTITY_POOL_ID 的值将特定于您的账户

CognitoAWSCredentials credentials = new CognitoAWSCredentials ( IDENTITY_POOL_ID Cognito Identity Pool ID RegionEndpointUSEast1 Region)


201

Amazon Cognito 开发人员指南访问Amazon服务

Note

注意如果您在 2015 年 2 月之前创建了身份池您将需要将您的角色与身份池重新关联才能在没有角色作为参数的情况下使用此构造函数为此请打开Amazon Cognito 控制台中选择管理身份池选择身份池选择编辑身份池指定您的经过身份验证和未经身份验证的角色然后保存更改



var identityId = await credentialsGetIdentityIdAsync()

访问Amazon服务Amazon Cognito 凭证提供程序经过初始化和刷新后您可以直接将其传递给初始化程序以便Amazon客户端例如下面的代码段将初始化 Amazon DynamoDB 客户端

Android

Create a service client with the providerAmazonDynamoDB client = new AmazonDynamoDBClient(credentialsProvider)

凭证提供程序与 Amazon Cognito 通信为经过身份验证和未经身份验证的用户检索唯一标识符并为具有有限权限的临时权限Amazon的凭证AmazonMobile SDK检索到的凭证的有效期为 1 小时提供程序会在凭证过期时进行刷新

iOS - Objective-C create a configuration that uses the providerAWSServiceConfiguration configuration = [AWSServiceConfiguration configurationWithRegionAWSRegionUSEast1 providercredentialsProvider]

get a client with the default service configurationAWSDynamoDB dynamoDB = [AWSDynamoDB defaultDynamoDB]


iOS - Swift get a client with the default service configurationlet dynamoDB = AWSDynamoDBdefault()

get a client with a custom configurationAWSDynamoDBregister(with configuration forKey USWest2DynamoDB)let dynamoDBCustom = AWSDynamoDB(forKey USWest2DynamoDB)

202



JavaScript

Create a service client with the providervar dynamodb = new AWSDynamoDB(region us-west-2)


Unity

create a service client that uses credentials provided by CognitoAmazonDynamoDBClient client = new AmazonDynamoDBClient(credentials REGION)


Xamarin

create a service client that uses credentials provided by Cognitovar client = new AmazonDynamoDBClient(credentials REGION)


身份池 (联合身份) 外部身份提供商使用 logins 属性您可以设置从身份提供商处接收的凭证此外您还可以将一个身份池与多个身份提供商关联例如您可以在logins属性从而唯一的 Amazon Cognito 身份会与两个身份提供商登录相关联无论最终用户使用哪个账户进行身份验证Amazon Cognito 都会返回相同的用户标识符

以下说明将指导您使用由 Amazon Cognito 身份池提供支持的身份提供商完成身份验证

主题bull Facebook (身份池) (p 204)bull Login with Amazon (身份池) (p 208)bull Google (身份池) (p 211)bull Sign in with Apple（身份池） (p 217)bull Open ID Connect 提供商 (身份池) (p 221)bull SAML 身份提供商 (身份池) (p 223)

203

Amazon Cognito 开发人员指南Facebook

Facebook (身份池)Amazon Cognito 身份池与 Facebook 集成以针对移动应用程序用户提供联合身份验证本部分介绍了如何使用 Facebook 作为身份提供商来注册和设置应用程序

设置 Facebook您需要先使用 Facebook 注册应用程序然后才能开始对 Facebook 用户进行身份验证并与 Facebook API进行交互

Facebook 开发人员门户将指导您完成设置应用程序的流程如果您尚未完成该流程则必须先完成该流程然后才能在 Amazon Cognito 身份池中集成 Facebook

设置 Facebook

1 在 Facebook 开发人员门户中使用 Facebook 凭证登录2 从 Apps (应用程序) 菜单中选择 Add a New App (添加新应用程序)3 选择一个平台然后完成快速启动流程

Android

Facebook 入门指南提供了有关与 Facebook 登录集成的更多信息

iOS - Objective-C


iOS - Swift


JavaScript


Unity


Xamarin

要提供 Facebook 身份验证请先按照以下相应的流程在应用程序中添加和设置 Facebook 开发工具包Amazon Cognito 身份池使用 Facebook 访问令牌生成与 Amazon Cognito 身份关联的唯一用户标识符

bull 由 Xamarin 开发的 Facebook iOS 开发工具包bull 由 Xamarin 开发的 Facebook Android 开发工具包

在 Amazon Cognito 联合身份控制台中配置外部提供商使用以下过程可以配置外部提供商

1 选择管理身份池来自的Amazon Cognito 控制台主页2 选择想要针对其启用 Facebook 作为外部提供商的身份池的名称此时将显示身份池的控制面板页

204


3 在控制面板页的右上角选择编辑身份池此时将显示编辑身份池页4 向下滚动并选择身份验证提供商以将其展开5 选择 Facebook 选项卡6 选择解锁7 输入您从 Facebook 获取的 Facebook 应用程序 ID然后选择保存更改

使用 FacebookAndroid

要提供 Facebook 身份验证请先按照 Facebook 指南将其开发工具包添加到应用程序中然后将ldquo用Facebook 登录rdquo按钮添加到 Android 用户界面Facebook 开发工具包使用会话对象来跟踪其状态AmazonCognito 使用来自此会话对象的访问令牌来对用户进行身份验证生成唯一标识符并根据需要授予用户对其他Amazon资源的费用

使用 Facebook 开发工具包对用户进行身份验证后立即将会话令牌添加到 Amazon Cognito 凭证提供程序

Facebook SDK 40 或更高版本

MapltString Stringgt logins = new HashMapltString Stringgt()loginsput(graphfacebookcom AccessTokengetCurrentAccessToken()getToken())credentialsProvidersetLogins(logins)

Facebook SDK 40 之前的版本

MapltString Stringgt logins = new HashMapltString Stringgt()loginsput(graphfacebookcom SessiongetActiveSession()getAccessToken())credentialsProvidersetLogins(logins)

Facebook 登录流程在其开发工具包中初始化一个单例会话Facebook 会话对象包含 Amazon Cognito 使用的 OAuth 令牌生成Amazon身份验证的最终用户的凭据Amazon Cognito 还可以使用令牌来检查用户数据库以确定是否存在与此特定 Facebook 身份匹配的用户如果用户已存在则 API 会返回现有的标识符否则将返回新的标识符标识符由本地设备上的客户端开发工具包自动缓存

Note

设置登录映射后必须调用 refresh 或 get 以实际获取 Amazon 凭证

iOS - Objective-C

要添加 Facebook 身份验证请先按照 Facebook 指南将 Facebook 开发工具包集成到应用程序中然后向用户界面添加ldquo用 Facebook 登录rdquo按钮Facebook 开发工具包使用会话对象来跟踪其状态AmazonCognito 使用来自此会话对象的访问令牌来对用户进行身份验证并将其绑定到唯一的 Amazon Cognito 身份池（联合身份）

要向 Amazon Cognito 提供 Facebook 访问令牌请实施任务提供商管理器协议

在 logins 方法的实现中返回一个包含 AWSIdentityProviderFacebook 的词典此词典充当键而经过身份验证的 Facebook 用户的当前访问令牌充当值如以下代码示例所示

- (AWSTaskltNSDictionaryltNSString NSString gt gt )logins FBSDKAccessToken fbToken = [FBSDKAccessToken currentAccessToken] if(fbToken) NSString token = fbTokentokenString

205


return [AWSTask taskWithResult AWSIdentityProviderFacebook token ] else return [AWSTask taskWithError[NSError errorWithDomainFacebook Login code-1 userInfoerrorNo current Facebook access token]]

当您实例化 AWSCognitoCredentialsProvider 时在构造函数中传递实施AWSIdentityProviderManager 作为 identityProviderManager 的值的类有关更多信息请转到 AWSCognitoCredentialsProvider 参考页面并选择initWithRegionTypeidentityPoolIdidentityProviderManager

iOS - Swift




class FacebookProvider NSObject AWSIdentityProviderManager func logins() -gt AWSTaskltNSDictionarygt if let token = AccessTokencurrentauthenticationToken return AWSTask(result [AWSIdentityProviderFacebooktoken]) return AWSTask(errorNSError(domain Facebook Login code -1 userInfo [Facebook No current Facebook access token]))


JavaScript

要提供 Facebook 身份验证请按照适用于 Web 的 Facebook 登录在您的网站上添加ldquo用 Facebook 登录rdquo按钮Facebook 开发工具包使用会话对象来跟踪其状态Amazon Cognito 使用来自此会话对象的访问令牌来对用户进行身份验证生成唯一标识符并根据需要授予用户对其他Amazon资源的费用


FBlogin(function (response)

Check if the user logged in successfully if (responseauthResponse)

consolelog(You are now logged in)

Add the Facebook access token to the Amazon Cognito credentials login map AWSconfigcredentials = new AWSCognitoIdentityCredentials(

206


IdentityPoolId IDENTITY_POOL_ID Logins graphfacebookcom responseauthResponseaccessToken )

Obtain AWS credentials AWSconfigcredentialsget(function() Access AWS resources here )

else consolelog(There was a problem logging you in)

)

Facebook 开发工具包获取 Amazon Cognito 使用的 OAuth 令牌生成Amazon身份验证的最终用户的凭据Amazon Cognito 还可以使用令牌来检查用户数据库以确定是否存在与此特定 Facebook 身份匹配的用户如果用户已存在则 API 会返回现有的标识符否则将返回新的标识符标识符由本地设备上的客户端开发工具包自动缓存

Note

设置登录映射后必须调用 refresh 或 get 以获取凭证有关代码示例请参阅 JavaScript 自述文件中的ldquo使用案例 17将用户池与 Cognito 身份集成rdquo

Unity

要提供 Facebook 身份验证请先按照Facebook 指南将其开发工具包添加到应用程序中并对其进行设置Amazon Cognito 使用来自 ldquoFBrdquo 对象的 Facebook 访问令牌生成与 Amazon Cognito 身份关联的唯一用户标识符


void Start() FBInit(delegate() if (FBIsLoggedIn) User already logged in from a previous session AddFacebookTokenToCognito() else FBLogin (email FacebookLoginCallback) )

void FacebookLoginCallback(FBResult result) if (FBIsLoggedIn) AddFacebookTokenToCognito() else DebugLog(FB Login error)

void AddFacebookTokenToCognito() credentialsAddLogin (graphfacebookcom AccessTokenCurrentAccessTokenTokenString)

207

Amazon Cognito 开发人员指南Login with Amazon

在使用 FBLogin() 之前您应该确保调用 FBIsLoggedIn 并确保 FBAccessToken 为 true

XamarinXamarin for Android

public void InitializeFacebook() FacebookSdkSdkInitialize(thisApplicationContext) callbackManager = CallbackManagerFactoryCreate() LoginManagerInstanceRegisterCallback(callbackManager new FacebookCallback amplt LoginResult ampgt () HandleSuccess = loginResult = ampgt var accessToken = loginResultAccessToken credentialsAddLogin(graphfacebookcom accessTokenToken) open new activity HandleCancel = () = ampgt throw error message HandleError = loginError = ampgt throw error message ) LoginManagerInstanceLogInWithReadPermissions(this new List amplt string ampgt public_profile )

Xamarin for iOS

public void InitializeFacebook() LoginManager login = new LoginManager() loginLogInWithReadPermissions(readPermissionsToArray() delegate(LoginManagerLoginResult result NSError error) if (error = null) throw error message else if (resultIsCancelled) throw error message else var accessToken = loginResultAccessToken credentialsAddLogin(graphfacebookcom accessTokenToken) open new view controller )

Login with Amazon (身份池)Amazon Cognito 与 Login with Amazon 集成以针对移动应用程序和 Web 应用程序用户提供联合身份验证本部分介绍如何使用 Login with Amazon 作为身份提供商来注册和设置应用程序

可通过两种方法来设置 Login with Amazon以与 Amazon Cognito 结合使用如果您不确定使用哪一种方法或者需要使用两种方法请参阅以 Amazon 登录常见问题中的ldquo设置 Login with Amazonrdquo

bull 通过 Amazon 开发人员门户如果您想让最终用户通过 Login with Amazon 进行身份验证但您没有Seller Central 账户请使用此方法

bull 使用 httploginamazoncom 并通过 Seller Central 设置如果您是使用 Seller Central 的零售商请使用此方法

208


Note

对于 Xamarin请按照 Xamarin 入门指南将 Login with Amazon 集成到 Xamarin 应用程序中Note

Unity 平台本身不支持 Login with Amazon 集成目前进行集成需要使用 Web 视图来完成浏览器登录流程

设置 Login with Amazon要实施 Login with Amazon请执行以下操作之一

bull 通过 Amazon 开发人员门户为应用程序创建安全配置文件 ID如果您想让最终用户通过 Amazon 进行身份验证但没有 Seller Central 账户请使用此方法开发人员门户 Login with Amazon 文档将指导您完成在应用程序中设置 Login with Amazon下载客户端开发工具包及在 Amazon 开发人员平台上声明应用程序等流程记下安全配置文件 ID因为您将需要在创建 Amazon Cognito 身份池时输入它作为 Amazon 应用程序 ID如获取凭证 (p 196)

bull 使用 httploginamazoncom通过 Seller Central 为应用程序创建应用程序 ID如果您是使用 SellerCentral 的零售商请使用此方法Seller Central Login with Amazon 文档将指导您完成在应用程序中设置以 Amazon 登录下载客户端开发工具包及在 Amazon 开发人员平台上声明应用程序等流程记下应用程序 ID因为您将需要在创建 Amazon Cognito 身份池时输入它作为 Amazon 应用程序 ID如获取凭证

在 Amazon Cognito 控制台控制台中配置外部提供商选择管理身份池来自的Amazon Cognito 控制台主页

1 选择想要针对其启用ldquo以 Amazon 登录rdquo作为外部提供商的身份池的名称此时将显示身份池的控制面板页

2 在控制面板页的右上角选择编辑身份池此时将显示ldquoEdit identity poolrdquo页3 向下滚动并选择身份验证提供商以将其展开4 选择 Amazon 选项卡5 选择解锁6 输入从 Amazon 获取的 Amazon 应用程序 ID然后选择保存更改

使用 Login with AmazonAndroid实施 Amazon 登录后您可以使用 TokenListener 接口的 onSuccess 方法将令牌传递给 Amazon Cognito 凭证提供程序代码如下所示

Overridepublic void onSuccess(Bundle response) String token = responsegetString(AuthzConstantsBUNDLE_KEYTOKENval) MapltString Stringgt logins = new HashMapltString Stringgt() loginsput(wwwamazoncom token) credentialsProvidersetLogins(logins)

使用 Login with AmazoniOS - Objective-C实施 Amazon 登录后您可以使用 AMZNAccessTokenDelegate 的 requestDidSucceed 方法将令牌传递给Amazon Cognito 凭证提供程序

- (void)requestDidSucceed(APIResult )apiResult

209


if (apiResultapi == kAPIAuthorizeUser) [AIMobileLib getAccessTokenForScopes[NSArray arrayWithObjectprofile] withOverrideParamsnil delegateself] else if (apiResultapi == kAPIGetAccessToken) credentialsProviderlogins = (AWSCognitoLoginProviderKeyLoginWithAmazon) apiResultresult

使用 Login with AmazoniOS - Swift实施 Amazon 登录后您可以将令牌传递给 Amazon Cognito 凭证提供程序其中包含requestDidSucceed方法AMZNAccessTokenDelegate

func requestDidSucceed(apiResult APIResult) if apiResultapi == APIAuthorizeUser AIMobileLibgetAccessTokenForScopes([profile] withOverrideParams nil delegate self) else if apiResultapi == APIGetAccessToken credentialsProviderlogins = [AWSCognitoLoginProviderKeyLoginWithAmazonrawValue apiResultresult]

使用 Login with AmazonJavaScript在用户通过 Login with Amazon 进行身份验证并重定向回网站后系统会在查询字符串中提供 Login withAmazon access_token将此令牌传递到凭证登录映射

AWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId IDENTITY_POOL_ID Logins wwwamazoncom Amazon Access Token )

使用 Login with AmazonXamarinXamarin for Android

AmazonAuthorizationManager manager = new AmazonAuthorizationManager(this BundleEmpty)

var tokenListener = new APIListener Success = response =gt Get the auth token var token = responseGetString(AuthzConstantsBUNDLE_KEYTokenVal) credentialsAddLogin(wwwamazoncom token)

Try and get existing loginmanagerGetToken(new[] profile tokenListener)

Xamarin for iOS

在 AppDelegatecs 中插入以下内容

210

Amazon Cognito 开发人员指南Google

public override bool OpenUrl (UIApplication application NSUrl url string sourceApplication NSObject annotation) Pass on the url to the SDK to parse authorization code from the url bool isValidRedirectSignInURL = AIMobileLibHandleOpenUrl (url sourceApplication) if(isValidRedirectSignInURL) return false

App may also want to handle url return true

然后在 ViewControllercs 中执行以下操作

public override void ViewDidLoad () baseLoadView ()

Here we create the Amazon Login Button btnLogin = UIButtonFromType (UIButtonTypeRoundedRect) btnLoginFrame = new RectangleF (55 206 209 48) btnLoginSetTitle (Login using Amazon UIControlStateNormal) btnLoginTouchUpInside += (sender e) =gt AIMobileLibAuthorizeUser (new [] profile new AMZNAuthorizationDelegate ()) ViewAddSubview (btnLogin)

Class that handles Authentication SuccessFailurepublic class AMZNAuthorizationDelegate AIAuthenticationDelegate public override void RequestDidSucceed(ApiResult apiResult) Your code after the user authorizes application for requested scopes var token = apiResult[access_token] credentialsAddLogin(wwwamazoncomtoken)

public override void RequestDidFail(ApiError errorResponse) Your code when the authorization fails InvokeOnMainThread(() =gt new UIAlertView(User Authorization Failed errorResponseErrorMessage null Ok null)Show())

Google (身份池)Amazon Cognito 与 Google 集成以针对移动应用程序用户提供联合身份验证本部分介绍了如何使用Google 作为身份提供商来注册和设置应用程序

AndroidNote

如果您的应用程序使用 Google 并且可在多个移动平台上使用则应将其配置为 OpenID Connect提供商 (p 221)将所有创建的客户端 ID 添加为附加受众值以便更好地集成要了解有关Google 跨客户端身份模式的更多信息请参阅跨客户端身份

设置 Google

211


要启用 Google Sign-in for Android您必须为应用程序创建 Google Developers 控制台项目

1 转到 Google Developers 控制台并创建一个新项目2 在 APIs and auth (API 和授权) gt APIs (API) gt Social APIs (社交 API) 下启用 Google API3 在 APIs and auth (API 和授权) gt Credentials (凭证) gt OAuth consent screen (OAuth 同意屏幕) 下创建

在应用程序请求访问用户的私有数据时将向用户显示的对话4 在 Credentials (凭证) gt Add Credentials (添加凭证) 下创建适用于 Android 的 OAuth 20 客户端 ID您

将需要针对打算为其开发的每个平台 (如 WebiOSAndroid) 提供一个客户端 ID5 在 Credentials (凭证) gt Add Credentials (添加凭证) 下创建一个服务账户控制台将提醒您系统已创

建新的公有私有密钥

有关使用 Google Developers 控制台的更多说明请参阅在 Developers 控制台中管理项目

有关将 Google 集成到 Android 应用程序的更多信息请参阅适用于 Android 的 Google 文档

在 Amazon Cognito 控制台控制台中配置外部提供商

选择管理身份池来自的Amazon Cognito 控制台主页

1 选择想要针对其启用 Google 作为外部提供商的身份池的名称此时将显示身份池的控制面板页2 在控制面板页的右上角选择编辑身份池此时将显示ldquoEdit identity poolrdquo页3 向下滚动并选择身份验证提供商以将其展开4 选择 Google 选项卡5 选择解锁6 输入从 Google 获取的 Google 客户端 ID然后保存更改

使用 Google

要在应用程序中启用ldquo用 Google 登录rdquo请按照适用于 Android 的 Google 文档中的说明执行操作成功通过身份验证后将生成一个 OpenID Connect 身份验证令牌供 Amazon Cognito 用于对用户进行身份验证并生成一个唯一标识符

以下示例代码显示如何从 Google Play 服务检索身份验证令牌

GooglePlayServicesUtilisGooglePlayServicesAvailable(getApplicationContext())AccountManager am = AccountManagerget(this)Account[] accounts = amgetAccountsByType(GoogleAuthUtilGOOGLE_ACCOUNT_TYPE)String token = GoogleAuthUtilgetToken(getApplicationContext() accounts[0]name audienceserverclient_idYOUR_GOOGLE_CLIENT_ID)MapltString Stringgt logins = new HashMapltString Stringgt()loginsput(accountsgooglecom token)credentialsProvidersetLogins(logins)

iOS - Objective-CNote


要启用 Google Sign-in for iOS您必须为应用程序创建 Google Developers 控制台项目

设置 Google

1 转到 Google Developers 控制台并创建一个新项目

212


2 在 APIs and auth (API 和授权) gt APIs (API) gt Social APIs (社交 API) 下启用 Google API3 在 APIs and auth (API 和授权) gt Credentials (凭证) gt OAuth consent screen (OAuth 同意屏幕) 下创

建在应用程序请求访问用户的私有数据时将向用户显示的对话4 在 Credentials (凭证) gt Add Credentials (添加凭证) 下创建适用于 iOS 的 OAuth 20 客户端 ID您将

需要针对打算为其开发的每个平台 (如 WebiOSAndroid) 提供一个客户端 ID5 在 Credentials (凭证) gt Add Credentials (添加凭证) 下创建一个服务账户控制台将提醒您系统已

创建新的公有私有密钥


有关将 Google 集成到 iOS 应用程序的更多信息请参阅适用于 iOS 的 Google 文档


在 Amazon Cognito 控制台中配置外部提供商


使用 Google

要在应用程序中启用ldquo用 Google 登录rdquo请按照适用于 iOS 的 Google 文档中的说明执行操作成功通过身份验证后将生成一个 OpenID Connect 身份验证令牌供 Amazon Cognito 用于对用户进行身份验证并生成一个唯一标识符

成功的身份验证会导致GTMOAuth2Authentication对象其中包含id_token供 Amazon Cognito 用于对用户进行身份验证并生成一个唯一标识符

- (void)finishedWithAuth (GTMOAuth2Authentication )auth error (NSError ) error NSString idToken = [authparameters objectForKeyid_token] credentialsProviderlogins = (AWSCognitoLoginProviderKeyGoogle) idToken

iOS - SwiftNote


要启用 Google Sign-in for iOS您需要为应用程序创建 Google Developers 控制台项目

设置 Google

1 转到 Google Developers 控制台并创建一个新项目2 在 APIs and auth (API 和授权) gt APIs (API) gt Social APIs (社交 API) 下启用 Google API3 在 APIs and auth (API 和授权) gt Credentials (凭证) gt OAuth consent screen (OAuth 同意屏幕) 下创


需要针对打算为其开发的每个平台 (如 WebiOSAndroid) 提供一个客户端 ID

213


5 在 Credentials (凭证) gt Add Credentials (添加凭证) 下创建一个服务账户控制台将提醒您系统已创建新的公有私有密钥






使用 Google



func finishedWithAuth(auth GTMOAuth2Authentication error NSError) if error = nil print(errorlocalizedDescription) else let idToken = authparametersobjectForKey(id_token) credentialsProviderlogins = [AWSCognitoLoginProviderKeyGooglerawValue idToken]

JavaScriptNote


设置 Google

要启用适用于您的 Web 应用程序的 Google Sign-in您需要为应用程序创建 Google Developers 控制台项目


在应用程序请求访问用户的私有数据时将向用户显示的对话4 在 Credentials (凭证) gt Add Credentials (添加凭证) 下创建适用于您的 Web 应用程序的 OAuth 20 客户

端 ID您将需要针对打算为其开发的每个平台（如 WebiOSAndroid）提供一个客户端 ID

214







使用 Google

要在应用程序中启用ldquo用 Google 登录rdquo请按照适用于 Web 的 Google 文档中的说明执行操作

成功通过身份验证后将生成一个响应对象包含id_token供 Amazon Cognito 用于对用户进行身份验证并生成一个唯一标识符

function signinCallback(authResult) if (authResult[status][signed_in])

Add the Google access token to the Amazon Cognito credentials login map AWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId IDENTITY_POOL_ID Logins accountsgooglecom authResult[id_token] )


Unity设置 Google



在应用程序请求访问用户的私有数据时将向用户显示的对话4 对于 Unity您需要创建三个 ID其中两个用于 Android另一个用于 iOS在 Credentials (凭证) gt Add

Credentials (添加凭证) 下bull Android为 Android 创建一个适用于 Android 的 OAuth 20 客户端 ID 和一个适用于 Web 应用程序的

OAuth 20 客户端 ID

215


bull iOS 创一个适用于 iOS 的 OAuth 20 客户端 ID5 在 Credentials (凭证) gt Add Credentials (添加凭证) 下创建一个服务账户控制台将提醒您系统已创


在 IAM 控制台中创建 OpenID 提供商

1 接下来您需要在 IAM 控制台中创建一个 OpenID 提供商有关如何设置 OpenID 提供商的说明请参阅使用 OpenID Connect 身份提供商 (p 221)

2 当系统提示您输入提供商 URL 时请输入 httpsaccountsgooglecom3 当系统提示您在 Audience (受众) 字段中输入一个值时请输入您在之前步骤中创建的三个客户端 ID 中的

任意一个4 创建提供商后选择该提供商名称并添加另外两个受众提供剩余的两个客户端 ID




安装 Unity Google 插件

1 将适用于 Unity 的 Google Play Games 插件添加到 Unity 项目2 在 Unity 中从 Windows 菜单使用适用于 Android 和 iOS 平台的三个 ID 配置插件

使用 Google


void Start() PlayGamesClientConfiguration config = new PlayGamesClientConfigurationBuilder()Build() PlayGamesPlatformInitializeInstance(config) PlayGamesPlatformDebugLogEnabled = true PlayGamesPlatformActivate() SociallocalUserAuthenticate(GoogleLoginCallback)

void GoogleLoginCallback(bool success) if (success) string token = PlayGamesPlatformInstanceGetIdToken() credentialsAddLogin(accountsgooglecom token) else DebugLogError(Google login failed If you are not running in an actual AndroidiOS device this is expected)

216

Amazon Cognito 开发人员指南使用 Apple 登录

XamarinNote

Xamarin 平台本身不支持 Google 集成目前进行集成需要使用 Web 视图来完成浏览器登录流程要了解 Google 集成如何与其他开发工具包配合使用请选择另一个平台

要在应用程序中启用 Login with Google您将需要对用户进行身份验证并从其获取 OpenID Connect 令牌Amazon Cognito 使用此令牌生成与 Amazon Cognito 身份关联的唯一用户标识符遗憾的是适用于Xamarin 的 Google 开发工具包不允许您检索 OpenID Connect 令牌因此您必须使用替代客户端或 Web视图中的 Web 流程

拥有令牌后您可以在 CognitoAWSCredentials 中对其进行设置

credentialsAddLogin(accountsgooglecom token)

Note


Sign in with Apple（身份池）Amazon Cognito 与 Sign with Apple 集成以针对移动应用程序和 Web 应用程序用户提供联合身份验证此节介绍如何使用 Sign in with Apple 作为身份提供商来注册和设置应用程序

将 Sign in with Apple 作为身份验证提供商添加到身份池的过程包括两个步骤首先在应用程序中集成 Signin with Apple然后在身份池中配置 Sign in with Apple

设置 Sign in with Apple要将 Sign in with Apple 配置为身份提供商您必须向 Apple 注册您的应用程序才能接收客户端 ID

1 创建 Apple 开发人员账户2 使用 Apple 凭证登录3 在左侧导航窗格中选择 Certificates IDs amp Profiles (证书ID 和配置文件)4 在左侧导航窗格中选择Identifiers (标识符)5 在 Identifiers (标识符) 页面上选择 + 图标6 在 Register a New Identifier (注册新标识符) 页面上选择 App IDs (应用程序 ID)然后选择 Continue

(继续)7 在存储库的注册应用程序 ID页面上执行以下操作

a 在 Description (描述) 下方键入描述b 在 Bundle ID (服务包 ID) 下键入标识符记下此捆绑商品 ID因为您需要此值才能将 Apple 配置为

身份池中的提供商c 在 Capabilities (功能) 下方选择 Sign In with Apple (使用 Apple 登录)然后选择 Edit (编辑)d 在存储库的使用 Apple 登录应用程序 ID 配置页面上为您的应用程序选择适当的设置然后选

择Savee 选择 Continue (继续)

8 在 Confirm your App ID (确认您的应用程序 ID) 页面上选择 Register (注册)9 继续执行步骤10如果要将 Sign with Apple 与本机 iOS 应用程序集成请使用步骤 11 适用于您希望与

Sign in with Apple JS 集成的应用程序

217


10 在存储库的标识符页面上暂停应用程序 ID在页面右侧选择 Services IDs (服务 ID)然后选择 plus +(加号 +) 图标

11 在 Register a New Identifier (注册新标识符) 页面上选择 Services IDs (服务 ID)然后选择 Continue(继续)

12 在 Register an Services ID (注册服务 ID) 页面上执行以下操作

a 在 Description (描述) 下方键入描述b 在 Identifier (标识符) 下方键入标识符记下服务 ID因为您需要此值才能将 Apple 配置为身份

池中的提供商c 选择 Sign In with Apple (使用 Apple 登录)然后选择 Configure (配置)d 在 Web Authentication Configuration (Web 身份验证配置) 页面上选择 Primary App ID (主应用程

序 ID)UNDER网站 URLs中选择+图标对于 Domains and Subdomains (域和子域)输入应用程序的域名在 Return URL (返回 URL) 中输入授权在进行 Sign in with Apple 身份验证后重定向到的回调 URL

e 选择 Nextf 选择 Continue (继续)然后选择 Register (注册)

13 在左侧导航窗格中选择 Keys (密钥)14 在 Keys (密钥) 页面上选择 + 图标15 在 Register a New Key (注册新密钥) 页面上执行以下操作

a 在 Key Name (密钥名称) 下方键入密钥名称b 选择 Sign In with Apple (使用 Apple 登录)然后选择 Configure (配置)c 在 Configure Key (配置密钥) 页面上选择 Primary App ID (主应用程序 ID)然后选择 Save (保

存)d 选择 Continue (继续)然后选择 Register (注册)

Note

要将 Sign in with Apple 与本机 iOS 应用程序集成请参阅通过 Sign in with Apple 实施用户身份验证要在本机 iOS 以外的平台中集成 Sign in with Apple请参阅 Sign in with Apple J

配置外部提供商Amazon Cognito 联合身份控制台控制台中使用以下过程可以配置外部提供商

1 选择管理身份池来自的Amazon Cognito 控制台主页2 选择想要针对其启用 Apple 作为外部提供商的身份池的名称3 在控制面板的右上角选择 Edit identity pool (编辑身份池)4 向下滚动并选择身份验证提供商以将其展开5 选择 Apple 选项卡6 输入捆绑 ID从 httpsdeveloperapplecom 获得的信息然后选择 Save changes (保存更改)7 如果您使用使用 Apple 登录使用本机 iOS 应用程序请输入BundleID你是从开发者 applecom 获得

的或者如果您在 Web 或其他应用程序中使用 Sign in with Apple请输入服务 ID然后选择 Savechanges (保存更改)

在 Amazon Cognito 联合身份 CLI 中以 Sign with Apple 作为提供商的示例此示例以 Sign in with Apple 作为身份提供商创建一个名为 MyIdentityPool 的身份池

218


aws cognito-identity create-identity-pool --identity-pool-name MyIdentityPool--supported-login-providers appleidapplecom=samepleappleclientid

有关更多信息请参阅创建身份池

生成 Amazon Cognito 身份 ID

此示例生成（或检索）Amazon Cognito ID这是一个公有 API因此您不需要任何凭证即可调用此 API

aws cognito-identity get-id --identity-pool-id SampleIdentityPoolId --loginsappleidapplecom=SignInWithAppleIdToken

有关更多信息请参阅 get-id

获取 Amazon Cognito 身份 ID 的凭证

此示例返回用于提供的身份 ID 和 Sign in with Apple 登录的凭证这是一个公有 API因此您不需要任何凭证即可调用此 API

aws cognito-identity get-credentials-for-identity --identity-idSampleIdentityId --logins appleidapplecom=SignInWithAppleIdToken

有关更多信息请参阅 get-credentials-for-identity

使用 Sign with AppleAndroidApple 不提供支持 Sign in with Apple for Android 的开发工具包您可以改为在 Web 视图中使用 Web 流

bull 要在应用程序中配置 Sign in with Apple请按照 Apple 文档中的配置您的 Web 页面以使用 Sign in withApple操作

bull 要将 Sign in with Apple 按钮添加到 Android 用户界面请按照 Apple 文档中的显示和配置 Sign in withApple 按钮操作

bull 要使用 Sign in with Apple 安全地对用户进行身份验证请按照 Apple 文档中的配置您的 Web 页面以使用Sign in with Apple 操作

使用 Sign with Apple 使用会话对象来跟踪其状态Amazon Cognito 使用来自此会话对象的 ID 令牌来对用户进行身份验证生成唯一标识符并根据需要授予用户对其他Amazon资源的费用

Overridepublic void onSuccess(Bundle response) String token = responsegetString(id_token) MapltString Stringgt logins = new HashMapltString Stringgt() loginsput(appleidapplecom token) credentialsProvidersetLogins(logins)

使用 Sign in with AppleiOS - Objective-CApple 为原生 iOS 应用程序中的 Sign in with Apple 提供了开发工具包支持要在本机 iOS 设备中使用 Signin with Apple 实施用户身份验证请按照 Apple 文档中的使用 Sign in with Apple 实施用户身份验证操作

Amazon Cognito 使用 ID 令牌来对用户进行身份验证生成唯一标识符并根据需要授予用户对其他Amazon资源的费用

(void)finishedWithAuth (ASAuthorizationAppleIDCredential )auth error (NSError ) error NSString idToken = [ASAuthorizationAppleIDCredential objectForKeyidentityToken]

219


credentialsProviderlogins = appleidapplecom idToken

所用 Sign in with AppleiOS - SwiftApple 为原生 iOS 应用程序中的 Sign in with Apple 提供了开发工具包支持要在本机 iOS 设备中使用 Signin with Apple 实施用户身份验证请按照 Apple 文档中的使用 Sign in with Apple 实施用户身份验证操作


有关在 iOS 中设置 Sign in with Apple 的更多信息请参阅设置 Sign in with Apple

func finishedWithAuth(auth ASAuthorizationAppleIDCredential error NSError) if error = nil print(errorlocalizedDescription) else let idToken = authidentityToken credentialsProviderlogins = [appleidapplecom idToken]

使用 Sign with AppleJavaScriptApple 不提供支持 Sign in with Apple for JavaScript 的开发工具包您可以改为在 Web 视图中使用 Web流


bull 要将 Sign in with Apple 按钮添加到 JavaScript 用户界面请按照 Apple 文档中的显示和配置 Sign in withApple 按钮操作



function signinCallback(authResult) Add the apples id token to the Amazon Cognito credentials login map AWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId IDENTITY_POOL_ID Logins appleidapplecom authResult[id_token] )


使用 Sign with AppleXamarin我们没有支持 Sign in with Apple for Xamarin 的开发工具包您可以改为在 Web 视图中使用 Web 流

220

Amazon Cognito 开发人员指南OpenID Connect 提供商


bull 要将 Sign in with Apple 按钮添加到 Xamarin 用户界面请按照 Apple 文档中的显示和配置 Sign in withApple 按钮操作




credentialsAddLogin(appleidapplecom token)

Open ID Connect 提供商 (身份池)OpenID Connect是一种用于身份验证的开放标准受多个登录提供商支持Amazon Cognito 支持将身份与通过AmazonIdentity and Access Management

添加 OpenID Connect 提供商

有关如何创建 OpenID Connect 提供商的信息请参阅 IAM 文档

将提供商与 Amazon Cognito 关联

在 IAM 控制台中创建 OpenID Connect 提供商后您可以将其与身份池关联配置的所有提供商将显示在OpenID Connect 提供商标头下 Amazon Cognito 控制台中的 ldquoEdit Identity Poolrdquo 屏幕上

您可以将多个 OpenID Connect 提供商与一个身份池关联

使用 OpenID Connect

请参阅提供商的文档了解如何登录并接收 ID 令牌

拥有令牌后将此令牌添加到登录映射使用提供商的 URI 作为键

验证 OpenID Connect 令牌

首次与 Amazon Cognito 集成时您可能会收到InvalidToken异常务必要了解 Amazon Cognito 如何验证 OpenID Connect 令牌

Note

正如此处指定的（httpstoolsietforghtmlrfc7523）Amazon Cognito 留出 5 分钟的宽限期来处理系统之间的任何时钟偏差

221


1 iss 参数必须与登录映射中使用的密钥匹配（如 loginprovidercom）2 签名必须有效签名必须可通过 RSA 公有密钥进行验证3 托管公有密钥的证书的指纹与 OpenId Connect 提供商上的相应配置匹配4 如果存在 azp 参数请针对 OpenId Connect 提供商中列出的客户端 ID 检查此值5 如果不存在 azp 参数请针对 OpenId Connect 提供商中列出的客户端 ID 检查 aud 参数

jwtio 网站是用于解码令牌以验证这些值的宝贵资源

AndroidMapltString Stringgt logins = new HashMapltString Stringgt()loginsput(loginprovidercom token)credentialsProvidersetLogins(logins)

iOS - Objective-CcredentialsProviderlogins = loginprovidercom token

iOS - Swift要向 Amazon Cognito 提供 OIDC ID 令牌请实施AWSIdentityProviderManager协议

在登录方法的实现中返回包含您配置的 OIDC 提供商名称的词典此词典充当键而经过身份验证的用户的当前 ID 令牌充当值如以下代码示例所示

class OIDCProvider NSObject AWSIdentityProviderManager func logins() -gt AWSTaskltNSDictionarygt let completion = AWSTaskCompletionSourceltNSStringgt() getToken(tokenCompletion completion) return completiontaskcontinueOnSuccessWith (task) -gt AWSTaskltNSDictionarygt in loginprovidername is the name of the OIDC provider as setup in the Amazon Cognito console return AWSTask(result[loginprovidernametaskresult]) as AWSTaskltNSDictionarygt

func getToken(tokenCompletion AWSTaskCompletionSourceltNSStringgt) -gt Void get a valid oidc token from your server or if you have one that hasnt expired cached return it

TODO code to get token from your server

if error getting token set error appropriately tokenCompletionset(errorNSError(domain OIDC Login code -1 userInfo [Unable to get OIDC token Details about your error])) else tokenCompletionset(resultresult from server id token)

当您实例化 AWSCognitoCredentialsProvider 时在构造函数中传递实施 AWSIdentityProviderManager 作为 identityProviderManager 的值的类有关更多信息请转到 AWSCognitoCredentialsProvider 参考页面并选择initWithRegionTypeidentityPoolIdidentityProviderManager

222

Amazon Cognito 开发人员指南SAML 身份提供商

JavaScript

AWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId IDENTITY_POOL_ID Logins loginprovidercom token )

Unity

credentialsAddLogin(loginprovidercom token)

Xamarin


SAML 身份提供商 (身份池)Amazon Cognito 支持通过身份提供商并运用安全断言标记语言 20 (SAML 20) 来进行身份验证您可以使用支持 SAML 和 Amazon Cognito 结合使用的身份提供商为用户提供简单的登录流程支持 SAML 的身份提供商可以指定可由用户担任的 IAM 角色以便授予不同的用户不同的权限集

为 SAML 提供商配置身份池以下步骤介绍了如何配置身份池以使用基于 SAML 的提供商

Note

在配置身份池以支持 SAML 提供商前您必须先在IAM 控制台有关更多信息请参阅将第三方SAML 解决方案提供商与集成Amazon中的IAM 用户指南

配置身份池以支持 SAML 提供商

1 登录到Amazon Cognito 控制台控制台中选择管理身份池然后选择创建新的身份池2 在身份验证提供商部分中选择 SAML 选项卡3 选择 SAML 提供商的 ARN然后选择创建池

配置 SAML 身份提供商创建 SAML 提供商后配置 SAML 身份提供商以在身份提供商和 Amazon 之间添加信赖方信任许多身份提供商允许指定一个 URL以便其从中读取包含信赖方信息和证书的 XML 文档对于 Amazon您可以使用 httpssigninawsamazoncomstaticsaml-metadataxml下一步是配置来自身份提供商的 SAML 断言响应以填充 Amazon 所需的断言有关申请配置的详细信息请参阅针对身份验证响应配置 SAML 断言

使用 SAML 自定义用户角色通过将 SAML 与 Amazon Cognito 身份结合使用可针对最终用户自定义角色基于 SAML 的身份提供商仅支持增强型流程 (p 180)您无需为身份池指定经过身份验证或未经身份验证的角色即可使用基于 SAML的身份提供商httpsawsamazoncomSAMLAttributesRole 声明属性指定一个或多个逗号分隔的角色和提供商 ARN 对这些是允许用户担任的角色可对 SAML 身份提供商进行配置以根据身份提

223

Amazon Cognito 开发人员指南已经过开发人员验证的身份

供商提供的用户属性信息填充角色属性如果 SAML 断言中收到了多个角色则应在调用 customRoleArn时填充可选参数 getCredentialsForIdentity如果参数中收到的输入角色与 SAML 断言中断言的角色相匹配则该角色将由用户担任

使用 SAML 身份提供商对用户进行身份验证要与基于 SAML 的身份提供商进行联合您必须确定要用于启动登录的 URLAmazon 联合使用 IdP 启动的登录在 AD FS 20 中URL 采用 httpsltfqdngtadfslsIdpInitiatedSignOnaspxloginToRp=urnamazonwebservices 格式

要在 Amazon Cognito 中添加对 SAML 身份提供商的支持您必须先使用 SAML 身份提供商从 iOS 或Android 应用程序对用户进行身份验证用于通过 SAML 身份提供商进行集成和身份验证的代码因 SAML 身份提供商而异对用户进行身份验证后您可以使用 Amazon Cognito API 向 Amazon Cognito 身份提供生成的 SAML 断言

Android如果您使用的是 Android 开发工具包您可以使用 SAML 断言填充登录映射如下所示

Map logins = new HashMap()loginsput(arnawsiamaws account idsaml-providername base64 encoded assertion response) Now this should be set to CognitoCachingCredentialsProvider objectCognitoCachingCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(context identity pool id region)credentialsProvidersetLogins(logins) If SAML assertion contains multiple roles resolve the role by setting the custom rolecredentialsProvidersetCustomRoleArn(arnawsiamaws account idrolecustomRoleName) This should trigger a call to the Amazon Cognito service to get the credentialscredentialsProvidergetCredentials()

iOS如果您使用的是 iOS 开发工具包您可以在 AWSIdentityProviderManager 中提供 SAML 断言如下所示

- (AWSTaskltNSDictionaryltNSStringNSStringgt gt ) logins this is hardcoded for simplicity normally you would asynchronously go to your SAML provider get the assertion and return the logins map using a AWSTaskCompletionSource return [AWSTask taskWithResultarnawsiamaws account idsaml-providernamebase64 encoded assertion response] If SAML assertion contains multiple roles resolve the role by setting the custom role Implementing this is optional if there is only one role- (NSString )customRoleArn return arnawsiamaccountIdrolecustomRoleName

经过开发人员验证的身份 (身份池)除了通过 Web 联合身份验证之外Amazon Cognito 还支持已经过开发人员验证的身份通过Facebook(身份池) (p 204)Google (身份池) (p 211)Login with Amazon (身份池) (p 208) 和Sign in withApple（身份池） (p 217)借助已经过开发人员验证的身份您可以注册并通过自己的现有身份验证流程

224

Amazon Cognito 开发人员指南了解身份验证流程

对用户进行身份验证同时仍然使用 Amazon Cognito 同步用户数据并访问Amazon资源的费用使用已经过开发人员验证的身份涉及最终用户设备身份验证后端和 Amazon Cognito 之间的交互有关更多详细信息请阅读我们的博客

了解身份验证流程有关已经过开发人员验证的身份的身份验证流程以及它与外部提供商身份验证流程的不同之处的信息请参阅身份池 (联合身份) 身份验证流程 (p 180)

定义开发人员提供商名称并将其与身份池关联要使用已经过开发人员验证的身份您需要与开发人员提供商关联的身份池为此请按照以下步骤操作

1 登录Amazon Cognito 控制台2 创建新的身份池并在该过程中在 Authentication Providers 的 Custom 选项卡中定义开发人员提供商名

称3 或者编辑现有身份池并在 Authentication Providers 的 Custom 选项卡中定义开发人员提供商名称

注意一旦设置提供商名称便无法进行更改

有关使用 Amazon Cognito 控制台的更多说明请参阅使用 Amazon Cognito 控制台 (p 3)

实施身份提供商Android要使用已经过开发人员验证的身份请实施自己的身份提供商类该类可扩展AWSAbstractCognitoIdentityProvider您的身份提供商类应返回包含令牌作为属性的响应对象

以下是身份提供商的简单示例

public class DeveloperAuthenticationProvider extends AWSAbstractCognitoDeveloperIdentityProvider

private static final String developerProvider = ltDeveloper_provider_namegt

public DeveloperAuthenticationProvider(String accountId String identityPoolId Regions region) super(accountId identityPoolId region) Initialize any other objects needed here

Return the developer provider name which you choose while setting up the identity pool in the ampCOG Console

Override public String getProviderName() return developerProvider

Use the refresh method to communicate with your backend to get an identityId and token

Override public String refresh()

Override the existing token

225

Amazon Cognito 开发人员指南实施身份提供商

setToken(null)

Get the identityId and token by making a call to your backend (Call to your backend)

Call the update method with updated identityId and token to make sure these are ready to be used from Credentials Provider

update(identityId token) return token

If the app has a valid identityId return it otherwise get a valid identityId from your backend

Override public String getIdentityId()

Load the identityId from the cache identityId = cachedIdentityId

if (identityId == null) Call to your backend else return identityId

要使用此身份提供商您必须将其传递到 CognitoCachingCredentialsProvider示例如下

DeveloperAuthenticationProvider developerProvider = new DeveloperAuthenticationProvider( null IDENTITYPOOLID context RegionsUSEAST1)CognitoCachingCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider( context developerProvider RegionsUSEAST1)

iOS - Objective-C要使用已经过开发人员验证的身份请实施自己的身份提供商类该类可扩展AWSCognitoCredentialsProviderHelper您的身份提供商类应返回包含令牌作为属性的响应对象

implementation DeveloperAuthenticatedIdentityProvider Use the token method to communicate with your backend to get an identityId and token

- (AWSTask ltNSStringgt ) token Write code to call your backend Pass usernamepassword to backend or some sort of token to authenticate user If successful from backend call getOpenIdTokenForDeveloperIdentity with logins map containing yourprovidernameenduserusername Return the identity id and token to client You can use AWSTaskCompletionSource to do this asynchronously

Set the identity id and return the token selfidentityId = responseidentityId return [AWSTask taskWithResultresponsetoken]

226


end

要使用此身份提供商请将其传递到 AWSCognitoCredentialsProvider如下例所示

DeveloperAuthenticatedIdentityProvider devAuth = [[DeveloperAuthenticatedIdentityProvider alloc] initWithRegionTypeAWSRegionYOUR_IDENTITY_POOL_REGION identityPoolIdYOUR_IDENTITY_POOL_ID useEnhancedFlowYES identityProviderManagernil]AWSCognitoCredentialsProvider credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionTypeAWSRegionYOUR_IDENTITY_POOL_REGION identityProviderdevAuth]

如果您想同时支持未经身份验证的身份和已经过开发人员验证的身份请在 logins 实施中覆盖AWSCognitoCredentialsProviderHelper 方法

- (AWSTaskltNSDictionaryltNSString NSString gt gt )logins if(logic to determine if user is unauthenticated) return [AWSTask taskWithResultnil] else return [super logins]

如果您想支持已经过开发人员验证的身份和社交提供商您必须管理在 logins 的AWSCognitoCredentialsProviderHelper 实施中谁是当前的提供商

- (AWSTaskltNSDictionaryltNSString NSString gt gt )logins if(logic to determine if user is unauthenticated) return [AWSTask taskWithResultnil] else if (logic to determine if user is Facebook) return [AWSTask taskWithResult AWSIdentityProviderFacebook [FBSDKAccessToken currentAccessToken] ] else return [super logins]

iOS - Swift要使用已经过开发人员验证的身份请实施自己的身份提供商类该类可扩展AWSCognitoCredentialsProviderHelper您的身份提供商类应返回包含令牌作为属性的响应对象

import AWSCore Use the token method to communicate with your backend to get an identityId and token class DeveloperAuthenticatedIdentityProvider AWSCognitoCredentialsProviderHelper override func token() -gt AWSTaskltNSStringgt Write code to call your backend pass usernamepassword to backend or some sort of token to authenticate user if successful from backend call getOpenIdTokenForDeveloperIdentity with logins map containing yourprovidernameenduserusername return the identity id and token to client You can use AWSTaskCompletionSource to do this asynchronously

227


Set the identity id and return the token selfidentityId = resultFromAboveidentityId return AWSTask(result resultFromAbovetoken)


let devAuth = DeveloperAuthenticatedIdentityProvider(regionType YOUR_IDENTITY_POOL_REGION identityPoolId YOUR_IDENTITY_POOL_ID useEnhancedFlow true identityProviderManagernil)let credentialsProvider = AWSCognitoCredentialsProvider(regionType YOUR_IDENTITY_POOL_REGION identityProviderdevAuth)let configuration = AWSServiceConfiguration(region YOUR_IDENTITY_POOL_REGION credentialsProvidercredentialsProvider)AWSServiceManagerdefault()defaultServiceConfiguration = configuration


override func logins () -gt AWSTaskltNSDictionarygt if(logic to determine if user is unauthenticated) return AWSTask(resultnil) else return superlogins()


override func logins () -gt AWSTaskltNSDictionarygt if(logic to determine if user is unauthenticated) return AWSTask(resultnil) else if (logic to determine if user is Facebook) if let token = AccessTokencurrentauthenticationToken return AWSTask(result [AWSIdentityProviderFacebooktoken]) return AWSTask(errorNSError(domain Facebook Login code -1 userInfo [Facebook No current Facebook access token])) else return superlogins()

JavaScript从后端获取身份 ID 和会话令牌后您要将它们传递到 AWSCognitoIdentityCredentials 提供商示例如下

AWSconfigcredentials = new AWSCognitoIdentityCredentials( IdentityPoolId IDENTITY_POOL_ID IdentityId IDENTITY_ID_RETURNED_FROM_YOUR_PROVIDER Logins cognito-identityamazonawscom TOKEN_RETURNED_FROM_YOUR_PROVIDER )

228


Unity要使用已经过开发人员验证的身份您需要扩展 CognitoAWSCredentials 并覆盖 RefreshIdentity方法以从后端检索用户身份 ID 和令牌并将它们返回下面是可通过ldquoexamplecomrdquo联系假想后端的身份提供商的简单示例

using UnityEngineusing SystemCollectionsusing AmazonCognitoIdentityusing SystemCollectionsGenericusing ThirdPartyJsonLitJsonusing Systemusing SystemThreading

public class DeveloperAuthenticatedCredentials CognitoAWSCredentials const string PROVIDER_NAME = examplecom const string IDENTITY_POOL = IDENTITY_POOL_ID static readonly RegionEndpoint REGION = RegionEndpointUSEast1

private string login = null

public DeveloperAuthenticatedCredentials(string loginAlias) base(IDENTITY_POOL REGION) login = loginAlias

protected override IdentityState RefreshIdentity() IdentityState state = null ManualResetEvent waitLock = new ManualResetEvent(false) MainThreadDispatcherExecuteCoroutineOnMainThread(ContactProvider((s) =gt state = s waitLockSet() )) waitLockWaitOne() return state

IEnumerator ContactProvider(ActionltIdentityStategt callback) WWW www = new WWW(httpexamplecomusername=+login) yield return www string response = wwwtext

JsonData json = JsonMapperToObject(response)

The backend has to send us back an Identity and a OpenID token string identityId = json[IdentityId]ToString() string token = json[Token]ToString()

IdentityState state = new IdentityState(identityId PROVIDER_NAME token false) callback(state)

上面的代码使用线程调度程序对象调用协同程序如果您在项目中无法执行上述操作您可以在场景中使用以下脚本

using Systemusing UnityEngine

229

Amazon Cognito 开发人员指南更新登录映射 (仅限 Android 和 iOS)

using SystemCollectionsusing SystemCollectionsGeneric

public class MainThreadDispatcher MonoBehaviour static QueueltIEnumeratorgt _coroutineQueue = new QueueltIEnumeratorgt() static object _lock = new object()

public void Update() while (_coroutineQueueCount gt 0) StartCoroutine(_coroutineQueueDequeue())

public static void ExecuteCoroutineOnMainThread(IEnumerator coroutine) lock (_lock) _coroutineQueueEnqueue(coroutine)

Xamarin要使用已经过开发人员验证的身份您需要扩展 CognitoAWSCredentials 并覆盖 RefreshIdentity方法以从后端检索用户身份 ID 和令牌并将它们返回下面是可通过ldquoexamplecomrdquo联系假想后端的身份提供商的简单示例

public class DeveloperAuthenticatedCredentials CognitoAWSCredentials const string PROVIDER_NAME = examplecom const string IDENTITY_POOL = IDENTITY_POOL_ID static readonly RegionEndpoint REGION = RegionEndpointUSEast1 private string login = null


protected override async TaskltIdentityStategt RefreshIdentityAsync() IdentityState state = null get your identity and set the state return state

更新登录映射 (仅限 Android 和 iOS)Android使用身份验证系统成功对用户进行身份验证后请使用开发人员提供商名称和开发人员用户标识符 (一个字母数字字符串可在身份验证系统中唯一标识用户) 更新登录映射请确保在更新登录映射后调用 refresh方法因为 identityId 可能已更改

HashMapltString Stringgt loginsMap = new HashMapltString Stringgt()

230

Amazon Cognito 开发人员指南获取令牌 (服务器端)

loginsMapput(developerAuthenticationProvidergetProviderName() developerUserIdentifier)

credentialsProvidersetLogins(loginsMap)credentialsProviderrefresh()

iOS - Objective-C如果没有凭证或者凭证已过期则 iOS 开发工具包仅调用 logins 方法以获取最新登录映射如果您要强制开发工具包获取新的凭证 (例如最终用户从未经身份验证变为经过身份验证并且您想要经过身份验证的用户的凭证)则在 clearCredentials 上调用 credentialsProvider

[credentialsProvider clearCredentials]

iOS - Swift如果没有凭证或者凭证已过期则 iOS 开发工具包仅调用 logins 方法以获取最新登录映射如果您要强制开发工具包获取新的凭证 (例如最终用户从未经身份验证变为经过身份验证并且您想要经过身份验证的用户的凭证)则在 clearCredentials 上调用 credentialsProvider

credentialsProviderclearCredentials()

获取令牌 (服务器端)您可通过调用 GetOpenIdTokenForDeveloperIdentity 获取令牌您必须使用后端调用此 APIAmazon开发人员凭证不得从客户端开发工具包调用它API 接收 Cognito 身份池 ID包含身份提供商名称作为密钥及标识符作为值的登录映射以及可选 Cognito 身份 ID (即您让一个未经过身份验证的用户变成了经过身份验证的用户)标识符可以是用户的用户名电子邮件地址或数值API 通过为用户提供唯一 Cognito ID 及为最终用户提供 OpenID Connect 令牌来响应您的调用

对于由 GetOpenIdTokenForDeveloperIdentity 返回的令牌您需要注意以下事项

bull 您可以指定令牌的自定义过期时间以便缓存如果您不提供任何自定义过期时间则令牌的有效期为 15分钟

bull 您可以设置的最大令牌持续时间为 24 小时bull 请留意延长令牌持续时间所带来的安全方面的问题如果攻击者获取了此令牌则他们可以将令牌换成

Amazon凭证供最终用户在令牌持续时间使用

以下 Java 代码段显示了如何初始化 Amazon Cognito 客户端以及如何检索已经过开发人员验证的身份的令牌

authenticate your end user as appropriate

if authenticated initialize a cognito client with your AWS developer credentialsAmazonCognitoIdentity identityClient = new AmazonCognitoIdentityClient( new BasicAWSCredentials(access_key_id secret_access_key))

create a new request to retrieve the token for your end userGetOpenIdTokenForDeveloperIdentityRequest request = new GetOpenIdTokenForDeveloperIdentityRequest()requestsetIdentityPoolId(YOUR_COGNITO_IDENTITY_POOL_ID)

requestsetIdentityId(YOUR_COGNITO_IDENTITY_ID) optional set this if your client has an

231

Amazon Cognito 开发人员指南连接到现有社交身份

identity ID that you want to link to this developer account

set up your logins map with the username of your end userHashMapltStringStringgt logins = new HashMapltgt()loginsput(YOUR_IDENTITY_PROVIDER_NAMEYOUR_END_USER_IDENTIFIER)requestsetLogins(logins)

optionally set token duration (in seconds)requestsetTokenDuration(60 15l)GetOpenIdTokenForDeveloperIdentityResult response = identityClientgetOpenIdTokenForDeveloperIdentity(request)

obtain identity id and token to return to your clientString identityId = responsegetIdentityId()String token = responsegetToken()

code to return identity id and token to client

按照上述步骤操作您应该能够将已经过开发人员验证的身份集成到应用程序中如有任何问题或疑问请随时在我们的论坛上发帖

连接到现有社交身份当您使用已经过开发人员验证的身份时您必须从后端链接所有提供商要将自定义身份连接到用户的社交身份（Login with AmazonSign in with AppleFacebook 或 Google）请在调用GetOpenIdTokenForDeveloperIdentity 时将身份提供商令牌添加到登录映射要实现上述目标当您从客户端开发工具包调用后端来对最终用户进行身份验证时您还需要传递最终用户的社交提供商令牌

例如如果您想将自定义身份链接到 Facebook在调用 GetOpenIdTokenForDeveloperIdentity 时除了身份提供商标识符之外您还需要将 Facebook 令牌添加到登录映射

loginsput(YOUR_IDENTITY_PROVIDER_NAMEYOUR_END_USER_IDENTIFIER)loginsput(graphfacebookcomEND_USERS_FACEBOOK_ACCESSTOKEN)

支持在提供商之间转换Android您的应用程序可能需要支持未经身份验证的身份或使用公有提供商（Login with AmazonSign in withAppleFacebook 或 Google）的经过身份验证的身份以及已经过开发人员验证的身份已经过开发人员验证的身份与其他身份 (未经身份验证的身份和使用公共提供商的经过身份验证的身份) 的主要区别在于identityId 和令牌的获取方式对于其他身份移动应用程序将直接与 Amazon Cognito 进行交互而不是与身份验证系统联系因此移动应用程序应该能够支持两个不同的流程具体取决于应用程序用户的选择对此您必须对自定义身份提供商做出一些更改

如果映射不为空且包含带开发人员提供商名称的密钥则 refresh 方法应该检查登录映射然后您应该调用后端否则请调用 getIdentityId 方法并返回 null

public String refresh()

setToken(null)

If the logins map is not empty make a call to your backend to get the token and identityId if (getProviderName() = null ampamp

232

Amazon Cognito 开发人员指南支持在提供商之间转换

thisloginsMapisEmpty() ampamp thisloginsMapcontainsKey(getProviderName()))

This is where you would call your backend

now set the returned identity id and token in the provider update(identityId token) return token

else Call getIdentityId method and return null thisgetIdentityId() return null

同样getIdentityId 方法也有两个流程具体取决于登录映射的内容

public String getIdentityId()


if (identityId == null)

If the logins map is not empty make a call to your backend to get the token and identityId

if (getProviderName() = null ampamp thisloginsMapisEmpty() ampamp thisloginsMapcontainsKey(getProviderName()))



else Otherwise call ampCOG using getIdentityId of super class return supergetIdentityId()

else return identityId

iOS - Objective-C您的应用程序可能需要支持未经身份验证的身份或使用公有提供商（Login with AmazonSign in withAppleFacebook 或 Google）的经过身份验证的身份以及已经过开发人员验证的身份为此请覆盖AWSCognitoCredentialsProviderHelper logins 方法以便根据当前的身份提供商返回正确的登录映射此示例说明如何能够在未经身份验证的身份Facebook 和已经过开发人员验证的身份之间切换

- (AWSTaskltNSDictionaryltNSString NSString gt gt )logins if(logic to determine if user is unauthenticated) return [AWSTask taskWithResultnil]

233


else if (logic to determine if user is Facebook) return [AWSTask taskWithResult AWSIdentityProviderFacebook [FBSDKAccessToken currentAccessToken] ] else return [super logins]

当您从未经身份验证转换为经过身份验证时您应该调用 [credentialsProviderclearCredentials] 以强制开发工具包获取经过身份验证的新凭证当您在两个经过身份验证的提供商之间切换并且不想将这两个提供商链接起来时 (即您没有在登录词典中为多个提供商提供令牌)您应该调用 [credentialsProvider clearKeychain]上述操作将清除凭证和身份并强制开发工具包获取新的

iOS - Swift您的应用程序可能需要支持未经身份验证的身份或使用公有提供商（Login with AmazonSign in withAppleFacebook 或 Google）的经过身份验证的身份以及已经过开发人员验证的身份为此请覆盖AWSCognitoCredentialsProviderHelper logins 方法以便根据当前的身份提供商返回正确的登录映射此示例说明如何能够在未经身份验证的身份Facebook 和已经过开发人员验证的身份之间切换


当您从未经身份验证转换为经过身份验证时您应该调用credentialsProviderclearCredentials() 以强制开发工具包获取经过身份验证的新凭证当您在两个经过身份验证的提供商之间切换并且不想将这两个提供商链接起来时 (即您没有在登录词典中为多个提供商提供令牌)您应该调用 credentialsProviderclearKeychain()上述操作将清除凭证和身份并强制开发工具包获取新的

Unity您的应用程序可能需要支持未经身份验证的身份或使用公有提供商（Login with AmazonSign in withAppleFacebook 或 Google）的经过身份验证的身份以及已经过开发人员验证的身份已经过开发人员验证的身份与其他身份 (未经身份验证的身份和使用公共提供商的经过身份验证的身份) 的主要区别在于identityId 和令牌的获取方式对于其他身份移动应用程序将直接与 Amazon Cognito 进行交互而不是与身份验证系统联系因此移动应用程序应该能够支持两个不同的流程具体取决于应用程序用户的选择对此您必须对自定义身份提供商做出一些更改

在 Unity 中我们建议您从 AmazonCognitoEnhancedIdentityProvide 而不是AbstractCognitoIdentityProvider 扩展身份提供商并调用父 RefreshAsync 方法而不是您自己的方法以防用户未通过您自己的后端进行身份验证如果用户已经过身份验证则您可以使用之前介绍的相同的流程

Xamarin您的应用程序可能需要支持未经身份验证的身份或使用公有提供商（Login with AmazonSign in withAppleFacebook 或 Google）的经过身份验证的身份以及已经过开发人员验证的身份已经过开发人

234

Amazon Cognito 开发人员指南切换身份

员验证的身份与其他身份 (未经身份验证的身份和使用公共提供商的经过身份验证的身份) 的主要区别在于identityId 和令牌的获取方式对于其他身份移动应用程序将直接与 Amazon Cognito 进行交互而不是与身份验证系统联系因此移动应用程序应该能够支持两个不同的流程具体取决于应用程序用户的选择对此您必须对自定义身份提供商做出一些更改

将未经身份验证的用户切换为经过身份验证的用户（身份池）

Amazon Cognito 身份池同时支持经过身份验证和未经身份验证的用户未经身份验证的用户可以访问Amazon资源即使未通过任何身份提供商 (IIdPs) 登录这些资源也有效此级别的访问可用于向尚未登录的用户显示内容即使每个未经身份验证的用户尚未单独登录和经过身份验证这些用户在身份池中也都具有唯一的身份

本节介绍了用户如何选择从使用未经身份验证的身份登录切换为使用经过身份验证的身份登录

Android用户能够以未经身份验证的来宾的身份登录您的应用程序最终他们可能决定使用某个受支持的 IdP 登录Amazon Cognito 将确保旧身份保留与新身份相同的唯一标识符并确保配置文件数据自动合并

应用程序会通过 IdentityChangedListener 界面收到配置文件合并的消息在界面中实施identityChanged 方法以接收这些消息

overridepublic void identityChanged(String oldIdentityId String newIdentityId) handle the change

iOS - Objective-C用户能够以未经身份验证的来宾的身份登录您的应用程序最终他们可能决定使用某个受支持的 IdP 登录Amazon Cognito 将确保旧身份保留与新身份相同的唯一标识符并确保配置文件数据自动合并

NSNotificationCenter 通知应用程序配置文件合并的消息

[[NSNotificationCenter defaultCenter] addObserverself selectorselector(identityIdDidChange) nameAWSCognitoIdentityIdChangedNotification objectnil]

-(void)identityDidChange(NSNotification)notification NSDictionary userInfo = notificationuserInfo NSLog(identity changed from to [userInfo objectForKeyAWSCognitoNotificationPreviousId] [userInfo objectForKeyAWSCognitoNotificationNewId])

iOS - Swift用户能够以未经身份验证的来宾的身份登录您的应用程序最终他们可能决定使用某个受支持的 IdP 登录Amazon Cognito 将确保旧身份保留与新身份相同的唯一标识符并确保配置文件数据自动合并


235


[NSNotificationCenterdefaultCenter()addObserver(observer self selectoridentityDidChange nameAWSCognitoIdentityIdChangedNotification objectnil)

func identityDidChange(notification NSNotification) if let userInfo = notificationuserInfo as [String AnyObject] print(identity changed from (userInfo[AWSCognitoNotificationPreviousId]) to (userInfo[AWSCognitoNotificationNewId]))

JavaScript最初未经身份验证的用户用户最初通常具有未经身份验证的角色对于此角色您可以设置配置对象的凭证属性而不设置登录属性在这种情况下您的默认配置可能如下所示

set the default config objectvar creds = new AWSCognitoIdentityCredentials( IdentityPoolId us-east-11699ebc0-7900-4099-b910-2df94f52a030)AWSconfigcredentials = creds

切换为经过身份验证的用户当未经身份验证的用户登录 IdP 并且您拥有令牌时您可以通过调用可更新凭证对象和添加登录令牌的自定义函数来将用户从未经身份验证的用户切换为经过身份验证的用户

Called when an identity provider has a token for a logged in userfunction userLoggedIn(providerName token) credsparamsLogins = credsparamsLogins || credsparamsLogins[providerName] = token

Expire credentials to refresh them on the next request credsexpired = true

您还可以创建 CognitoIdentityCredentials 对象在这种情况下必须重置任何现有服务对象的凭证属性以反映更新的凭证配置信息请参阅使用全局配置对象

有关CognitoIdentityCredentials对象请参阅Amazon 认知身份凭证中的Amazon SDK forJavaScriptAPI 参考

Unity用户能够以未经身份验证的来宾的身份登录您的应用程序最终他们可能决定使用某个受支持的 IdP 登录Amazon Cognito 将确保旧身份保留与新身份相同的唯一标识符并确保配置文件数据自动合并

您可以订阅 IdentityChangedEvent以接收配置文件合并的通知

credentialsProviderIdentityChangedEvent += delegate(object sender CognitoAWSCredentialsIdentityChangedArgs e)

236


handle the change Debuglog(Identity changed from + eOldIdentityId + to + eNewIdentityId)

Xamarin用户能够以未经身份验证的来宾的身份登录您的应用程序最终他们可能决定使用某个受支持的 IdP 登录Amazon Cognito 将确保旧身份保留与新身份相同的唯一标识符并确保配置文件数据自动合并

credentialsProviderIdentityChangedEvent += delegate(object sender CognitoAWSCredentialsIdentityChangedArgs e) handle the change ConsoleWriteLine(Identity changed from + eOldIdentityId + to + eNewIdentityId)

237

Amazon Cognito 开发人员指南Amazon Cognito Sync 入门

Amazon Cognito 同步

如果您是 Amazon Cognito Sync 的新用户请使用Amazon AppSync像 Amazon Cognito Sync一样Amazon AppSync是一种在设备之间同步应用程序数据的服务它允许用户数据（如应用首选项或游戏状态）进行同步它还允许多个用户实时同步和协作处理共享的数据从而扩展了这些功能

Amazon Cognito Sync 是Amazon服务和客户端库用于跨设备同步应用程序相关用户数据您可以用它来跨移动设备和 Web 同步用户配置文件数据无需使用自己的后端客户端库在本地缓存数据因此您的应用程序可以读取和写入数据无论设备是否处于连接状态都是如此设备处于在线状态时您可以同步数据如果您设置推送同步则在更新可用时会立即通知其他设备

有关 Amazon Cognito 身份区域可用性的信息请参阅Amazon服务区域可用性

要了解有关 Amazon Cognito Sync 的更多信息请参阅以下主题

主题bull Amazon Cognito Sync 入门 (p 238)bull 同步数据 (p 239)bull 处理回调 (p 245)bull 推送同步 (p 257)bull Amazon Cognito 流 (p 262)bull Amazon Cognito 事件 (p 264)

Amazon Cognito Sync 入门如果您是 Amazon Cognito Sync 的新用户请使用Amazon AppSync像 Amazon Cognito Sync一样Amazon AppSync是一种在设备之间同步应用程序数据的服务它允许用户数据（如应用首选项或游戏状态）进行同步它还允许多个用户实时同步和协作处理共享的数据从而扩展了这些功能

Amazon Cognito Sync 是Amazon服务和客户端库用于跨设备同步应用程序相关用户数据您可以使用它来跨移动设备和 Web 应用程序同步用户配置文件数据客户端库在本地缓存数据因此您的应用程序可以读取和写入数据无论设备是否处于连接状态都是如此设备处于在线状态时您可以同步数据如果您设置推送同步则在更新可用时会立即通知其他设备

注册 Amazon 账户要使用 Amazon Cognito 同步功能您需要Amazonaccount 如果您还没有账户请按照以下步骤注册

如何注册 Amazon 账户



238

Amazon Cognito 开发人员指南在 Amazon Cognito 中设置身份池

在 Amazon Cognito 中设置身份池Amazon Cognito 同步需要一个 Amazon Cognito 身份池来提供用户身份因此您需要先设置身份池然后才能使用 Amazon Cognito Sync按照 Amazon Cognito 身份池入门 (联合身份) (p 174) 指南创建身份池并安装开发工具包

存储和同步数据设置身份池并安装开发工具包后您就可以开始在设备之间存储和同步数据了参阅同步数据 (p 239) 了解更多信息

同步数据如果您是 Amazon Cognito Sync 的新用户请使用Amazon AppSync像 Amazon Cognito Sync一样Amazon AppSync是一种在设备之间同步应用程序数据的服务它允许用户数据（如应用首选项或游戏状态）进行同步它还允许多个用户实时同步和协作处理共享的数据从而扩展了这些功能

借助 Amazon Cognito您可将最终用户数据保存在包含键值对的数据集中此数据与 Amazon Cognito 身份相关联因此可以跨登录和设备进行访问要在 Amazon Cognito 服务和最终用户设备之间同步此数据请调用 synchronize 方法每个数据集的最大大小为 1MB您最多可以将 20 个数据集与一个身份关联

Amazon Cognito Sync 客户端会为身份数据创建一个本地缓存您的应用程序在读取和写入键时将与此本地缓存通信这可保证您在设备上所做的所有更改都能在设备上立即可用即使您处于离线状态也是如此调用 synchronize 方法后服务的更改将拉取到设备上并且所有本地更改都会推送到该服务此时这些更改可供其他设备同步时使用

正在初始化 Amazon Cognito Sync

要初始化 Amazon Cognito Sync 客户端您首先需要创建凭证提供程序凭证提供程序获取临时Amazon凭证以使您的应用程序能够访问Amazon资源的费用您还需要导入所需的标头文件使用以下步骤初始化Amazon Cognito Sync 客户端

Android1 按照获取凭证 (p 196)中的说明创建凭证提供程序2 导入 Amazon Cognito 包import comamazonawsmobileconnectorscognito

3 初始化 Amazon Cognito Sync传入 Android 应用程序上下文身份池 IDAmazon区域以及已初始化的 Amazon Cognito 凭证提供商

CognitoSyncManager client = new CognitoSyncManager( getApplicationContext() RegionsYOUR_REGION credentialsProvider)

iOS - Objective-C1 按照获取凭证 (p 196)中的说明创建凭证提供程序2 导入 AWSCore 和 Cognito并初始化 AWSCognito

239

Amazon Cognito 开发人员指南了解数据集

import ltAWSiOSSDKv2AWSCorehgtimport ltAWSCognitoSyncCognitohgt

AWSCognito syncClient = [AWSCognito defaultCognito]

3 如果您使用的是 CocoaPods请将ltAWSiOSSDKv2AWSCorehgt替换为AWSCoreh然后遵循Amazon Cognito 导入的同一语法

iOS - Swift1 按照获取凭证 (p 196)中的说明创建凭证提供程序2 导入并初始化 AWSCognito

import AWSCognitolet syncClient = AWSCognitodefault()

JavaScript1 下载Amazon Cognito Sync 管理 JavaScript2 在您的项目中添加 Sync Manager 库3 按照获取凭证 (p 196)中的说明创建凭证提供程序4 初始化 Sync Manager

var syncManager = new AWSCognitoSyncManager()

Unity1 您首先需要按照CognitoAWSCredentials中的说明创建获取凭证 (p 196) 的实例2 创建 CognitoSyncManager 的实例将 CognitoAwsCredentials 对象和

AmazonCognitoSyncConfig 至少传递到区域集

AmazonCognitoSyncConfig clientConfig = new AmazonCognitoSyncConfig RegionEndpoint = REGION CognitoSyncManager syncManager = new CognitoSyncManager(credentials clientConfig)

Xamarin1 您首先需要按照CognitoAWSCredentials中的说明创建获取凭证 (p 196) 的实例2 创建 CognitoSyncManager 的实例将 CognitoAwsCredentials 对象和



了解数据集

240


借助 Amazon Cognito最终用户配置文件数据可以组织到数据集中每个数据集可以包含高达 1MB 的键值对形式的数据数据集是可以执行同步操作的最精细的实体在调用 synchronize 方法之前在数据集上执行的读取和写入操作只会对本地存储产生影响数据集采用唯一字符串标识您可以创建新数据集或打开现有数据集如下所示

Android

Dataset dataset = clientopenOrCreateDataset(datasetname)

要删除数据集首先要调用该方法以将其从本地存储中删除然后调用synchronize方法从 AmazonCognito 中删除数据集

datasetdelete()datasetsynchronize(syncCallback)

iOS - Objective-C

AWSCognitoDataset dataset = [syncClient openOrCreateDatasetmyDataSet]


[dataset clear][dataset synchronize]

iOS - Swift

let dataset = syncClientopenOrCreateDataset(myDataSet)


datasetclear()datasetsynchronize()

JavaScript

syncManageropenOrCreateDataset(myDatasetName function(err dataset) )

Unity

string myValue = datasetGet(myKey)datasetPut(myKey newValue)

您可以使用 Remove 从数据集中删除键

datasetRemove(myKey)

241

Amazon Cognito 开发人员指南在数据集中读取并写入数据

XamarinDataset dataset = syncManagerOpenOrCreateDataset(myDatasetName)


datasetDelete()datasetSynchronizeAsync()

在数据集中读取并写入数据Amazon Cognito 数据集用作字典值可以通过键进行访问数据集的键和值可以读取添加或修改就像数据集是字典一样下面是一个示例

请注意在您调用 synchronize 方法之前写入数据集的值仅对本地缓存的数据副本有影响

AndroidString value = datasetget(myKey)datasetput(myKey my value)

iOS - Objective-C[dataset setStringmy value forKeymyKey]NSString value = [dataset stringForKeymyKey]

iOS - SwiftdatasetsetString(my value forKeymyKey)let value = datasetstringForKey(myKey)

JavaScript

datasetget(myKey function(err value) consolelog(myRecord + value))

datasetput(newKey newValue function(err record) consolelog(record))

datasetremove(oldKey function(err record) consolelog(success))

Unitystring myValue = datasetGet(myKey)datasetPut(myKey newValue)

242

Amazon Cognito 开发人员指南使用同步存储空间同步本地数据

Xamarin

obtain a valuestring myValue = datasetGet(myKey)

Create a record in a dataset and synchronize with the serverdatasetOnSyncSuccess += SyncSuccessCallbackdatasetPut(myKey myValue)datasetSynchronizeAsync()

void SyncSuccessCallback(object sender SyncSuccessEventArgs e) Your handler code here

Android您可以使用 remove 方法从数据集中删除键

datasetremove(myKey)

iOS - Objective-C您可以使用 removeObjectForKey 从数据集中删除键

[dataset removeObjectForKeymyKey]

iOS - Swift您可以使用 removeObjectForKey 从数据集中删除键

datasetremoveObjectForKey(myKey)

Unity您可以使用 Remove 从数据集中删除键


Xamarin您可以使用 Remove 从数据集中删除键


使用同步存储空间同步本地数据

Android这些区域有synchronize方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较从 Amazon Cognito Sync 存储空间中拉取远程更改如果出现任何冲突则调用冲突解决方法设备上的更新值将推送到该服务要同步数据集请调用其 synchronize 方法

243


datasetsynchronize(syncCallback)

synchronize 方法收到 SyncCallback 接口的实现如下所述

synchronizeOnConnectivity() 方法尝试在连接可用时进行同步如果连接立即可用则synchronizeOnConnectivity() 的行为类似于 synchronize()否则它会监控连接更改并在连接可用时立即执行同步如果多次调用 synchronizeOnConnectivity()则只会保持最近一次同步请求并只会触发最近一次回调如果数据集或回调收集到垃圾则此方法不会执行同步且不会触发回调

要了解有关数据集同步和不同回调的更多信息请参阅处理回调 (p 245)

iOS - Objective-C这些区域有synchronize方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较从 Amazon Cognito Sync 存储空间中拉取远程更改如果出现任何冲突则调用冲突解决方法设备上的更新值将推送到该服务要同步数据集请调用其 synchronize 方法

synchronize 方法是异步的它会返回 AWSTask 对象以处理响应

[[dataset synchronize] continueWithBlockîd(AWSTask task) if (taskisCancelled) Task cancelled else if (taskerror) Error while executing task else Task succeeded The data was saved in the sync store return nil]

synchronizeOnConnectivity 方法尝试在设备具备连接时进行同步首先synchronizeOnConnectivity 将检查连接状态如果设备处于在线状态则立即调用synchronize并返回与此次尝试关联的 AWSTask 对象

如果设备处于离线状态synchronizeOnConnectivity 1) 计划在设备下次变为在线状态时进行同步2) 返回一个无结果的 AWSTask计划的同步仅在该数据集对象的生命周期内有效如果在连接恢复之前退出应用程序则数据不会进行同步如果您希望在计划同步期间发生事件时收到通知则必须添加在AWSCognito 中找到的通知的观察者


iOS - Swift这些区域有synchronize方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较从 Amazon Cognito Sync 存储空间中拉取远程更改如果出现任何冲突则调用冲突解决方法设备上的更新值将推送到该服务要同步数据集请调用其 synchronize 方法


datasetsynchronize()continueWith(block (task) -gt AnyObject in

if taskisCancelled Task cancelled else if taskerror = nil Error while executing task else Task succeeded The data was saved in the sync store

244

Amazon Cognito 开发人员指南处理回调

return task)


如果设备处于离线状态synchronizeOnConnectivity 1) 计划在设备下次变为在线状态时进行同步2) 返回一个无结果的 AWSTask 对象计划的同步仅在该数据集对象的生命周期内有效如果在连接恢复之前退出应用程序则数据不会进行同步如果您希望在计划同步期间发生事件时收到通知则必须添加在AWSCognito 中找到的通知的观察者


JavaScript这些区域有synchronize方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较从 Amazon Cognito Sync 存储空间中拉取远程更改如果出现任何冲突则调用冲突解决方法设备上的更新值将推送到该服务要同步数据集请调用其 synchronize 方法

datasetsynchronize()


Unitysynchronize 方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较从Amazon Cognito Sync 存储空间中拉取远程更改如果出现任何冲突则调用冲突解决方法设备上的更新值将推送到该服务要同步数据集请调用其 synchronize 方法

datasetSynchronize()

同步将以异步方式运行最终会调用您可以在数据集中指定的几个回调之一


Xamarin这些区域有synchronize方法将本地缓存的数据与存储在 Amazon Cognito Sync 存储空间中的数据进行比较从 Amazon Cognito Sync 存储空间中拉取远程更改如果出现任何冲突则调用冲突解决方法设备上的更新值将推送到该服务要同步数据集请调用其 synchronize 方法

datasetSynchronizeAsync()


处理回调如果您是 Amazon Cognito Sync 的新用户请使用Amazon AppSync像 Amazon Cognito Sync一样Amazon AppSync是一种在设备之间同步应用程序数据的服务

245


它允许用户数据（如应用首选项或游戏状态）进行同步它允许多个用户实时同步和协作处理共享的数据从而扩展了这些功能

本部分介绍如何处理回调

AndroidSyncCallback 接口

通过实施 SyncCallback 接口您可以在应用程序上接收有关数据集同步的通知然后您的应用程序可以在删除本地数据合并未经身份验证的和经过身份验证的配置文件以及解决同步冲突方面制定有效决策您应该实施接口所需的以下方法

bull onSuccess()

bull onFailure()

bull onConflict()

bull onDatasetDeleted()

bull onDatasetsMerged()

请注意如果您不想指定所有回调也可以使用类 DefaultSyncCallback它会为所有回调提供默认的空实施

onSuccess

从同步存储空间成功下载数据集后将触发 onSuccess() 回调

Overridepublic void onSuccess(Dataset dataset ListltRecordgt newRecords)

onFailure

如果同步过程中出现异常则会调用 onFailure()

Overridepublic void onFailure(DataStorageException dse)

onConflict

如果在本地存储和同步存储空间修改同一键则会产生冲突onConflict() 方法可处理冲突解决方法如果您没有实施此方法则 Amazon Cognito Sync 客户端将默认为使用最近的更改

Overridepublic boolean onConflict(Dataset dataset final ListltSyncConflictgt conflicts) ListltRecordgt resolvedRecords = new ArrayListltRecordgt() for (SyncConflict conflict conflicts) resolved by taking remote records resolvedRecordsadd(conflictresolveWithRemoteRecord())

alternately take the local records resolvedRecordsadd(conflictresolveWithLocalRecord())

or customer logic say concatenate strings String newValue = conflictgetRemoteRecord()getValue() + conflictgetLocalRecord()getValue() resolvedRecordsadd(conflictresolveWithValue(newValue)

246


datasetresolve(resolvedRecords)

return true so that synchronize() is retried after conflicts are resolved return true

onDatasetDeleted

删除数据集后Amazon Cognito 客户端将使用SyncCallback接口确认是否还应删除本地缓存的数据集副本实施 onDatasetDeleted() 方法以告知客户端开发工具包该如何处理本地数据

Overridepublic boolean onDatasetDeleted(Dataset dataset String datasetName) return true to delete the local copy of the dataset return true

onDatasetMerged

当两个以前未连接的身份链接在一起后它们的所有数据集都将合并可通过 onDatasetsMerged() 方法向应用程序发送有关合并的通知

Overridepublic boolean onDatasetsMerged(Dataset dataset ListltStringgt datasetNames) return false to handle Dataset merge outside the synchronization callback return false

iOS - Objective-C同步通知

Amazon Cognito 客户端将发出大量NSNotification事件您可以进行注册以通过标准NSNotificationCenter 监控这些通知

[NSNotificationCenter defaultCenter] addObserverself selectorselector(myNotificationHandler) nameNOTIFICATION_TYPE objectnil]

Amazon Cognito 支持五种通知类型如下所列

AWSCognitoDidStartSynchronizeNotification

同步操作开始时调用userInfo 包含主数据集即正在进行同步的数据集的名称

AWSCognitoDidEndSynchronizeNotification

在同步操作完成 (无论是否成功) 时调用userInfo 包含主数据集即正在进行同步的数据集的名称

AWSCognitoDidFailToSynchronizeNotification

同步操作失败时调用userInfo 包含主数据集 (即正在进行同步的数据集的名称) 和关键错误 (包含导致失败的错误)

AWSCognitoDidChangeRemoteValueNotification

247


本地更改成功推送到 Amazon Cognito 时调用userInfo 包含主数据集 (即正在进行同步的数据集的名称)和关键键 (包含已推送的记录键的 NSArray)

AWSCognitoDidChangeLocalValueFromRemoteNotification

本地值由于同步操作而更改时调用userInfo 包含主数据集 (即正在进行同步的数据集的名称) 和关键键(包含已更改的记录键的 NSArray)

冲突解决方法处理程序

在同步操作过程中如果在本地存储和同步存储空间修改同一键则会产生冲突如果您尚未设置冲突解决方法处理程序则 Amazon Cognito 将默认为选择最近的更新

通过实施和分配 AWSCognitoRecordConflictHandler您可以更改默认的冲突解决方法AWSCognitoConflict 输入参数冲突包含本地缓存数据和同步存储空间中冲突记录的 AWSCognitoRecord对象使用 AWSCognitoConflict您可以通过 [conflict resolveWithLocalRecord] 解决与本地记录的冲突通过 [conflict resolveWithRemoteRecord] 解决与远程记录的冲突或通过 [conflict resolveWithValuevalue]解决与全新值的冲突此方法返回无将阻止同步继续进行并且下一次同步过程开始时会再次出现冲突

您可以在客户端层面设置冲突解决方法处理程序

clientconflictHandler = ÂWSCognitoResolvedConflict (NSString datasetName AWSCognitoConflict conflict) always choose local changes return [conflict resolveWithLocalRecord]

或在数据集层面

datasetconflictHandler = ÂWSCognitoResolvedConflict (NSString datasetName AWSCognitoConflict conflict) override and always choose remote changes return [conflict resolveWithRemoteRecord]

数据集删除处理程序

删除数据集后Amazon Cognito 客户端将使用AWSCognitoDatasetDeletedHandler确认是否还应删除本地缓存的数据集副本如果未实施 AWSCognitoDatasetDeletedHandler则将自动清除本地数据如果您希望在清除前保留本地数据的副本或保留本地数据则实施AWSCognitoDatasetDeletedHandler

您可以在客户端层面设置数据集删除处理程序

clientdatasetDeletedHandler = ^BOOL (NSString datasetName) make a backup of the data if you choose delete the local data (default behavior) return YES


datasetdatasetDeletedHandler = ^BOOL (NSString datasetName) override default and keep the local data return NO

数据集合并处理程序

248

Amazon Cognito 开发人员指南iOS - Swift

当两个以前未连接的身份链接在一起后它们的所有数据集都将合并可通过 DatasetMergeHandler 向应用程序发送有关合并的通知该处理程序将收到根数据集名称以及标记为根数据集合并的数据集名称数组

如果未实施 DatasetMergeHandler这些数据集将被忽略但将继续占用最多 20 个身份总数据集中的空间

您可以在客户端层面设置数据集合并处理程序

clientdatasetMergedHandler = ^(NSString datasetName NSArray datasets) Blindly delete the datasets for (NSString name in datasets) AWSCognitoDataset merged = [[AWSCognito defaultCognito] openOrCreateDatasetname] [merged clear] [merged synchronize]


datasetdatasetMergedHandler = ^(NSString datasetName NSArray datasets) Blindly delete the datasets for (NSString name in datasets) AWSCognitoDataset merged = [[AWSCognito defaultCognito] openOrCreateDatasetname] do something with the data if it differs from existing dataset now delete it [merged clear] [merged synchronize]

iOS - Swift同步通知


NSNotificationCenterdefaultCenter()addObserver(observer self selector myNotificationHandler nameNOTIFICATION_TYPE objectnil)








249








通过实施和分配 AWSCognitoRecordConflictHandler您可以更改默认的冲突解决方法AWSCognitoConflict 输入参数冲突包含本地缓存数据和同步存储空间中冲突记录的AWSCognitoRecord 对象使用 AWSCognitoConflict您可以通过 [conflict resolveWithLocalRecord]解决与本地记录的冲突通过 [conflict resolveWithRemoteRecord] 解决与远程记录的冲突或通过 [conflictresolveWithValuevalue] 解决与全新值的冲突此方法返回无将阻止同步继续进行并且下一次同步过程开始时会再次出现冲突


clientconflictHandler = (datasetName String conflict AWSCognitoConflict) -gt AWSCognitoResolvedConflict in return conflictresolveWithLocalRecord()


datasetconflictHandler = (datasetName String conflict AWSCognitoConflict) -gt AWSCognitoResolvedConflict in return conflictresolveWithLocalRecord()




clientdatasetDeletedHandler = (datasetName String) -gt Bool in make a backup of the data if you choose delete the local data (default behaviour) return true


datasetdatasetDeletedHandler = (datasetName String) -gt Bool in make a backup of the data if you choose

250


delete the local data (default behaviour) return true





clientdatasetMergedHandler = (datasetName String datasets [AnyObject]) -gt Void in for nameObject in datasets if let name = nameObject as String let merged = AWSCognitodefaultCognito()openOrCreateDataset(name) mergedclear() mergedsynchronize()


datasetdatasetMergedHandler = (datasetName String datasets [AnyObject]) -gt Void in for nameObject in datasets if let name = nameObject as String let merged = AWSCognitodefaultCognito()openOrCreateDataset(name) do something with the data if it differs from existing dataset now delete it mergedclear() mergedsynchronize()

JavaScript同步回调

在数据集上执行 synchronize() 时您可以有选择性地指定用于处理以下各种状态的回调

datasetsynchronize(

onSuccess function(dataset newRecords)

onFailure function(err)

onConflict function(dataset conflicts callback)

251


onDatasetDeleted function(dataset datasetName callback)

onDatasetMerged function(dataset datasetNames callback)

)

onSuccess()

从同步存储空间成功更新数据集后将触发 onSuccess() 回调如果您未定义回调则同步成功完成后将保持静默状态

onSuccess function(dataset newRecords) consolelog(Successfully synchronized + newRecordslength + new records)

onFailure()

如果同步过程中出现异常则会调用 onFailure()如果您未定义回调则同步失败后将无提示

onFailure function(err) consolelog(Synchronization failed) consolelog(err)

onConflict()

如果在本地存储和同步存储空间修改同一键则会产生冲突onConflict() 方法可处理冲突解决方法如果您未实施此方法则在发生冲突时同步将中止


var resolved = []

for (var i=0 iltconflictslength i++)

Take remote version resolvedpush(conflicts[i]resolveWithRemoteRecord())

Or take local version resolvedpush(conflicts[i]resolveWithLocalRecord())

Or use custom logic var newValue = conflicts[i]getRemoteRecord()getValue() + conflicts[i]getLocalRecord()getValue() resolvedpush(conflicts[i]resovleWithValue(newValue)

datasetresolve(resolved function() return callback(true) )

Or callback false to stop the synchronization process return callback(false)

252


onDatasetDeleted()

删除数据集后Amazon Cognito 客户端将使用onDatasetDeleted()回调决定是否还应删除本地缓存的数据集副本默认情况下不会删除该数据集


Return true to delete the local copy of the dataset Return false to handle deleted datasets outside the synchronization callback

return callback(true)

onDatasetMerged()

当两个以前未连接的身份链接在一起后它们的所有数据集都将合并可通过 onDatasetsMerged() 回调向应用程序发送有关合并的通知


Return true to continue the synchronization process Return false to handle dataset merges outside the synchronization callback

return callback(false)

Unity打开或创建数据集之后您可以为其设置不同的回调以在使用 Synchronize 方法时触发以下就是将回调注册到数据集的方法

datasetOnSyncSuccess += thisHandleSyncSuccessdatasetOnSyncFailure += thisHandleSyncFailuredatasetOnSyncConflict = thisHandleSyncConflictdatasetOnDatasetMerged = thisHandleDatasetMergeddatasetOnDatasetDeleted = thisHandleDatasetDeleted

请注意SyncSuccess 和 SyncFailure 使用 += 而不是 =因此您可以向其订阅多个回调

OnSyncSuccess

从云成功更新数据集后将触发 OnSyncSuccess 回调如果您未定义回调则同步成功完成后将保持静默状态

private void HandleSyncSuccess(object sender SyncSuccessEvent e) Continue with your game flow display the loaded data etc

OnSyncFailure

如果同步过程中出现异常则会调用 OnSyncFailure如果您未定义回调则同步失败后将无提示

253


private void HandleSyncFailure(object sender SyncFailureEvent e) Dataset dataset = sender as Dataset if (datasetMetadata = null) DebugLog(Sync failed for dataset + datasetMetadataDatasetName) else DebugLog(Sync failed) Handle the error DebugLogException(eException)

OnSyncConflict

如果在本地存储和同步存储空间修改同一键则会产生冲突OnSyncConflict 回调可处理冲突解决方法如果您未实施此方法则在发生冲突时同步将中止

private bool HandleSyncConflict(Dataset dataset List lt SyncConflict gt conflicts) if (datasetMetadata = null) DebugLogWarning(Sync conflict + datasetMetadataDatasetName) else DebugLogWarning(Sync conflict) List lt AmazonCognitoSyncSyncManagerRecord gt resolvedRecords = new List lt AmazonCognitoSyncSyncManagerRecord gt () foreach(SyncConflict conflictRecord in conflicts) SyncManager provides the following default conflict resolution methods ResolveWithRemoteRecord - overwrites the local with remote records ResolveWithLocalRecord - overwrites the remote with local records ResolveWithValue - to implement your own logic resolvedRecordsAdd(conflictRecordResolveWithRemoteRecord()) resolves the conflicts in local storage datasetResolve(resolvedRecords) on return true the synchronize operation continues where it left returning false cancels the synchronize operation return true

OnDatasetDeleted

删除数据集后Amazon Cognito 客户端将使用OnDatasetDeleted回调决定是否还应删除本地缓存的数据集副本默认情况下不会删除该数据集

private bool HandleDatasetDeleted(Dataset dataset) DebugLog(datasetMetadataDatasetName + Dataset has been deleted) Do clean up if necessary returning true informs the corresponding dataset can be purged in the local storage and return false retains the local dataset return true

OnDatasetMerged

当两个以前未连接的身份链接在一起后它们的所有数据集都将合并可通过 OnDatasetsMerged 回调向应用程序发送有关合并的通知

public bool HandleDatasetMerged(Dataset localDataset Listltstringgt mergedDatasetNames)

254


foreach (string name in mergedDatasetNames) Dataset mergedDataset = syncManagerOpenOrCreateDataset(name) Lambda function to delete the dataset after fetching it EventHandlerltSyncSuccessEventgt lambda lambda = (object sender SyncSuccessEvent e) =gt ICollectionltstringgt existingValues = localDatasetGetAll()Values ICollectionltstringgt newValues = mergedDatasetGetAll()Values

Implement your merge logic here

mergedDatasetDelete() Delete the dataset locally mergedDatasetOnSyncSuccess -= lambda We dont want this callback to be fired again mergedDatasetOnSyncSuccess += (object s2 SyncSuccessEvent e2) =gt localDatasetSynchronize() Continue the sync operation that was interrupted by the merge mergedDatasetSynchronize() Synchronize it as deleted failing to do so will leave us in an inconsistent state mergedDatasetOnSyncSuccess += lambda mergedDatasetSynchronize() Asnchronously fetch the dataset

returning true allows the Synchronize to continue and false stops it return false

Xamarin打开或创建数据集之后您可以为其设置不同的回调以在使用 Synchronize 方法时触发以下就是将回调注册到数据集的方法



OnSyncSuccess


private void HandleSyncSuccess(object sender SyncSuccessEventArgs e) Continue with your game flow display the loaded data etc

OnSyncFailure


private void HandleSyncFailure(object sender SyncFailureEventArgs e) Dataset dataset = sender as Dataset if (datasetMetadata = null)

255


ConsoleWriteLine(Sync failed for dataset + datasetMetadataDatasetName) else ConsoleWriteLine(Sync failed)

OnSyncConflict


private bool HandleSyncConflict(Dataset dataset List lt SyncConflict gt conflicts) if (datasetMetadata = null) ConsoleWriteLine(Sync conflict + datasetMetadataDatasetName) else ConsoleWriteLine(Sync conflict) List lt AmazonCognitoSyncSyncManagerRecord gt resolvedRecords = new List lt AmazonCognitoSyncSyncManagerRecord gt () foreach(SyncConflict conflictRecord in conflicts) SyncManager provides the following default conflict resolution methods ResolveWithRemoteRecord - overwrites the local with remote records ResolveWithLocalRecord - overwrites the remote with local records ResolveWithValue - to implement your own logic resolvedRecordsAdd(conflictRecordResolveWithRemoteRecord()) resolves the conflicts in local storage datasetResolve(resolvedRecords) on return true the synchronize operation continues where it left returning false cancels the synchronize operation return true

OnDatasetDeleted


private bool HandleDatasetDeleted(Dataset dataset) ConsoleWriteLine(datasetMetadataDatasetName + Dataset has been deleted) Do clean up if necessary returning true informs the corresponding dataset can be purged in the local storage and return false retains the local dataset return true

OnDatasetMerged


public bool HandleDatasetMerged(Dataset localDataset Listltstringgt mergedDatasetNames) foreach (string name in mergedDatasetNames) Dataset mergedDataset = syncManagerOpenOrCreateDataset(name)


256

Amazon Cognito 开发人员指南推送同步

mergedDatasetOnSyncSuccess += lambda mergedDatasetSynchronizeAsync() Asnchronously fetch the dataset


推送同步如果您是 Amazon Cognito Sync 的新用户请使用Amazon AppSync像 Amazon Cognito Sync一样Amazon AppSync是一种在设备之间同步应用程序数据的服务它允许用户数据（如应用首选项或游戏状态）进行同步它允许多个用户实时同步和协作处理共享的数据从而扩展了这些功能

Amazon Cognito 会自动跟踪身份和设备之间的关联使用推送同步功能您可以确保在身份数据发生更改后向给定身份的每个实例发送通知推送同步可以确保无论特定身份的同步存储数据何时发生更改与该身份关联的所有设备都会收到一个静音推送通知通知它们所发生的更改

Note

推送同步不支持 JavaScriptUnity 或 Xamarin

您必须首先设置用于推送同步的账户并在 Amazon Cognito 控制台中启用推送同步然后才可使用推送同步

创建 Amazon SSimple Notification Service (AmazonSNS) 应用为支持的平台创建并配置 Amazon SNS 应用程序如SNS 开发人员指南

在 Amazon Cognito 控制台中启用推送同步您可以通过 Amazon Cognito 控制台启用推送同步从控制台主页

1 单击您需要启用推送同步的身份池的名称此时将显示身份池的控制面板页2 在控制面板页的右上角单击 Manage Identity Pools (管理身份池)此时将显示联合身份页3 向下滚动并单击推送同步以将其展开4 在服务角色下拉菜单中选择授予 Cognito 发送 SNS 通知的权限的 IAM 角色单击创建角色以创建或

修改与身份池关联的角色AmazonIAM 控制台5 选择一个平台应用程序然后单击保存更改6 为应用程序授予 SNS 访问权限

在 IAM 控制台中将您的 IAM 角色配置为具有完整 SNS 访问权限或创建一个信任 Cognito 同步并具有完整 SNS 访问权限的新角色要了解有关 IAM 角色的更多信息请参阅角色（委托和联合）

在您的应用程序中使用推送同步Android您的应用程序需要导入 Google Play 服务您可以通过 Android SDK Manager 下载最新版本的 Google Play开发工具包按照 Android 有关 Android 实施的文档注册您的应用程序并接收来自 GCM 的注册 ID收到注册 ID 之后您需要向 Amazon Cognito 注册设备如以下代码段所示

257

Amazon Cognito 开发人员指南在您的应用程序中使用推送同步Android

String registrationId = MY_GCM_REGISTRATION_IDtry clientregisterDevice(GCM registrationId) catch (RegistrationFailedException rfe) Loge(TAG Failed to register device for silent sync rfe) catch (AmazonClientException ace) Loge(TAG An unknown error caused registration for silent sync to fail ace)

现在您可以订阅设备以接收来自特定数据集的更新

Dataset trackedDataset = clientopenOrCreateDataset(myDataset)if (clientisDeviceRegistered()) try trackedDatasetsubscribe() catch (SubscribeFailedException sfe) Loge(TAG Failed to subscribe to datasets sfe) catch (AmazonClientException ace) Loge(TAG An unknown error caused the subscription to fail ace)

要停止接收来自数据集的推送通知只需调用 unsubscribe 方法即可要订阅 CognitoSyncManager 对象中的所有数据集 (或特定子集)请使用 subscribeAll()

if (clientisDeviceRegistered()) try clientsubscribeAll() catch (SubscribeFailedException sfe) Loge(TAG Failed to subscribe to datasets sfe) catch (AmazonClientException ace) Loge(TAG An unknown error caused the subscription to fail ace)

实施 Android BroadcastReceiver 对象时您可以检查已修改数据集的最新版本并决定您的应用程序是否需要再次同步

Overridepublic void onReceive(Context context Intent intent)

PushSyncUpdate update = clientgetPushSyncUpdate(intent)

The update has the source (cognito-sync here) identityId of the user identityPoolId in question the non-local sync count of the data set and the name of the dataset All are accessible through relevant getters

String source = updategetSource() String identityPoolId = updategetIdentityPoolId() String identityId = updategetIdentityId() String datasetName = updategetDatasetName long syncCount = updategetSyncCount

Dataset dataset = clientopenOrCreateDataset(datasetName)

need to access last sync count If sync count is less or equal to last sync count of the dataset no sync is required

long lastSyncCount = datasetgetLastSyncCount() if (lastSyncCount lt syncCount)

258

Amazon Cognito 开发人员指南在您的应用程序中使用推送同步iOS ndash Objective-C

datasetsynchronize(new SyncCallback() )

推送通知负载中提供以下键

bull sourcecognito-sync这可以作为通知之间的区分因素bull identityPoolId身份池 ID这可用于验证或获取其他信息但从接收方的角度来看这并不是不可

或缺的bull identityId池中的身份 IDbull datasetName已更新的数据集的名称这可用于 openOrCreateDataset 调用bull syncCount远程数据集的同步计数您可以使用此方法来确保本地数据集已过期并且传入同步是新

的

在您的应用程序中使用推送同步iOS ndash Objective-C要获取应用程序的设备令牌请参阅 Apple 有关注册远程通知的文档收到来自 APN 的作为 NSData 对象的设备令牌之后您需要立 Amazon Cognito 使用registerDevice方法如下所示

AWSCognito syncClient = [AWSCognito defaultCognito] [[syncClient registerDevice devToken] continueWithBlockîd(AWSTask task) if(taskerror) NSLog(Unable to registerDevice taskerror) else NSLog(Successfully registered device with id taskresult) return nil ]

在调试模式下设备将向 APN 沙盒注册在发布模式下设备将向 APN 注册要接收来自特定数据集的更新请使用 subscribe 方法

[[[syncClient openOrCreateDatasetMyDataset] subscribe] continueWithBlockîd(AWSTask task) if(taskerror) NSLog(Unable to subscribe to dataset taskerror) else NSLog(Successfully subscribed to dataset taskresult) return nil ]

要停止接收来自数据集的推送通知只需调用 unsubscribe 方法即可

[[[syncClient openOrCreateDatasetrdquoMyDatasetrdquo] unsubscribe] continueWithBlockîd(AWSTask task) if(taskerror) NSLog(Unable to unsubscribe from dataset taskerror) else NSLog(Successfully unsubscribed from dataset taskresult) return nil

259


]

要订阅 AWSCognito 对象中的所有数据集请调用 subscribeAll

[[syncClient subscribeAll] continueWithBlockîd(AWSTask task) if(taskerror) NSLog(Unable to subscribe to all datasets taskerror) else NSLog(Successfully subscribed to all datasets taskresult) return nil ]

在调用 subscribeAll 之前请确保在每个数据集上至少同步一次以便数据集存在于服务器上

要对推送通知做出反应您需要在应用程序委托上实施 didReceiveRemoteNotification 方法

- (void)application(UIApplication )application didReceiveRemoteNotification(NSDictionary )userInfo [[NSNotificationCenter defaultCenter] postNotificationNameCognitoPushNotification objectuserInfo]

如果您使用通知处理程序发布通知则可以在您拥有数据集句柄的应用程序中的其他位置响应通知如果您按照如下方式订阅通知

[[NSNotificationCenter defaultCenter] addObserverself selectorselector(didReceivePushSync) name CognitoPushNotification objectnil]

则可以按照如下所示处理通知

- (void)didReceivePushSync(NSNotification)notification NSDictionary data = [(NSDictionary )[notification object] objectForKeydata] NSString identityId = [data objectForKeyidentityId] NSString datasetName = [data objectForKeydatasetName] if([selfdatasetname isEqualToStringdatasetName] ampamp [selfidentityId isEqualToStringidentityId]) [[selfdataset synchronize] continueWithBlockîd(AWSTask task) if(taskerror) NSLog(Successfully synced dataset) return nil ]



或缺的bull identityId池中的身份 IDbull datasetName已更新的数据集的名称这可用于 openOrCreateDataset 调用

260

Amazon Cognito 开发人员指南在您的应用程序中使用推送同步iOS ndash Swift

bull syncCount远程数据集的同步计数您可以使用此方法来确保本地数据集已过期并且传入同步是新的

在您的应用程序中使用推送同步iOS ndash Swift要获取应用程序的设备令牌请参阅 Apple 有关注册远程通知的文档收到来自 APN 的作为 NSData 对象的设备令牌之后您需要立即使用同步客户端的 register terDevice 方法向 Amazon Cognito 注册如下所示下面

let syncClient = AWSCognitodefault()syncClientregisterDevice(devToken)continueWith(block (task AWSTask) -gt AnyObject in if (taskerror = nil) print(Unable to register device + taskerrorlocalizedDescription)

else print(Successfully registered device with id (taskresult)) return task)


syncClientopenOrCreateDataset(MyDataset)subscribe()continueWith(block (task AWSTask) -gt AnyObject in if (taskerror = nil) print(Unable to subscribe to dataset + taskerrorlocalizedDescription)

else print(Successfully subscribed to dataset (taskresult)) return task)

要停止接收来自数据集的推送通知请调用 unsubscribe 方法

syncClientopenOrCreateDataset(MyDataset)unsubscribe()continueWith(block (task AWSTask) -gt AnyObject in if (taskerror = nil) print(Unable to unsubscribe to dataset + taskerrorlocalizedDescription)

else print(Successfully unsubscribed to dataset (taskresult)) return task)


syncClientopenOrCreateDataset(MyDataset)subscribeAll()continueWith(block (task AWSTask) -gt AnyObject in if (taskerror = nil) print(Unable to subscribe to all datasets + taskerrorlocalizedDescription)

else print(Successfully subscribed to all datasets (taskresult)) return task

261

Amazon Cognito 开发人员指南Amazon Cognito 流

)



func application(application UIApplication didReceiveRemoteNotification userInfo [NSObject AnyObject] fetchCompletionHandler completionHandler (UIBackgroundFetchResult) -gt Void) NSNotificationCenterdefaultCenter()postNotificationName(CognitoPushNotification object userInfo))


NSNotificationCenterdefaultCenter()addObserver(observerself selectordidReceivePushSync nameCognitoPushNotification objectnil)


func didReceivePushSync(notification NSNotification) if let data = (notificationobject as [String AnyObject])[data] as [String AnyObject] let identityId = data[identityId] as String let datasetName = data[datasetName] as String

if selfdatasetname == datasetName ampamp selfidentityId == identityId datasetsynchronize()continueWithBlock (task) -gt AnyObject in if taskerror == nil print(Successfully synced dataset) return nil




的

Amazon Cognito 流如果您是 Amazon Cognito Sync 的新用户请使用Amazon AppSync像 Amazon Cognito Sync一样Amazon AppSync是一种在设备之间同步应用程序数据的服务

262



Amazon Cognito 流让开发人员能够控制和了解他们存储在 Amazon Cognito 中的数据现在开发人员可以配置 Kinesis 流以便在数据更新和同步时接收事件Amazon Cognito 可以实时向您拥有的 Kinesis 流推送每个数据集更改

使用 Amazon Cognito 流您可以将所有的同步数据移动到 Kinesis然后将其流式传输到数据仓库工具（如Amazon Redshift）供进一步分析要了解有关 Kinesis 的更多信息请参阅使用 Amazon Kinesis

配置流

您可以在 Amazon Cognito 控制台中设置 Amazon Cognito 流要在 Amazon Cognito 控制台中启用Amazon Cognito 流您需要选择要将它发布到哪个 Kinesis 流以及授权 Amazon Cognito 将事件放入选定流中的 IAM 角色

从控制台主页

1 单击要为其设置 Amazon Cognito 流的身份池的名称此时将显示身份池的控制面板页2 在控制面板页的右上角单击 Manage Identity Pools (管理身份池)出现 Manage Federated Identities

页3 向下滚动并单击 Cognito Streams以将其展开4 在流名称下拉菜单中选择一个现有 Kinesis 流的名称或者单击创建流以创建一个流输入流的名称

和分片数量要了解分区并在如何估算流需要的分区数方面获取帮助请参阅Kinesis 开发人员指南5 在发布角色下拉菜单中选择授权 Amazon Cognito 发布流的 IAM 角色单击创建角色以创建或修改与

身份池关联的角色AmazonIAM 控制台6 在流状态下拉菜单中选择启用以启用流更新单击保存更改

成功配置 Amazon Cognito 流之后此身份池中数据集的所有后续更新都会发送到此流中

流内容

发送到流的每个记录都代表一次同步以下是一个发送到流的记录示例

identityPoolId Pool Id identityId Identity Id dataSetName Dataset Name operation (replace|remove) kinesisSyncRecords [ key Key value Value syncCount 1 lastModifiedDate 1424801824343 deviceLastModifiedDate 1424801824343 op (replace|remove) ] lastModifiedDate 1424801824343 kinesisSyncRecordsURL S3Url payloadType (S3Url|Inline) syncCount 1

对于大于 Kinesis 最大负载大小 50 KB 的更新将添加预签名 Amazon S3 URL其中包含完整的更新内容

263

Amazon Cognito 开发人员指南Amazon Cognito 事件

配置 Amazon Cognito 流之后如果您删除 Kinesis 流或更改角色信任权限以便它不再由 Amazon CognitoSync 承担则 Amazon Cognito 流将禁用您需要重新创建 Kinesis 流或修复角色然后需要重新启用此流

批量发布

配置 Amazon Cognito 流之后您能够对身份池中的现有数据执行批量发布操作通过控制台或直接通过API 启动批量发布操作之后Amazon Cognito 会开始将此数据发布到接收更新的同一流中

Amazon Cognito 不保证在使用批量发布操作时发送到流的数据具有唯一性您可能会收到两个相同的更新一个来自更新操作一个属于批量发布在处理来自流的记录时请记住这一点

要批量发布所有流请执行ldquo配置流rdquo下的步骤 1-6然后单击ldquoStart bulk publishrdquo任何特定时间都只能有一个正在进行的批量发布操作且每 24 小时只能有一次成功的批量发布请求

Amazon Cognito 事件如果您是 Amazon Cognito Sync 的新用户请使用Amazon AppSync像 Amazon Cognito Sync一样Amazon AppSync是一种在设备之间同步应用程序数据的服务它允许用户数据（如应用首选项或游戏状态）进行同步它允许多个用户实时同步和协作处理共享的数据从而扩展了这些功能

Amazon Cognito 事件让您能够执行Amazon Lambda函数以响应 Amazon Cognito 中的重要事件当数据集得到同步时Amazon Cognito 会引发同步触发事件当用户更新数据时您可以使用同步触发事件采取行动该函数可以评估并有选择性地操作数据然后数据才会存储到云中并同步到用户的其他设备这有利于在来自设备的数据同步到用户的其他设备之前对其进行验证或者基于传入数据更新数据集中的其他值如在玩家达到新级别时颁发奖励

以下步骤将引导您设置每次 Amazon Cognito 数据集同步时都会执行的 Lambda 函数Note

使用 Amazon Cognito 事件时您只能使用从 Amazon Cognito 身份获取的凭证如果你有一个关联的 Lambda 函数但你调用UpdateRecords替换为Amazon帐户凭证（开发人员凭证）则不会调用 Lambda 函数

在中创建函数 Amazon Lambda

要将 Lambda 与 Amazon Cognito 集成您首先需要在 Lambda 中创建函数为此请执行以下操作

在 Amazon Cognito 中选择 Lambda 函数

1 打开 Lambda 控制台2 单击 Create a Lambda function3 在ldquoSelect blueprintrdquo屏幕上搜索并选择ldquocognito-sync-triggerrdquo4 在ldquoConfigure event sourcesrdquo屏幕上将ldquoEvent source typerdquo设置保留为ldquoCognito Sync Triggerrdquo并选择您

的身份池单击 Next5 在ldquoConfigure functionrdquo屏幕上输入函数的名称和描述将ldquoRuntimerdquo设置保留为ldquoNodejsrdquo在我们的示例

中保留原来的代码默认示例没有更改正在同步的数据它只记录发生了 Amazon Cognito Sync Trigger事件这一事实将ldquoHandler namerdquo设置保留为ldquoindexhandlerrdquo对于 ldquoRolerdquo选择一个授权您的代码访问的 IAM 角色Amazon Lambda要修改角色请参阅 IAM 控制台将ldquoAdvancedrdquo设置保留不变单击Next

6 在ldquoReviewrdquo屏幕上查看详细信息并单击ldquoCreate functionrdquo下一页面将显示您的新 Lambda 函数

现在Lambda 中已经写入了相应的函数您需要选择该函数作为 Amazon Cognito Sync 触发事件的处理程序以下步骤将指导您完成此过程

264


从控制台主页

1 单击要为其设置 Amazon Cognito 事件的身份池的名称此时将显示身份池的控制面板页2 在 Dashboard 页的右上角单击 Manage Federated Identities出现 Manage Federated Identities 页3 向下滚动并单击ldquoCognito Eventsrdquo以将其展开4 在 ldquoSync Triggerrdquo 下拉菜单中选择您希望在同步事件发生时触发的 Lambda 函数5 单击保存更改

现在您的 Lambda 函数将在每次数据集同步时执行下一部分将介绍如何在数据同步时读取和修改函数中的数据

编写同步触发的 Lambda 函数

同步触发遵循服务提供商接口编程范例Amazon Cognito 将按照以下 JSON 格式为您的 Lambda 函数提供输入

version 2 eventType SyncTrigger region us-east-1 identityPoolId identityPoolId identityId identityId datasetName datasetName datasetRecords SampleKey1 oldValue oldValue1 newValue newValue1 op replace SampleKey2 oldValue oldValue2 newValue newValue2 op replace

Amazon Cognito 预计函数的返回值与输入格式相同下面提供了完整示例

编写同步触发事件的函数时应记住以下关键点

bull 在 UpdateRecords 过程中调用 Lambda 函数时该函数必须在 5 秒内响应如果没有Amazon CognitoSync 服务将引发LambdaSocketTimeoutException异常这个超时值无法增加

bull 如果您收到 LambdaThrottledException 异常则应重新尝试同步操作 (更新记录)bull Amazon Cognito 将提供数据集中出现的所有记录以作为函数的输入bull 对于应用程序用户更新的记录其ldquooprdquo字段将设置为ldquoreplacerdquo对于删除的记录其ldquooprdquo字段将设置

为ldquoremoverdquobull 您可以修改任何记录即使应用程序用户未进行更新也是如此bull 除 datasetRecords 之外的所有字段只能读取不应更改更改这些字段将导致记录更新失败bull 要修改记录的值只需更新该值并将ldquooprdquo设置为ldquoreplacerdquobull 要删除记录将ldquooprdquo设置为ldquoremoverdquo或将该值设置为空bull 要添加记录只需将新记录添加到 datasetRecords 数组bull 更新时将忽略响应中省略的所有记录

Lambda 函数示例

265


以下是显示如何访问修改和删除数据的示例 Lambda 函数

consolelog(Loading function)

exportshandler = function(event context) consolelog(JSONstringify(event null 2))

Check for the event type if (eventeventType === SyncTrigger)

Modify value for a key if(SampleKey1 in eventdatasetRecords) eventdatasetRecordsSampleKey1newValue = ModifyValue1 eventdatasetRecordsSampleKey1op = replace

Remove a key if(SampleKey2 in eventdatasetRecords) eventdatasetRecordsSampleKey2op = remove

Add a key if((SampleKey3 in eventdatasetRecords)) eventdatasetRecordsSampleKey3=newValueModifyValue3 op replace

contextdone(null event)

266

Amazon Cognito 开发人员指南数据保护

Amazon Cognito 中的安全保护Amazon的云安全性的优先级最高作为Amazon客户您将从专为满足大多数安全敏感型组织的要求而打造的数据中心和网络架构中受益

安全性是 Amazon 和您的共同责任责任共担模式将其描述为云的安全性和云中的安全性

bull 云的安全性 ndash Amazon负责保护在Amazon云中运行Amazon服务的基础设施Amazon还向您提供可安全使用的服务作为Amazon合规性计划的一部分第三方审计人员将定期测试和验证安全性的有效性要了解适用于 Amazon Cognito 的合规性计划请参阅Amazon合规性计划范围内的服务

bull 云中的安全性 - 您的责任由您使用的 Amazon 服务决定您还需要对其他因素负责包括您的数据的敏感性您公司的要求以及适用的法律法规

此文档将帮助您了解如何在使用 Amazon Cognito 时应用责任共担模式它说明了如何配置 Amazon Cognito以实现您的安全性和合规性目标您还将了解如何使用其他Amazon服务以帮助您监控和保护 AmazonCognito 资源

目录bull Amazon Cognito 中的数据保护 (p 267)bull Amazon Cognito 的 Identity and Access Management (p 268)bull Amazon Cognito 中的日志记录和监控 (p 289)bull Amazon Cognito 的合规性验证 (p 298)bull Amazon Cognito 中的恢复能力 (p 299)bull Amazon Cognito 中的基础设施安全性 (p 299)bull Amazon Cognito 用户池中的配置和漏洞分析 (p 300)bull Amazon Cognito 用户池的安全最佳实践 (p 300)bull AmazonAmazon Cognito 的托管策略 (p 311)

Amazon Cognito 中的数据保护这些区域有Amazon 责任共担模式适用于 Amazon Cognito（Amazon Cognito）中的数据保护如该模式中所述Amazon 负责保护运行所有 Amazon 云的全球基础设施您负责维护对托管在此基础设施上的内容的控制此内容包括您所使用的Amazon服务的安全配置和管理任务有关数据隐私的更多信息请参阅数据隐私常见问题

出于数据保护目的我们建议您保护Amazon账户凭证并使用 Amazon Identity and Access Management(IAM) 设置单独的用户账户这仅向每个用户授予履行其工作职责所需的权限我们还建议您通过以下方式保护您的数据

bull 对每个账户使用 Multi-Factor Authentication (MFA)bull 使用 SSLTLS 与Amazon资源进行通信bull 使用 Amazon CloudTrail 设置 API 和用户活动日志记录bull 使用Amazon加密解决方案以及Amazon服务中的所有默认安全控制bull 使用高级托管安全服务（例如 Amazon Macie）它有助于发现和保护存储在 Amazon S3 中的个人数据

我们强烈建议您切勿将敏感的可识别信息（例如您客户的账号）放入自由格式字段（例如 Name 字段）这包括当您使用 Amazon Cognito 或其他Amazon服务使用控制台APIAmazon CLI或者Amazon开发工具包您输入到 Amazon Cognito 或其他服务中的任何数据都可能被选取以包含在诊断日志中当您向外部服务器提供 URL 时请勿在 URL 中包含凭证信息来验证您对该服务器的请求

267

Amazon Cognito 开发人员指南数据加密

数据加密数据加密通常分为两类静态加密和传输中加密

静态加密

Amazon Cognito 中的数据按照行业标准进行静态加密

传输中加密

对 Amazon Cognito 的所有请求都必须使用传输层安全协议 (TLS) 发出客户端必须支持传输层安全性(TLS) 10 或更高版本建议使用 TLS 12 或更高版本客户端还必须支持具有完全向前保密 (PFS) 的密码套件例如 Ephemeral Diffie-Hellman (DHE) 或 Elliptic Curve Ephemeral Diffie-Hellman (ECDHE)大多数现代系统（如 Java 7 及更高版本）都支持这些模式

Note

Amazon Cognito 在内部加密客户内容并且不支持客户提供的密钥

Amazon Cognito 的 Identity and AccessManagement

Amazon Identity and Access Management (IAM) 是一种 Amazon 服务可以帮助管理员安全地控制对Amazon 资源的访问IAM 管理员可以控制哪些人身份验证(已登录) 和授权（具有权限）来使用 Cognito 资源IAM 是一个可以免费使用的Amazon服务

主题bull Audience (p 268)bull 使用身份进行身份验证 (p 269)bull 使用策略管理访问 (p 270)bull Amazon Cognito 如何与 IAM 协同工作 (p 271)bull Amazon Cognito 的基于身份的策略示例 (p 277)bull Amazon Cognito 身份和访问疑难解答 (p 279)bull 对 Amazon Cognito 使用服务相关角色 (p 281)bull 使用用户池进行身份验证 (p 283)

Audience您如何使用Amazon Identity and Access Management(IAM) 因您可以在 Cognito 中完成的工作而异

服务用户mdash 如果您使用 Cognito 服务来完成工作则您的管理员会为您提供所需的凭证和权限当您使用更多 Cognito 功能来完成工作时您可能需要额外权限了解如何管理访问权限可帮助您向管理员请求适合的权限如果您无法访问 Cognito 中的功能请参阅Amazon Cognito 身份和访问疑难解答 (p 279)

服务管理员mdash 如果您在公司负责管理 Cognito 资源则您可能具有的完全访问权限您有责任确定您的员工应访问哪些 Cognito 功能和资源然后您必须向 IAM 管理员提交请求以更改服务用户的权限请查看该页面上的信息以了解 IAM 的基本概念要了解有关您的公司如何将 IAM 与 Cognito 搭配使用的更多信息请参阅Amazon Cognito 如何与 IAM 协同工作 (p 271)

IAM 管理员mdash 如果您是 IAM 管理员您可能希望了解如何编写策略以管理 Cognito 的访问权限的详细信息要查看您可在 IAM 中使用的 Cognito 基于身份的策略示例请参阅Amazon Cognito 的基于身份的策略示例 (p 277)

268

Amazon Cognito 开发人员指南使用身份进行身份验证

使用身份进行身份验证身份验证是您使用身份凭证登录 Amazon 的方法有关使用 Amazon Web Services Management Console登录的更多信息请参阅 IAM 用户指南中的以 Amazon Web Services Management Console IAM 用户或根用户身份登录

您必须是身份验证登录到Amazon）作为 Amazon Web Services 账户根用户IAM 用户或代入 IAM 角色您还可以使用公司的单一登录身份验证方法甚至使用 Google 或 Facebook 登录在这些情况下您的管理员以前使用 IAM 角色设置了联合身份验证在您使用来自其他公司的凭证访问 Amazon 时您间接地代入了角色

要直接登录到 Amazon Web Services Management Console请将密码与根用户电子邮件地址或 IAM 用户名一起使用您可以使用根用户或 IAM 用户访问密钥以编程方式访问AmazonAmazon提供了开发工具包和命令行工具可使用您的凭证对您的请求进行加密签名如果您不使用 Amazon 工具则必须自行对请求签名使用签名版本 4（用于对入站 API 请求进行验证的协议）完成此操作有关验证请求的更多信息请参阅《Amazon 一般参考》中的 Signature Version 4 签名流程

无论使用何种身份验证方法您可能还需要提供其他安全信息例如Amazon 建议您使用多重身份验证(MFA) 来提高账户的安全性要了解更多信息请参阅《IAM 用户指南》中的在 Amazon 中使用多重身份验证 (MFA)

Amazon Web Services 账户根用户当您第一次创建 Amazon Web Services 账户中最初使用的是一个对所有Amazon账户中的服务和资源此身份称为 Amazon Web Services 账户根用户您可以使用您创建账户时所用的电子邮件地址和密码登录来获得该功能强烈建议您不使用根用户执行日常任务即使是管理任务相反请遵循仅使用根用户创建您的第一个 IAM 用户的最佳实践然后请妥善保存根用户凭证仅用它们执行少数账户和服务管理任务

IAM 用户和组网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的IAM 用户是您的 Amazon Web Services 账户具有针对某个人员或应用程序的特定权限IAM 用户可能具有长期凭证例如用户名和密码或一组访问密钥要了解如何生成访问密钥请参阅 IAM 用户指南中的管理 IAM 用户的访问密钥为 IAM 用户生成访问密钥时请确保查看并安全保存密钥对您以后无法找回秘密访问密钥而是必须生成新的访问密钥对

IAM 组是一个指定一组 IAM 用户的身份您不能使用组的身份登录您可以使用组来一次性为多个用户指定权限如果有大量用户使用组可以更轻松地管理用户权限例如您可能具有一个名为 IAMAdmins 的组并为该组授予权限以管理 IAM 资源

用户与角色不同用户唯一地与某个人员或应用程序关联而角色旨在让需要它的任何人代入用户具有永久的长期凭证而角色提供临时凭证要了解更多信息请参阅 IAM 用户指南中的何时创建 IAM 用户（而不是角色）

IAM 角色网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的IAM 角色是您的 Amazon Web Services账户具有特定权限它类似于 IAM 用户但与特定人员不关联您可以通过切换角色在 Amazon WebServices Management Console 中暂时代入 IAM 角色您可以调用 Amazon CLI 或 Amazon API 操作或使用自定义 URL 以代入角色有关使用角色的方法的更多信息请参阅 IAM 用户指南中的使用 IAM 角色

具有临时凭证的 IAM 角色在以下情况下很有用

bull 临时 IAM 用户权限 ndash IAM 用户可以代入 IAM 角色以暂时获得不同的权限以执行特定的任务bull 联合身份用户访问 ndash 您可以不创建 IAM 用户而是使用来自 Amazon Directory Service您的企业用

户目录或 Web 身份提供商的现有身份这些用户被称为联合用户在通过身份提供商请求访问权限时Amazon将为联合身份用户分配角色有关联合身份用户的更多信息请参阅 IAM 用户指南中的联合身份用户和角色

269

Amazon Cognito 开发人员指南使用策略管理访问

bull 跨账户访问 ndash 您可以使用 IAM 角色以允许不同账户中的某个人（可信委托人）访问您的账户中的资源角色是授予跨账户访问权限的主要方式但是对于某些 Amazon 服务您可以将策略直接附加到资源（而不是使用角色作为代理）要了解用于跨账户访问的角色和基于资源的策略之间的差别请参阅 IAM 用户指南中的 IAM 角色与基于资源的策略有何不同

bull 跨服务访问 ndash 某些 Amazon 服务使用其他 Amazon 服务中的功能例如当您在某个服务中进行调用时该服务通常会在 Amazon EC2 中运行应用程序或在 Amazon S3 中存储对象服务可能会使用发出调用的委托人的权限使用服务角色或使用服务相关角色来执行此操作bull 委托人权限 ndash 当您使用 IAM 用户或角色在 Amazon 中执行操作时您将被视为委托人策略向委托人

授予权限使用某些服务时您可能会执行一个操作此操作然后在不同服务中触发另一个操作在这种情况下您必须具有执行这两个操作的权限要查看某个操作是否需要策略中的其他相关操作请参阅Amazon Cognito 的操作资源和条件键中的服务授权参考

bull 服务角色 ndash 服务角色是服务代表您在您的账户中执行操作而担任的 IAM 角色服务角色只在您的账户内提供访问权限不能用于为访问其他账户中的服务授权IAM 管理员可以在 IAM 中创建修改和删除服务角色有关更多信息请参阅 IAM 用户指南中的创建向Amazon服务委派权限的角色

bull 服务相关角色 ndash 服务相关角色是与 Amazon 服务关联的一种服务角色服务可以代入代表您执行操作的角色服务相关角色显示在您的 IAM 账户中并归该服务所有IAM 管理员可以查看但不能编辑服务相关角色的权限

bull 在 Amazon EC2 上运行的应用程序 ndash 您可以使用 IAM 角色管理在 EC2 实例上运行并发出 Amazon CLI 或Amazon API 请求的应用程序的临时凭证这优先于在 EC2 实例中存储访问密钥要将Amazon角色分配给 EC2 实例并使其对该实例的所有应用程序可用您可以创建一个附加到实例的实例配置文件实例配置文件包含角色并使 EC2 实例上运行的程序能够获得临时凭证有关更多信息请参阅 IAM 用户指南中的使用 IAM 角色为 Amazon EC2 实例上运行的应用程序授予权限

要了解是使用 IAM 角色还是 IAM 用户请参阅 IAM 用户指南中的何时创建 IAM 角色（而不是用户）

使用策略管理访问您将创建策略并将其附加到 IAM 身份或Amazon资源以便控制Amazon中的访问策略是Amazon中的对象在与标识或资源相关联时策略定义它们的权限您可以通过 root 用户或 IAM 用户身份登录也可以代入 IAM 角色随后当您提出请求时Amazon会评估相关的基于身份或基于资源的策略策略中的权限确定是允许还是拒绝请求大多数策略在 Amazon 中存储为 JSON 文档有关 JSON 策略文档的结构和内容的更多信息请参阅 IAM 用户指南中的 JSON 策略概述

管理员可以使用 Amazon JSON 策略来指定谁有权访问什么内容也就是说哪个委托人可以对什么资源执行操作以及在什么条件下执行

每个 IAM 实体（用户或角色）最初没有任何权限换言之默认情况下用户什么都不能做甚至不能更改他们自己的密码要为用户授予执行某些操作的权限管理员必须将权限策略附加到用户或者管理员可以将用户添加到具有预期权限的组中当管理员为某个组授予访问权限时该组内的全部用户都会获得这些访问权限

IAM 策略定义操作的权限无关乎您使用哪种方法执行操作例如假设您有一个允许 iamGetRole 操作的策略具有该策略的用户可以从 Amazon Web Services Management ConsoleAmazon CLI 或 AmazonAPI 获取角色信息

基于身份的策略基于身份的策略是可附加到身份（如 IAM 用户用户组或角色）的 JSON 权限策略文档这些策略控制用户和角色可在何种条件下对哪些资源执行哪些操作要了解如何创建基于身份的策略请参阅 IAM 用户指南中的创建 IAM 策略

基于身份的策略可以进一步归类为内联策略或托管策略内联策略直接嵌入单个用户组或角色中托管策略是可以附加到您在 Amazon Web Services 账户托管策略包括 Amazon 托管策略和客户托管策略要了解如何在托管策略和内联策略之间进行选择请参阅 IAM 用户指南中的在托管策略与内联策略之间进行选择

270

Amazon Cognito 开发人员指南Amazon Cognito 如何与 IAM 协同工作

基于资源的策略基于资源的策略是附加到资源的 JSON 策略文档基于资源的策略的示例包括 IAM 角色信任策略和Amazon S3 存储桶策略在支持基于资源的策略的服务中服务管理员可以使用它们来控制对特定资源的访问对于在其中附加策略的资源策略定义指定委托人可以对该资源执行哪些操作以及在什么条件下执行您必须在基于资源的策略中指定委托人委托人可以包括账户用户角色联合身份用户或 Amazon 服务

基于资源的策略是位于该服务中的内联策略您不能在基于资源的策略中使用来自 IAM 的 Amazon 托管策略

访问控制列表 (ACL)访问控制列表 (ACL) 控制哪些委托人（账户成员用户或角色）有权访问资源ACL 与基于资源的策略类似尽管它们不使用 JSON 策略文档格式

Amazon S3Amazon WAF 和 Amazon VPC 是支持 ACL 的服务示例要了解有关 ACL 的更多信息请参阅 Amazon Simple Storage Service 开发人员指南中的访问控制列表 (ACL) 概述

其他策略类型Amazon 支持额外的不太常用的策略类型这些策略类型可以设置更常用的策略类型向您授予的最大权限

bull 权限边界 ndash 权限边界是一个高级功能用于设置基于身份的策略可以为 IAM 实体（IAM 用户或角色）授予的最大权限您可为实体设置权限边界这些结果权限是实体的基于身份的策略及其权限边界的交集在Principal 中指定用户或角色的基于资源的策略不受权限边界限制任一项策略中的显式拒绝将覆盖允许有关权限边界的更多信息请参阅 IAM 用户指南中的 IAM 实体的权限边界

bull 服务控制策略 (SCP)mdash SCP 是指定组织或组织单元 (OU) 的最大权限的 JSON 策略AmazonOrganizationsAmazon Organizations是用于分组和集中管理多个 Amazon Web Services 账户您的企业拥有如果在组织内启用了所有功能则可对任意或全部账户应用服务控制策略 (SCP)SCP 限制成员账户中实体的权限包括每个 Amazon Web Services 账户根用户有关 Organization 和 SCP 的更多信息请参阅《Amazon Organizations 用户指南》中的 SCP 的工作原理

bull 会话策略 ndash 会话策略是当您以编程方式为角色或联合身份用户创建临时会话时作为参数传递的高级策略结果会话的权限是用户或角色的基于身份的策略和会话策略的交集权限也可以来自基于资源的策略任一项策略中的显式拒绝将覆盖允许有关更多信息请参阅 IAM 用户指南中的会话策略

多个策略类型当多个类型的策略应用于一个请求时生成的权限更加复杂和难以理解要了解如何 Amazon 确定在涉及多种策略类型时是否允许请求请参阅《IAM 用户指南》中的策略评估逻辑

Amazon Cognito 如何与 IAM 协同工作在使用 IAM 管理对 Cognito 的访问权限之前请了解哪些 IAM 功能可与 Cognito 协同工作

您可以与 Amazon Cognito 一起使用的 IAM 功能

IAM 功能 Cognito 支持

基于身份的策略 (p 272) 是

基于资源的策略 (p 272) 否

271



策略操作 (p 273) 是

策略资源 (p 274) 是

策略条件键 (p 275) 是

ACL (p 275) 否

ABAC（策略中的标签） (p 276) 部分

临时凭证 (p 276) 是

委托人权限 (p 276) 否

服务角色 (p 276) 是

服务相关角色 (p 277) 是

获取 Cognito 和其他概要视图Amazon服务与大多数 IAM 功能配合使用请参阅Amazon使用 IAM 的服务中的IAM 用户指南

Cognito 的基于身份的策略

支持基于身份的策略是

基于身份的策略是可附加到身份（如 IAM 用户用户组或角色）的 JSON 权限策略文档这些策略控制用户和角色可在何种条件下对哪些资源执行哪些操作要了解如何创建基于身份的策略请参阅 IAM 用户指南中的创建 IAM 策略

通过使用 IAM 基于身份的策略您可以指定允许或拒绝的操作和资源以及允许或拒绝操作的条件您无法在基于身份的策略中指定委托人因为它适用于其附加到的用户或角色要了解您可在 JSON 策略中使用的所有元素请参阅IAM JSON 策略元素参考中的IAM 用户指南

Cognito 的基于身份的策略示例

要查看 Cognito 基于身份的策略的示例请参阅Amazon Cognito 的基于身份的策略示例 (p 277)

Cognito 中的基于资源的策略

支持基于资源的策略否

基于资源的策略是附加到资源的 JSON 策略文档基于资源的策略的示例包括 IAM 角色信任策略和Amazon S3 存储桶策略在支持基于资源的策略的服务中服务管理员可以使用它们来控制对特定资源的访问对于在其中附加策略的资源策略定义指定委托人可以对该资源执行哪些操作以及在什么条件下执行您必须在基于资源的策略中指定委托人委托人可以包括账户用户角色联合身份用户或 Amazon 服务

要启用跨账户访问您可以将整个账户或其他账户中的 IAM 实体指定为基于资源的策略中的委托人将跨账户委托人添加到基于资源的策略只是建立信任关系工作的一半而已当委托人和资源处于不同 Amazon WebServices 账户则可信账户中的 IAM 管理员还必须授予委托人实体（用户或角色）对资源的访问权限他们通过将基于身份的策略附加到实体以授予权限但是如果基于资源的策略向同一个账户中的委托人授予

272


访问权限则不需要额外的基于身份的策略有关更多信息请参阅 IAM 角色与基于资源的策略有何区别中的IAM 用户指南

Cognito 的策略操作

支持策略操作是


JSON 策略的 Action 元素描述可用于在策略中允许或拒绝访问的操作策略操作通常与关联的 AmazonAPI 操作同名有一些例外情况例如没有匹配 API 操作的仅限权限操作还有一些操作需要在策略中执行多个操作这些附加操作称为相关操作

在策略中包含操作以授予执行相关操作的权限

要查看 Cognito 操作的列表请参阅Amazon Cognito 定义的操作中的服务授权参考

Cognito 中的策略操作在操作前使用以下前缀

cognito-identity

要在单个语句中指定多项操作请使用逗号将它们隔开

Action [ cognito-identityaction1 cognito-identityaction2 ]

签名与未签名的 API

已签名的 APIAmazon凭证能够通过 IAM 策略进行限制以下 Cognito API 未签名因此无法通过 IAM 策略进行限制

Amazon Cognito 联合身份

bull GetId

bull GetOpenIdToken

bull GetCredentialsForIdentity

bull UnlinkIdentity

Amazon Cognito 您的用户池

bull ChangePassword

bull ConfirmDevice

bull ConfirmForgotPassword

bull ConfirmSignUp

bull DeleteUser

bull DeleteUserAttributes

bull ForgetDevice

273


bull ForgotPassword

bull GetDevice

bull GetUser

bull GetUserAttributeVerificationCode

bull GlobalSignOut

bull InitiateAuth

bull ListDevices

bull ResendConfirmationCode


bull SetUserSettings

bull SignUp

bull UpdateDeviceStatus

bull UpdateUserAttributes

bull VerifyUserAttribute


Cognito 的策略资源

支持策略资源是


Resource JSON 策略元素指定要向其应用操作的一个或多个对象语句必须包含 Resource 或NotResource 元素作为最佳实践请使用其 Amazon 资源名称 (ARN)指定资源对于支持特定资源类型（称为资源级权限）的操作您可以执行此操作

对于不支持资源级权限的操作（如列出操作）请使用通配符 () 指示语句应用于所有资源

Resource

Amazon 资源名称 (ARN)

Amazon Cognito 联合身份的 ARN

在 Amazon Cognito 身份池（联合身份）中您可以使用如下例所示的 Amazon 资源名称 (ARN) 格式限制IAM 用户对特定身份池的访问权限有关 ARN 的更多信息请参阅 IAM 标识符

arnawscognito-identityREGIONACCOUNT_IDidentitypoolIDENTITY_POOL_ID

Amazon Cognito Sync 的 ARN

在 Amazon Cognito Sync 中客户还可以按身份池 ID身份 ID 和数据集名称限制访问

对于在身份池上运行的 API身份池 ARN 格式与 Amazon Cognito 联合身份的相同但前者的服务名称是cognito-sync而不是cognito-identity

274


arnawscognito-syncREGIONACCOUNT_IDidentitypoolIDENTITY_POOL_ID

对于在单个身份池上运行的 API (例如 RegisterDevice)您可以通过以下 ARN 格式引用单个身份

arnawscognito-syncREGIONACCOUNT_IDidentitypoolIDENTITY_POOL_IDidentityIDENTITY_ID

有关在数据集上运行的 API (例如 UpdateRecords 和 ListRecords)您可以使用以下 ARN 格式引用单个数据集

arnawscognito-syncREGIONACCOUNT_IDidentitypoolIDENTITY_POOL_IDidentityIDENTITY_IDdatasetDATASET_NAME

Amazon Cognito 您的用户池的 ARN

对于 Amazon Cognito 您的用户池您可以使用以下 ARN 格式限制 IAM 用户对特定用户池的访问权限

arnawscognito-idpREGIONACCOUNT_IDuserpoolUSER_POOL_ID

要查看 Cognito 资源类型及其 ARN 的列表请参阅Amazon Cognito 定义的资源中的服务授权参考要了解您可以使用哪些操作指定每个资源的 ARN请参阅Amazon Cognito 定义的操作


Cognito 的策略条件密钥

支持策略条件密钥是


在 Condition 元素（或 Condition 块）中可以指定语句生效的条件Condition 元素是可选的您可以创建使用条件运算符（例如等于或小于）的条件表达式以使策略中的条件与请求中的值相匹配

如果您在一个语句中指定多个 Condition 元素或在单个 Condition 元素中指定多个键则 Amazon 使用逻辑 AND 运算评估它们如果您为单个条件键指定多个值则 Amazon 使用逻辑 OR 运算来评估条件在授予语句的权限之前必须满足所有的条件

在指定条件时您也可以使用占位符变量例如只有在使用 IAM 用户名标记 IAM 用户时您才能为其授予访问资源的权限有关更多信息请参阅 IAM 用户指南中的 IAM 策略元素变量和标签

Amazon支持全局条件键和特定于服务的条件键要查看所有 Amazon 全局条件键请参阅 IAM 用户指南中的 Amazon 全局条件上下文键

要查看 Cognito 条件键的列表请参阅Amazon Cognito 的条件键中的服务授权参考要了解您可以对哪些操作和资源使用条件键请参阅Amazon Cognito 定义的操作


Cognito 中的访问控制列表 (ACL)

支持 ACL 否

275


访问控制列表 (ACL) 控制哪些委托人（账户成员用户或角色）有权访问资源ACL 与基于资源的策略类似尽管它们不使用 JSON 策略文档格式

Cognito 的基于属性的访问控制 (ABAC)

支持 ABAC（策略中的标签）部分

基于属性的访问控制 (ABAC) 是一种授权策略该策略基于属性来定义权限在 Amazon 中这些属性称为标签您可以将标签附加到 IAM 实体（用户或角色）以及许多Amazon资源的费用标记实体和资源是ABAC 的第一步然后您可以设计 ABAC 策略以便在委托人的标签与他们试图访问的资源上的标签匹配时允许操作

ABAC 在快速增长的环境中非常有用并在策略管理变得繁琐的情况下可以提供帮助

要基于标签控制访问您需要使用 awsResourceTagkey-nameawsRequestTagkey-name 或awsTagKeys 条件键在策略的条件元素中提供标签信息

有关 ABAC 的更多信息请参阅什么是 ABAC中的IAM 用户指南要查看包含设置 ABAC 步骤的教程请参阅使用基于属性的访问控制 (ABAC)中的IAM 用户指南

将临时证书与 Cognito 一起使用

支持临时凭证是

一段时间Amazon服务在您使用临时证书登录时无法正常工作有关更多信息包括Amazon服务与临时证书配合使用请参阅Amazon使用 IAM 的服务中的IAM 用户指南

您正在使用临时证书如果您登录到Amazon Web Services Management Console使用除用户名和密码之外的任何方法例如当您访问Amazon使用您公司的单点登录 (SSO) 链接则该过程将自动创建临时凭证当您以用户身份登录控制台然后切换角色时您还会自动创建临时凭证有关切换角色的更多信息请参阅切换为角色（控制台）中的IAM 用户指南

您可以手动创建临时证书使用Amazon CLI或者AmazonAPI之后您可以使用这些临时凭证访问AmazonAmazon建议您动态生成临时证书而不是使用长期访问密钥有关更多信息请参阅 IAM 中的临时安全凭证

Cognito 的跨服务主体权限

支持委托人权限否

当您使用 IAM 用户或角色在Amazon您将被视为一个委托人策略向委托人授予权限使用某些服务时您可能会执行一个操作此操作然后在不同服务中触发另一个操作在这种情况下您必须具有执行这两个操作的权限要查看某个操作是否需要策略中的其他相关操作请参阅Amazon Cognito 的操作资源和条件键中的服务授权参考

Cognito 的服务角色

支持服务角色是

276

Amazon Cognito 开发人员指南基于身份的策略示例

服务角色是IAM 角色服务代表您执行操作而担任的操作服务角色只在您的账户内提供访问权限不能用于为访问其他账户中的服务授权IAM 管理员可以在 IAM 中创建修改和删除服务角色有关更多信息请参阅 IAM 用户指南中的创建向Amazon服务委派权限的角色

有关 Cognito 服务角色的详细信息请参阅启用推送同步 (p 179)和推送同步 (p 257)Warning

更改服务角色的权限可能会破坏 Cognito 功能仅当 Cognito 提供相关指导时才编辑服务角色

Cognito 的服务相关角色

支持服务相关角色是

服务相关角色是与Amazon服务服务可以代入代表您执行操作的角色服务相关角色显示在您的 IAM 账户中并归该服务所有IAM 管理员可以查看但不能编辑服务相关角色的权限

有关创建或管理 Cognito 服务相关角色的详细信息请参阅对 Amazon Cognito 使用服务相关角色 (p 281)

Amazon Cognito 的基于身份的策略示例默认情况下IAM 用户和角色没有创建或修改 Cognito 资源的权限它们还无法使用 Amazon Web ServicesManagement ConsoleAmazon CLI 或 Amazon API 执行任务IAM 管理员必须创建 IAM 策略以便为用户和角色授予权限以对所需的资源执行操作然后管理员必须将这些策略附加到需要这些权限的 IAM 用户或组

要了解如何使用这些示例 JSON 策略文档创建基于 IAM 身份的策略请参阅在ldquoJSONrdquo选项卡上创建策略中的IAM 用户指南

主题bull 策略最佳实践 (p 277)bull 使用 Cognito 控制台 (p 278)bull 允许用户查看他们自己的权限 (p 278)bull 限制对特定身份池的控制台访问权限 (p 278)bull 允许池中的所有身份访问特定数据集 (p 279)

策略最佳实践基于身份的策略非常强大它们确定某个人是否可以创建访问或删除您账户中的 Cognito 资源这些操作可能会使您的 Amazon Web Services 账户创建或编辑基于身份的策略时请遵循以下准则和建议

bull 入门Amazon托管策略mdash 要快速开始使用 Cognito请使用Amazon托管策略为您的员工授予所需的权限这些策略已在您的账户中提供并由 Amazon 维护和更新有关更多信息请参阅 IAM 用户指南中的开始使用 Amazon 托管策略中的权限

bull 授予最低权限 ndash 创建自定义策略时仅授予执行任务所需的许可最开始只授予最低权限然后根据需要授予其他权限这样做比起一开始就授予过于宽松的权限而后再尝试收紧权限来说更为安全有关更多信息请参阅 IAM 用户指南中的授予最低权限

bull 为敏感操作启用 MFA ndash 为了提高安全性要求 IAM 用户使用多重验证 (MFA) 访问敏感资源或 API 操作有关更多信息请参阅《IAM 用户指南》中的在 Amazon 中使用多重身份验证 (MFA)

bull 使用策略条件来增强安全性 ndash 在切实可行的范围内定义基于身份的策略在哪些情况下允许访问资源例如您可编写条件来指定请求必须来自允许的 IP 地址范围您也可以编写条件以便仅允许指定日期或时间范围内的请求或者要求使用 SSL 或 MFA有关更多信息请参阅 IAM JSON 策略元素Condition中的IAM 用户指南

277


使用 Cognito 控制台要访问 Amazon Cognito 控制台您必须拥有一组最低的权限这些权限必须允许您列出和查看有关Cognito 资源的详细信息 Amazon Web Services 账户如果您创建的基于身份的策略比所需的最低权限更严格则无法为具有该策略的实体（IAM 用户或角色）正常运行控制台

对于只需要调用 Amazon CLI 或 Amazon API 的用户无需为其提供最低控制台权限相反只允许访问与您尝试执行的 API 操作相匹配的操作

为确保用户和角色仍可使用 Cognito 控制台还请将 Cognito 附加到ConsoleAccess或者ReadOnlyAmazon托管策略添加到实体有关更多信息请参阅向用户添加权限中的IAM 用户指南

允许用户查看他们自己的权限该示例说明了您如何创建策略以允许 IAM 用户查看附加到其用户身份的内联和托管策略此策略包括在控制台上完成此操作或者以编程方式使用 Amazon CLI 或 Amazon API 所需的权限

Version 2012-10-17 Statement [ Sid ViewOwnUserInfo Effect Allow Action [ iamGetUserPolicy iamListGroupsForUser iamListAttachedUserPolicies iamListUserPolicies iamGetUser ] Resource [arnawsiamuser$awsusername] Sid NavigateInConsole Effect Allow Action [ iamGetGroupPolicy iamGetPolicyVersion iamGetPolicy iamListAttachedGroupPolicies iamListGroupPolicies iamListPolicyVersions iamListPolicies iamListUsers ] Resource ]

限制对特定身份池的控制台访问权限 Version 2012-10-17 Statement [ Effect Allow Action [ cognito-identityListIdentityPools ] Resource

278

Amazon Cognito 开发人员指南问题排查

Effect Allow Action [ cognito-identity ] Resource arnawscognito-identityus-east-10123456789identitypoolus-east-11a1a1a1a-ffff-1111-9999-12345678 Effect Allow Action [ cognito-sync ] Resource arnawscognito-syncus-east-10123456789identitypoolus-east-11a1a1a1a-ffff-1111-9999-12345678 ]

允许池中的所有身份访问特定数据集 Version 2012-10-17 Statement [ Effect Allow Action [ cognito-syncListRecords cognito-syncUpdateRecords ] Resource arnawscognito-syncus-east-10123456789identitypoolus-east-11a1a1a1a-ffff-1111-9999-12345678identitydatasetUserProfile ]

Amazon Cognito 身份和访问疑难解答使用以下信息可帮助您诊断和修复在使用 Cognito 和 IAM 时可能遇到的常见问题

主题bull 我无权在 Cognito 中执行操作 (p 279)bull 我无权执行 iamPassRole (p 280)bull 我想要查看我的访问密钥 (p 280)bull 我是管理员并希望允许其他人访问 Cognito (p 280)bull 我想要允许我的Amazon帐户来访问我的 Cognito 资源 (p 280)

我无权在 Cognito 中执行操作如果 Amazon Web Services Management Console 告诉您您无权执行某个操作则必须联系您的管理员寻求帮助您的管理员是指为您提供用户名和密码的那个人

下面的示例错误发生时mateojacksonIAM 用户尝试使用控制台来查看有关虚构的详细信息my-example-widget资源但没有虚构cognito-identityGetWidget权限

279


User arnawsiam123456789012usermateojackson is not authorized to perform cognito-identityGetWidget on resource my-example-widget

在这种情况下Mateo 请求他的管理员更新其策略以允许他使用 cognito-identityGetWidget 操作访问 my-example-widget 资源

我无权执行 iamPassRole如果您收到错误消息提示您无权执行 iamPassRole 操作则必须联系您的管理员寻求帮助您的管理员是指为您提供用户名和密码的那个人请求该人员更新您的策略以允许您将角色传递给 Cognito

有些 Amazon 服务允许您将现有角色传递到该服务而不是创建新服务角色或服务相关角色为此您必须具有将角色传递到服务的权限

当名为的 IAM 用户时会发生以下示例错误marymajor尝试使用控制台在 Cognito 中执行操作但是服务必须具有服务角色所授予的权限才可执行操作Mary 不具有将角色传递到服务的权限

User arnawsiam123456789012usermarymajor is not authorized to perform iamPassRole

在这种情况下Mary 请求她的管理员来更新其策略以允许她执行 iamPassRole 操作

我想要查看我的访问密钥在创建 IAM 用户访问密钥后您可以随时查看您的访问密钥 ID但是您无法再查看您的秘密访问密钥如果您丢失了私有密钥则必须创建一个新的访问密钥对

访问密钥包含两部分访问密钥 ID（例如 AKIAIOSFODNN7EXAMPLE）和秘密访问密钥（例如wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY）与用户名和密码一样您必须同时使用访问密钥ID 和秘密访问密钥对请求执行身份验证像对用户名和密码一样安全地管理访问密钥

Important

请不要向第三方提供访问密钥即便是为了帮助找到您的规范用户 ID 也不行如果您这样做可能会向某人提供对您的账户的永久访问权限

当您创建访问密钥对时系统会提示您将访问密钥 ID 和秘密访问密钥保存在一个安全位置秘密访问密钥仅在您创建它时可用如果丢失了您的秘密访问密钥您必须为 IAM 用户添加新的访问密钥您最多可拥有两个访问密钥如果您已有两个密钥则必须删除一个密钥对然后再创建新的密钥要查看说明请参阅IAM 用户指南中的管理访问密钥

我是管理员并希望允许其他人访问 Cognito要允许其他人访问 Cognito您必须为需要访问权限的人员或应用程序创建一个 IAM 实体（用户或角色）它们将使用该实体的凭证访问Amazon然后您必须将策略附加到实体以便在 Cognito 中为其授予正确的权限

要立即开始使用请参阅 IAM 用户指南中的创建您的第一个 IAM 委派用户和组

我想要允许我的Amazon帐户来访问我的 Cognito 资源您可以创建一个角色以便其他账户中的用户或您组织外的人员可以使用该角色来访问您的资源您可以指定谁值得信赖可以代入角色对于支持基于资源的策略或访问控制列表 (ACL) 的服务您可以使用这些策略向人员授予对您的资源的访问权

要了解更多信息请参阅以下内容

bull 要了解 Cognito 是否支持这些功能请参阅Amazon Cognito 如何与 IAM 协同工作 (p 271)

280

Amazon Cognito 开发人员指南使用服务相关角色

bull 要了解如何跨 Amazon Web Services 账户您拥有的请参阅在另一个中向 IAM 用户提供访问权限Amazon Web Services 账户您拥有的中的IAM 用户指南

bull 要了解如何向第三方提供对资源的访问权限 Amazon Web Services 账户请参阅提供访问权限 AmazonWeb Services 账户由第三方拥有中的IAM 用户指南

bull 要了解如何通过联合身份验证提供访问权限请参阅 IAM 用户指南中的为经过外部身份验证的用户（联合身份验证）提供访问权限

bull 要了解使用角色和基于资源的策略进行跨账户访问之间的差别请参阅 IAM 用户指南中的 IAM 角色与基于资源的策略有何不同

对 Amazon Cognito 使用服务相关角色Amazon Cognito 使用Amazon Identity and Access Management(IAM)服务相关角色服务相关角色是一种独特类型的 IAM 角色它与 Amazon Cognito 直接相关服务相关角色由 Amazon Cognito 预定义并包含服务调用其他Amazon代表您的服务

服务相关角色可让您更轻松地设置 Amazon Cognito因为您不必手动添加必要的权限Amazon Cognito 定义其服务相关角色的权限除非另外定义否则只有 Amazon Cognito 可以代入该角色定义的权限包括信任策略和权限策略以及不能附加到任何其他 IAM 实体的权限策略

只有在首先删除相关资源后才能删除服务相关角色这将保护您的 Amazon Cognito 资源因为您不会无意中删除对资源的访问权限

有关支持服务关联的角色的其他服务的信息请参阅与 IAM 配合使用的Amazon服务并查找 Service-Linked Role (服务相关角色) 列为 Yes (是) 的服务选择 Yes 与查看该服务的服务相关角色文档的链接

Amazon Cognito 的服务相关角色权限Amazon Cognito 使用以下服务相关角色

bull 卓越亚马逊代码邮件服务mdash 允许 Amazon Cognito 用户池服务使用您的 Amazon SES 身份发送电子邮件

bull 卓越亚马逊认证编码mdash 允许 Amazon Cognito 用户池为您的亚马逊 Pinpoint 项目发布事件和配置终端节点

AmazonCognitoIdpEmailService 服务相关角色信任以下服务代入该角色

bull emailcognito-idpamazonawscom

角色权限策略允许 Amazon Cognito 对指定资源完成以下操作

Amazon CognidFederation 邮件服务允许的操作

bull 操作sesSendEmail和sesSendRawEmail

bull 资源

此策略拒绝 Amazon Cognito 对指定资源完成以下操作的功能

拒绝的操作

bull 操作sesList

bull 资源

281


凭借这些权限Amazon Cognito 只能使用 Amazon SES 中经验证的电子邮件地址向用户发送电子邮件当用户在客户端应用程序中针对用户池执行特定操作（如注册或重置密码）时Amazon Cognito 将向用户发送电子邮件

您必须配置权限以允许 IAM 实体（例如用户组或角色）创建编辑或删除服务相关角色有关更多信息请参阅 IAM 用户指南中的服务相关角色权限

卓越亚马逊认证编码

AmazonCognitoidp 服务相关角色信任以下服务代入该角色



Amazon Cognito IdP 允许的操作

bull 操作cognito-idpDescribe

bull 资源

有了此权限Amazon Cognito 可以调用Describe为您提供 Amazon Cognito 代币 API 操作Note

当您将 Amazon Cognito 与 Amazon Pinpoint 集成使用createUserPoolClient和updateUserPoolClient资源权限将作为内联策略添加到 SLR 中内联策略将提供mobiletargetingUpdateEndpoint和mobiletargetingPutEvents权限这些权限允许 Amazon Cognito 发布事件并为您与 Cognito 集成的 Pinpoint 项目配置终端节点

为 Amazon Cognito 创建服务相关角色您无需手动创建服务相关角色当您将用户池配置为使用 Amazon SES 配置处理Amazon Web ServicesManagement ConsoleAmazon CLI或 Amazon Cognito API 时Amazon Cognito 会为您创建与服务相关的角色

如果您删除了此服务相关角色然后需要再次创建它则可以使用相同的流程在您的账户中重新创建此角色在配置用户池以使用 Amazon SES 配置处理电子邮件传送时Amazon Cognito 将再次为您创建服务相关角色

在 Amazon Cognito 可以创建此角色之前您用来设置用户池的 IAM 权限必须包含iamCreateServiceLinkedRoleaction 有关更新 IAM 中的权限的更多信息请参阅更改 IAM 用户的权限中的IAM 用户指南

编辑 Amazon Cognito 的服务相关角色Amazon Cognito 不允许您编辑 Amazon Cognito 邮件服务或卓越亚马逊代码邮件服务相关角色在创建服务相关角色后您将无法更改角色的名称因为可能有多种实体引用该角色不过您可以使用 IAM 编辑角色的说明有关更多信息请参阅 IAM 用户指南中的编辑服务相关角色

删除 Amazon Cognito 的服务相关角色如果您不再需要使用某个需要服务相关角色的功能或服务我们建议您删除该角色这样您就没有未被主动监控或维护的未使用实体您必须对使用该角色的每个用户池执行以下任一操作然后才能删除卓越亚马逊代码邮件服务相关角色

bull 删除该用户池bull 更新用户池中的电子邮件设置以使用默认的电子邮件功能默认设置不使用服务相关角色

282

Amazon Cognito 开发人员指南身份验证

请记住应在包含使用此角色的用户池的每个 Amazon 区域中执行这些操作Note

如果在您试图删除资源时 Amazon Cognito 服务正在使用该角色则删除操作可能会失败如果发生这种情况则请等待几分钟后重试

删除 Amazon Cognito 用户池

1 登录到Amazon Web Services Management Console并在以下位置打开 Amazon Cognito 控制台httpsconsoleamazonawscncognito

2 选择 Manage User Pools (管理用户池)3 在 Your User Pools (您的用户池) 页面上选择要删除的用户池4 选择删除池5 在 Delete user pool (删除用户池) 窗口中键入 delete然后选择 Delete pool (删除池)

更新 Amazon Cognito 用户池以使用默认的电子邮件功能


2 选择 Manage User Pools (管理用户池)3 在 Your User Pools (您的用户池) 页面上选择要更新的用户池4 在左侧导航菜单中选择 Message customizations (管理自定义)5 在 Do you want to send emails through your Amazon SES Configuration (是否要通过 Amazon SES 配

置发送电子邮件) 下选择 No - Use Cognito (Default) (否 -使用 Cognito (默认))6 当您完成设置您的电子邮件账户选项时选择 Save changes (保存更改)

使用 IAM 手动删除服务相关角色

使用 IAM 控制台Amazon CLI或Amazon删除亚马逊认知邮件服务或卓越亚马逊注册邮件服务与服务关联的角色的 API有关更多信息请参阅 IAM 用户指南中的删除服务相关角色

Amazon Cognito 服务相关角色支持的区域Amazon Cognito 支持在服务可用的所有区域中使用服务相关角色有关更多信息请参阅 Amazon 区域和终端节点

使用用户池进行身份验证您的应用程序用户可以通过用户池直接登录也可以通过第三方身份提供商 (IdP) 联合登录用户池管理处理以下令牌的开销从通过 FacebookGoogleAmazon 和苹果进行的社交登录返回的令牌以及从OConnect OpenID C (OIDC) 和 SAML IdPs C 返回的令牌

在成功验证身份后Amazon Cognito 会将用户池令牌返回到您的应用程序您可以使用这些令牌向您的用户授予对您自己的服务器端资源或 Amazon API Gateway 的访问权限或者您可以用它们交换Amazon凭证访问其他Amazon服务

您的 Web 和移动应用程序的用户池令牌处理和管理在客户端上是通过 Amazon Cognito 开发工具包提供的同样如果存在有效的（非过期的）刷新令牌适用于 SDK for iOS 的移动开发工具包和 Android 的移动开

283


发工具包会自动刷新您的 ID 令牌和访问令牌而且 ID 令牌和访问令牌至少有 5 分钟的剩余有效性有关开发工具包以及适用于 JavaScriptAndroid 和 iOS 的示例代码请参阅Amazon Cognito 用户池开发工具包

在您的应用程序用户成功登录后Amazon Cognito 会创建会话并返回经过身份验证的用户的 ID 令牌访问令牌和刷新令牌

JavaScript

Amazon Cognito creates a session which includes the id access and refresh tokens of an authenticated user

var authenticationData = Username username Password password var authenticationDetails = new AmazonCognitoIdentityAuthenticationDetails(authenticationData) var poolData = UserPoolId us-east-1_ExaMPle ClientId 1example23456789 var userPool = new AmazonCognitoIdentityCognitoUserPool(poolData) var userData = Username username Pool userPool var cognitoUser = new AmazonCognitoIdentityCognitoUser(userData) cognitoUserauthenticateUser(authenticationDetails onSuccess function (result) var accessToken = resultgetAccessToken()getJwtToken()

Use the idToken for Logins Map when Federating User Pools with identity pools or when passing through an Authorization Header to an API Gateway Authorizer var idToken = resultidTokenjwtToken

onFailure function(err) alert(err)

)

Android

Session is an object of the type CognitoUserSession and includes the id access and refresh tokens for a user

String idToken = sessiongetIdToken()getJWTToken()String accessToken = sessiongetAccessToken()getJWT()

iOS - Swift

AWSCognitoIdentityUserSession includes id access and refresh tokens for a user

- (AWSTaskltAWSCognitoIdentityUserSession gt )getSession

iOS - Objective-C

AWSCognitoIdentityUserSession includes the id access and refresh tokens for a user

284


[[user getSessionusername passwordpassword validationDatanil scopesnil] continueWithSuccessBlockîd _Nullable(AWSTaskltAWSCognitoIdentityUserSession gt _Nonnull task) success taskresult has user session return nil]

主题bull User池身份验证流程 (p 285)

User池身份验证流程除密码外现代身份验证流程还包含新的质询类型来验证用户身份我们将身份验证归纳为两个通用步骤这两个步骤通过两个 API 操作实现InitiateAuth 和 RespondToAuthChallenge

用户通过回答连续的质询进行身份验证直到身份验证失败或用户获得令牌通过这两个可以重复执行以包含不同质询的步骤我们可以支持任何自定义身份验证流程

您可以使用 Amazon Lambda 触发器自定义身份验证流程作为身份验证流程的一部分这些触发器将发布并验证自己的质询

您还可以在安全后端服务器上对用户使用管理员身份验证流您可以使用用户迁移身份验证流来允许用户迁移而无需用户重置其密码

Note

我们允许五次失败的登录尝试之后我们开始临时锁定其锁定时间从 1 秒开始呈指数增长每次失败尝试后成倍增加最长约为 15 分钟暂时锁定期间的尝试将被忽略在临时锁定期之后如果下一次尝试失败则新的临时锁定开始时间是最后一次的两倍等待大约 15 分钟而不进行任何尝试也会重置临时锁定请注意这种行为可能会发生变化

主题bull 客户端身份验证流程 (p 286)bull 服务器端身份验证流程 (p 286)bull 自定义身份验证流程 (p 286)bull 内置身份验证流程和质询 (p 287)

285


bull 自定义身份验证流程和质询 (p 287)bull 在自定义身份验证流程中使用 SRP 密码验证 (p 287)bull 管理员身份验证流程 (p 288)bull 用户迁移身份验证流程 (p 288)


以下是用户池身份验证对使用Amazon Mobile SDK for AndroidAmazon Mobile SDK for iOS或适用于JavaScript 的 Amazon 软件开发工具包创建的最终用户客户端应用程序的工作方式

1 用户将他们的用户名和密码输入到应用程序中2 应用程序使用用户的用户名和 SRP 详细信息调用 InitiateAuth 操作

该方法返回身份验证参数

Note

应用程序通过使用 AndroidiOS 和 JavaScript 开发工具包中支持的 Amazon Cognito SRP 来生成 SRP 详细信息

3 应用程序调用 RespondToAuthChallenge 操作如果调用成功则返回用户的令牌并且身份验证流程完成

如果需要另一个质询则不返回令牌相反对 RespondToAuthChallenge 的调用会返回一个会话4 如果 RespondToAuthChallenge 返回一个会话应用程序将再次调用 RespondToAuthChallenge

这次使用会话和质询响应（例如MFA 代码）

服务器端身份验证流程

如果您没有最终用户应用程序而是使用 JavaRuby 或 Nodejs 安全后端或服务器端应用程序则可以对Amazon Cognito 用户池使用经过身份验证的服务器端 API

对于服务器端应用程序用户池身份验证与客户端应用程序的身份验证类似但以下情况除外

bull 服务器端应用程序调用 AdminInitiateAuth API 操作（而不是 InitiateAuth）此操作需要Amazon 管理员凭证此操作返回身份验证参数

bull 具有身份验证参数后应用程序会调用 AdminRespondToAuthChallenge API 操作（而不是RespondToAuthChallenge）这也需要 Amazon 管理员凭证

AdminInitiateAuth 和 AdminRespondToAuthChallenge 操作不能接受用于管理员登录的用户名和密码用户凭证除非您通过执行以下操作之一明确启用它们

bull 在服务器端应用程序对 CreateUserPoolClient 或 UpdateUserPoolClient 的调用中为ExplicitAuthFlow 参数传递 ADMIN_USER_PASSWORD_AUTH（以前称为 ADMIN_NO_SRP_AUTH）

bull 选择Enable sign-in API for server-based authentication(ADMIN_USER_PASSWORD_AUTH)中的应用程序客户端中的选项卡创建用户池有关更多信息请参阅配置用户池应用程序客户端 (p 164)


Amazon Cognito 用户池还支持自定义身份验证流程这可以帮助您使用Amazon Lambda触发器

自定义身份验证流程旨在允许一系列可自定义以满足不同需求的质询和响应周期流程开始调用InitiateAuthAPI 操作该 API 指示将使用的身份验证类型并提供所有初始身份验证参数AmazonCognito 将回复InitiateAuth使用以下操作之一调用

286


bull 用户质询及会话和参数bull 错误（如果用户未能通过身份验证）bull ID访问和刷新令牌（如果 InitiateAuth 调用中提供的参数足以使用户登录）（通常需要首先回答

质询但这由您的自定义代码决定）

如果 Amazon Cognito 响应InitiateAuth调用时应用程序会收集更多输入并调用RespondToAuthChallenge操作提供质询响应并传回会话Amazon Cognito 响应RespondToAuthChallenge调用类似于InitiateAuth调用提供令牌 (如果用户已登录)另一质询或错误如果返回另一质询则序列以应用程序调用RespondToAuthChallenge直到用户登录或返回错误API 文档中提供了有关 InitiateAuth 和 RespondToAuthChallenge API 操作的更多详细信息

内置身份验证流程和质询Amazon Cognito 有一些内置AuthFlow和ChallengeName值以通过安全远程密码 (SRP) 协议验证用户名和密码此流程内置在适用于 Amazon Cognito 的 iOSAndroid 和 JavaScript 开发工具包中概括来说流程通过发送USER_SRP_AUTH作为AuthFlow到InitiateAuth随着USERNAME和SRP_A中的值AuthParameters如果 InitiateAuth 调用成功则响应将在质询参数中包括 PASSWORD_VERIFIER 作为 ChallengeName 和 SRP_B然后应用程序将使用 ChallengeResponses 中的 PASSWORD_VERIFIER ChallengeName 和必要参数调用RespondToAuthChallenge如果 RespondToAuthChallenge 调用成功并且用户已登录则将返回令牌如果针对用户启用了 Multi-Factor Authentication (MFA)则会返回 SMS_MFA 的 ChallengeName并且应用程序会通过再一次调用 RespondToAuthChallenge 提供必要代码

自定义身份验证流程和质询应用可以启动自定义身份验证流程具体方法是InitiateAuth替换为CUSTOM_AUTH作为Authflow借助自定义身份验证流程可通过三个 Amazon Lambda 触发器控制响应的质询和验证

bull 这些区域有DefineAuthChallengeLambda 触发器将以前的质询和响应的会话数组作为输入然后它输出下一个质询名称和布尔值指示用户是否通过身份验证（并且应被授予令牌）此 Lambda 触发器是一个状态机可通过质询控制用户的路径

bull 这些区域有CreateAuthChallengeLambda 触发器将质询名称作为输入并生成质询和参数以评估响应CreateAuthChallenge被调用DefineAuthChallenge返回CUSTOM_CHALLENGE作为下一质询并且在质询元数据参数中传递下一质询类型

bull 这些区域有VerifyAuthChallengeResponseLambda 函数会评估响应并返回布尔值以表明响应是否有效

自定义身份验证流程还可以使用内置质询的组合例如 SRP 密码验证和通过短信进行的 MFA它可以使用自定义质询如验证码或秘密问题

在自定义身份验证流程中使用 SRP 密码验证如果您希望将 SRP 包含在自定义身份验证流程中则您需要开始使用它

bull 要在自定义流程中启动 SRP 密码验证应用程序将 CUSTOM_AUTH 作为 Authflow 来调用InitiateAuth它包括在 AuthParameters 映射 SRP_A（SRP A 值）和 CHALLENGE_NAMESRP_A 中

bull 这些区域有DefineAuthChallengeLambda 触发器以初始会话调用challengeNameSRP_A和challengeResult true并且应该使用challengeNamePASSWORD_VERIFIERissueTokens false 和failAuthentication false

bull 接下来该应用程序需要使用 challengeName PASSWORD_VERIFIER 和 challengeResponses 映射中 SRP 所需的其他参数调用 RespondToAuthChallenge

bull 如果密码已验证DefineAuthChallengeLambda 触发器以第二个会话调用challengeNamePASSWORD_VERIFIER和challengeResult true在这一点上DefineAuthChallengeLambda触发器可以响应challengeName CUSTOM_CHALLENGE启动自定义质询

287


bull 如果为用户启用了 MFA则会在验证密码后自动处理 MFA

Note


有关 Lambda 触发器的更多信息包括示例代码请参阅使用 Lambda 触发器自定义用户池工作流 (p 63)

Note


管理员身份验证流程

描述自定义身份验证流程 (p 286) 并使用 SRP 进行密码验证的 API 操作是推荐的身份验证方法iOSAndroid 和 JavaScript 开发工具包均基于上述方法让使用 SRP 变得很轻松但是如果您希望避免 SRP 计算还可以使用另一组专为在安全后端服务器上使用而设计的管理员 API 操作对于这些后端管理员实施AdminInitiateAuth 用于替代 InitiateAuth并且 AdminRespondToAuthChallenge用于替代 RespondToAuthChallenge在使用这些操作时密码能够以明文形式提交因此无需进行SRP 计算示例如下

AdminInitiateAuth Request AuthFlowADMIN_USER_PASSWORD_AUTH AuthParameters USERNAMEltusernamegt PASSWORDltpasswordgt ClientIdltclientIdgt UserPoolIdltuserPoolIdgt

这些管理员身份验证操作要求提供开发人员凭证并使用 Amazon 签名版本 4 (SigV4) 签名过程这些操作在标准Amazon开发工具包（包包包包）便于在 Lambda 函数中使用Nodejs 为了使用这些操作并让它们接受明文密码您必须在控制台中为应用程序启用这些操作或者您可以在调用 CreateUserPoolClient 或 UpdateUserPoolClient 时为 ExplicitAuthFlow 参数传递ADMIN_USER_PASSWORD_AUTH对于 InitiateAuth 和 RespondToAuthChallenge 操作系统不接受 ADMIN_USER_PASSWORD_AUTH AuthFlow

在 AdminInitiateAuth 响应 ChallengeParameters 中USER_ID_FOR_SRP 属性（如果显示）将包含用户的实际用户名而不是别名（如电子邮件地址或电话号码）在 AdminRespondToAuthChallenge调用的 ChallengeResponses 中您必须在 USERNAME 参数中传递此用户名

Note

管理员身份验证流程专为后端管理员实施而设计因此不支持设备跟踪如果启用了设备跟踪管理员身份验证成功但任何对刷新访问令牌的调用均会失败

用户迁移身份验证流程

可使用用户迁移 Lambda 触发器轻松地将用户从传统用户管理系统迁移到您的用户池要避免让用户在用户迁移过程中重置密码请选择 USER_PASSWORD_AUTH 身份验证流程此流程在身份验证期间通过加密的SSL 连接向服务发送用户的密码

所有用户均完成迁移后我们建议您切换为更安全的 SRP 流程SRP 流程不通过网络发送任何密码

要了解有关 Lambda 触发器的更多信息请参阅使用 Lambda 触发器自定义用户池工作流 (p 63)

有关使用 Lambda 触发器迁移用户的详细信息请参阅利用用户迁移 Lambda 触发器将用户导入用户池 (p 124)

288

Amazon Cognito 开发人员指南日志记录和监控

Amazon Cognito 中的日志记录和监控监控是保持 Amazon Cognito 和您的其他Amazon解决方案Amazon Cognito 目前支持以下两个Amazon服务以便您可以监控组织和组织内部的活动

bull Amazon CloudTrailndash借助 CloudTrail您可以捕获来自 Amazon Cognito 控制台和来自对 Amazon CognitoAPI 操作的代码调用的 API 调用例如在用户进行身份验证时CloudTrail 可以记录请求中的 IP 地址何人发出的请求以及发出请求的时间等详细信息

bull Amazon CloudWatch 指标 mdash利用 CloudWatch 指标您可以几乎实时地监控和报告并在发生事件时采取自动措施例如您可以基于提供的指标创建 CloudWatch 控制面板来监控 Amazon Cognito 用户池也可以基于提供的指标创建 CloudWatch 警报以便在超过设定的阈值时通知您

bull Amazon CloudWatch Logs Insights-通过 CCloudWatch Logs 见解您可以配置 CloudTrail 以将事件发送到 CloudWatch 以监控 Amazon Cognito CloudTrail 日志文件

主题bull 跟踪 CloudWatch 和 Service Quotas 中的配额和使用情况 (p 289)bull Amazon Cognito 用户池指标 (p 289)bull Amazon Cognito 用户池的尺寸 (p 294)bull 使用 Service Quotas 控制台跟踪指标 (p 294)bull 使用 CloudWatch 控制台跟踪指标 (p 295)bull 为配额创建 CloudWatch 警报 (p 295)bull 使用记录 Amazon Cognito API 调用Amazon CloudTrail (p 295)bull 使用 Amazon CloudTrail Watch Logs Insights 分析 Amazon Cognito 事件 (p 297)

跟踪 CloudWatch 和 Service Quotas 中的配额和使用情况您可以使用亚马逊 CloudWatch 或使用 Service Quotas 监控 Amazon Cognito 用户池CloudWatch 收集原始数据并将数据处理为便于读取的近乎实时的指标在 CloudWatch 中您可以设置用于监测特定阈值的警报并在达到相应阈值时发送通知或执行操作要为服务配额创建 CloudWatch 警报请参阅创建CloudWatch 警报Amazon Cognito 指标每隔五分钟提供一次有关 CloudWatch 中的保留期的更多信息请访问Amazon CloudWatch 常见问题页面

您可以使用 Service Quotas 查看和管理您的 Amazon Cognito 用户池配额使用情况Service Quotas 控制台具有三个功能查看服务配额请求提高服务配额以及查看当前利用率您可以使用第一个功能来查看配额并查看配额是否可调节您可以使用第二个功能请求增加 Service Quotas您可以使用最后一个功能查看配额利用率此功能仅在您的帐户已激活一段时间后才可用有关在 Service Quotas 控制台中查看配额的更多信息请参阅查看 Service Quotas

Note

每 5 分钟提供一次 Amazon Cognito 指标有关 CloudWatch 中的保留期的更多信息请访问Amazon CloudWatch 常见问题页面

Amazon Cognito 用户池指标下表列出了 Amazon Cognito 用户池的可用指标

Note

控制台中不会显示在过去两周内没有任何新数据点的指标当您在搜索框中输入其指标名称或维度名称时它们也不会显示在所有指标选项卡此外它们不会在列表指标命令的结果中返回

289

Amazon Cognito 开发人员指南Amazon Cognito 用户池指标

检索这些指标的最佳方法是使用get-metric-data或者get-metric-statistics中的命令AmazonCLI

指标描述

SignUpSuccesses 提供向 Amazon Cognito 用户池发出的成功的用户注册请求的总数一个成功的用户注册请求会产生值 1而一个不成功的请求会产生值 0受限制的请求也会被视为不成功的请求因此一个受限制的请求也将产生计数 0

要查找成功的用户注册请求的百分比请对此指标使用 Average 统计数据要计算用户注册请求的总数请对此指标使用 Sample Count 统计数据要计算成功的用户注册请求的总数请对此指标使用 Sum 统计数据要计算失败的用户注册请求的总数请使用 CloudWatchMath表达式并减去Sum中的统计数据Sample Count统计数据

针对每个用户池客户端的每个用户池发布此度量如果用户注册由管理员执行则以下情况将指标与用户池客户端一起发布Admin

请注意不会针对用户导入和用户移案例发出此指标

指标维度UserPoolUserPoolClient

单位计数

SignUpThrottles 提供向 Amazon Cognito 用户池发出的受限的用户注册请求的总数当用户注册请求受到限制时将发布计数 1

要计算受限制的用户注册请求的总数请对此指标使用 Sum 统计数据

针对每个客户端的每个用户池发布此度量如果受限的请求由管理员发出则以用户池客户端身份将指标与用户池客户端一起发布Admin


单位计数

SignInSuccesses 提供向 Amazon Cognito 用户池发出的成功的用户身份验证请求的总数在向用户颁发身份验证令牌时用户身份验证将被视为成功一个成功的身份验证会产生值 1而一个不成功的请求会产生值 0受限制的请求也会被视为不成功的请求因此一个受限制的请求也将产生计数 0

要查找成功的用户身份验证请求的百分比请对此指标使用 Average 统计数据要计算用户身份验证请求的总数请对此指标使用 Sample Count 统计数据要计算成功的用户身份验证请求的总数请对此指标使用 Sum 统计数据要计算失败的用户身份验证请求的总数请使用 CloudWatchMath表达

290


指标描述式并减去Sum中的统计数据Sample Count统计数据

针对每个客户端的每个用户池发布此度量如果随请求提供了无效的用户池客户端则指标中的相应用户池客户端值将包含固定值Invalid而不是请求中发送的实际无效值

请注意此指标中不包含刷新 Amazon Cognito 令牌的请求有一个用于提供的单独指标Refresh令牌统计数据


单位计数

SignInThrottles 提供向 Amazon Cognito 用户池发出的受限的用户身份验证请求的总数当身份验证请求受到限制时将发布计数 1

要计算受限制的用户身份验证请求的总数请对此指标使用 Sum 统计数据


此指标中不包含刷新 Amazon Cognito 令牌的请求有一个用于提供的单独指标Refresh令牌统计数据


单位计数

291


指标描述

TokenRefreshSuccesses 提供向 Amazon Cognito 用户池发出的成功的Amazon Cognito 令牌刷新请求的总数一个成功的Amazon Cognito 令牌刷新请求会产生值 1而一个不成功的请求会产生值 0受限制的请求也会被视为不成功的请求因此一个受限制的请求也将产生计数 0

要查找成功的 Amazon Cognito 令牌刷新请求的百分比请使用Average此指标的统计数据要计算刷新 Amazon Cognito 令牌的请求总数请对此使用Sample Count此指标的统计数据要计算成功的 Amazon Cognito 令牌刷新请求的总数请对此使用Sum此指标的统计数据要计算失败的 AmazonCognito 令牌刷新请求的总数请对 CloudWatch使用Math表达式并减去Sum中的统计数据SampleCount统计数据

按每个用户池客户端的每个指标发布如果请求中有无效的用户池客户端则用户池客户端值包含固定值Invalid


单位计数

TokenRefreshThrottles 提供向 Amazon Cognito 用户池发出的受限制的Amazon Cognito 令牌刷新请求的总数当 AmazonCognito 令牌刷新请求受到限制时将发布计数 1

要计算受限制的 Amazon Cognito 令牌刷新请求的总数请对此使用Sum此指标的统计数据



单位计数

292


指标描述

FederationSuccesses 提供向 Amazon Cognito 用户池发出的成功的联合身份验证请求的总数一个成功的联合身份验证请求会产生值 1而一个不成功的请求会产生值 0受限制的请求也会被视为不成功的请求因此一个受限制的请求也将产生计数 0

要查找成功的联合身份验证请求的百分比请对此指标使用 Average 统计数据要计算联合身份验证请求的总数请对此指标使用 Sample Count 统计数据要计算成功的联合身份验证请求的总数请对此指标使用 Sum 统计数据要计算失败的联合身份验证请求的总数请使用 CloudWatchMath表达式并减去Sum中的统计数据Sample Count统计数据

指标维度UserPoolUserPoolClientIdentityProvider

单位计数

FederationThrottles 提供向 Amazon Cognito 用户池发出的受限制的联合身份验证请求的总数当联合身份验证请求受到限制时将发布计数 1

要计算受限制的联合身份验证请求的总数请对此指标使用 Sum 统计数据


单位计数

CallCount 提供客户发出的与类别相关的呼叫总数此衡量指标包括所有呼叫如受限调用失败的呼叫和成功的呼叫

此指标可在用量 nameSpace

类别配额是针对每个Amazon帐户中的所有用户池和区域中的所有用户池

您可以使用Sum此指标的统计数据

指标维度服务类型资源类

单位计数

293

Amazon Cognito 开发人员指南Amazon Cognito 用户池的尺寸

指标描述

ThrottleCount 提供与某个类别相关的受限制的呼叫的总数


此指标在帐户级别发布

您可以计算类别中的呼叫总数使用Sum此指标的统计数据


单位计数

Amazon Cognito 用户池的尺寸以下维度用于优化由 Amazon Cognito 发布的用量指标维度仅适用于CallCount和ThrottleCount 指标

维度描述

服务包含该资源的 Amazon 服务的名称对于 AmazonCognito 用量指标此维度的值为Cognito userpool

类型正在报告的实体的类型Amazon Cognito 用量指标的唯一有效值为 API

资源正在运行的资源的类型唯一有效值为类别名称

类所跟踪的资源的类Amazon Cognito 不使用类别维度

使用 Service Quotas 控制台跟踪指标Amazon Cognito 用户池与 Service Quotas 集成后者是一项服务可让您从中心位置查看和管理您的配额您可以使用 ldquoService Quotasrdquo 控制台查看有关特定配额的详细信息监控配额使用情况请求增加配额以及创建 CloudWatch 警报来跟踪您的配额使用情况

要查看 Amazon Cognito 用户池服务配额利用率请完成以下步骤

1 打开服务配额控制台2 在导航窗格中选择 Amazon 服务3 从Amazon服务列表中在搜索字段中输入 Amazon Cognito 用户池此时将显示服务配额页面4 向下滚动到监控5 In监控您可以在图表中查看当前服务配额利用率6 In监控选择一小时三小时十二小时一天三天或一周7 选择图表中的任意区域以查看服务配额利用率百分比在此处您可以将图形添加到仪表板或使用操

作菜单选择在指标中查看此工具将带您访问 CloudWatch 控制台中的相关指标

294

Amazon Cognito 开发人员指南使用 CloudWatch 控制台跟踪指标

使用 CloudWatch 控制台跟踪指标您可以使用 CloudWatch 跟踪和收集 Amazon Cognito 用户池指标云监视仪表板将显示有关每个Amazon您使用的服务您可以使用 CloudWatch 来创建指标警报可以将警报设置为向您发送通知或更改您正在监视的特定资源要在 CloudWatch 中查看服务配额指标请完成以下步骤

1 打开CloudWatch 控制台2 在导航窗格中选择指标3 In所有指标选择一个量度和一个维度4 选中指标旁边的复选框指标将显示在图表中

Note

控制台中不会显示在过去两周内没有任何新数据点的指标当您在控制台的 All 指标选项卡的搜索框中输入指标名称或维度名称时它们也不会显示并且 List-metrics 命令的结果中不会返回它们检索这些指标的最佳方法是使用get-metric-data或者get-metric-statistics中的命令AmazonCLI

为配额创建 CloudWatch 警报Amazon Cognito 提供了 CloudWatch 使用量指标 AWS 这些指标与CallCount和ThrottleCountAPI在 Service Quotas 控制台中您可以创建警报以在用量接近服务配额时向您发出警报使用以下步骤使用Service Quotas 控制台设置 CloudWatch 警报

1 打开服务配额 httpsdocsawsamazoncomservicequotaslatestuserguide 控制台2 在导航窗格中选择 Amazon 服务3 SelectAmazon Cognito 用户池4 选择要在其中设置警报的配额5 向下滚动到CloudWatch 警报6 InCloudWatch 警报中选择Create7 In警报阈值下选择一个阈值8 适用于警报名称中输入一个唯一名称9 选择创建

使用记录 Amazon Cognito API 调用Amazon CloudTrailAmazon Cognito 与Amazon CloudTrail提供用户角色或AmazonAmazon Cognito 中的服务CloudTrail将对 Amazon Cognito 的 API 调用子集作为事件捕获包括来自 Amazon Cognito 控制台的调用和对Amazon Cognito API 操作的代码调用如果您创建跟踪则可以使 CloudTrail 事件持续传送到 AmazonS3 存储桶（包括 Amazon Cognito 的事件）如果您不配置跟踪则仍可在 CloudTrail 控制台中的 Eventhistory (事件历史记录) 中查看最新事件使用 CloudTrail 收集的信息您可以确定向 Amazon Cognito 发出了什么请求发出请求的 IP 地址何人发出的请求请求的发出时间以及其他详细信息

要了解有关 CloudTrail 的更多信息（包括如何对其进行配置和启用）请参阅《Amazon CloudTrail 用户指南》

您还可以针对特定 CloudTrail 事件创建 Amazon CloudWatch 警报例如您可以设置 CloudWatch以在身份池配置发生更改时触发警报有关更多信息请参阅为 CloudTrail 事件创建云监视警报示例

295

Amazon Cognito 开发人员指南使用记录 Amazon Cognito API 调用Amazon CloudTrail

CloudTrail 中的 Amazon Cognito 信息在您创建 Amazon 账户时将在该账户上启用 CloudTrail当 Amazon Cognito 中发生受支持的事件活动时该活动将记录在 CloudTrail 事件中并与其他Amazon中的服务事件事件历史记录您可以在 Amazon账户中查看搜索和下载最新事件有关更多信息请参阅使用 CloudTrail 事件历史记录查看事件

要持续记录您的事件Amazon账户（包括 Amazon Cognito 的活动）请创建跟踪通过跟踪CloudTrail可将日志文件传送至 Amazon S3 存储桶默认情况下在控制台中创建跟踪时此跟踪应用于所有区域此跟踪记录来自 Amazon 分区中的所有区域的事件并将日志文件传送至您指定的 Amazon S3 存储桶此外您可以配置其他 Amazon 服务进一步分析在 CloudTrail 日志中收集的事件数据并采取行动有关更多信息请参阅

bull 创建跟踪概述bull CloudTrail 支持的服务和集成bull 为 CloudTrail 配置 Amazon SNS 通知bull 从多个区域接收 CloudTrail 日志文件和从多个账户接收 CloudTrail 日志文件

Amazon Cognito User Pools

Amazon Cognito 支持对所有操作进行记录具体记录在用户池操作页面中的事件作为 CloudTrail 日志文件中的事件Amazon Cognito 记录UserSub但不是UserName在 CloudTrail 日志中查看特定于用户的请求你可以找到一个给定的UserSub通过调用ListUsersAPI并使用子的过滤器

Note

CloudTrail 中当前不包含托管的 UI 和联合身份调用


bull CreateIdentityPoolbull DeleteIdentityPoolbull DescribeIdentityPoolbull GetIdentityPoolRolesbull ListIdentityPoolsbull SetIdentityPoolRolesbull UpdateIdentityPool


Amazon Cognito 支持对所有操作进行记录具体记录在Amazon Cognito Sync 操作页面中的事件作为CloudTrail 日志文件中的事件

每个事件或日志条目都包含有关生成请求的人员信息身份信息可帮助您确定以下内容

bull 请求是使用根用户凭证还是 IAM 用户凭证发出的bull 请求是使用角色还是联合身份用户的临时安全凭证发出的bull 请求是否由其他 Amazon 服务发出

有关更多信息请参阅 CloudTrail userIdentity 元素

例如Amazon Cognito 日志文件条目跟踪是一种配置可用于将事件作为日志文件传送到您指定的 Amazon S3 存储桶CloudTrail 日志文件包含一个或多个日志条目一个事件表示来自任何源的一个请求包括有关请求的操作操作的日期和时间请

296

Amazon Cognito 开发人员指南使用 Amazon CloudTrail Watch LogsInsights 分析 Amazon Cognito 事件

求参数等方面的信息CloudTrail 日志文件不是公用 API 调用的有序堆栈跟踪因此它们不会按任何特定顺序显示

以下示例是为进行 CreateIdentityPool 操作而发出的请求的日志条目该请求由名为 Alice 的 IAM 用户发出

eventVersion103 userIdentity typeIAMUser principalIdPRINCIPAL_ID arnarnawsiam123456789012userAlice accountId123456789012 accessKeyId[EXAMPLE_KEY_ID] userNameAlice eventTime2016-01-07T020430Z eventSourcecognito-identityamazonawscom eventNameCreateIdentityPool awsRegionus-east-1 sourceIPAddress127001 userAgentUSER_AGENT requestParameters identityPoolNameTestPool allowUnauthenticatedIdentitiestrue supportedLoginProviders graphfacebookcom000000000000000 responseElements identityPoolNameTestPool identityPoolIdus-east-11cf667a2-49a6-454b-9e45-23199EXAMPLE allowUnauthenticatedIdentitiestrue supportedLoginProviders graphfacebookcom000000000000000 requestID15cc73a1-0780-460c-91e8-e12ef034e116 eventIDf1d47f93-c708-495b-bff1-cb935a6064b2 eventTypeAwsApiCall recipientAccountId123456789012

使用 Amazon CloudTrail Watch Logs Insights 分析Amazon Cognito 事件Amazon CloudWatch Logs Insights 让您能够交互地搜索和分析您的 Amazon Cognito CloudTrail 事件数据在配置您的跟踪以将事件发送到 CloudWatch Logs 时CloudTrail 只发送符合您的跟踪设置的事件

要查询或研究您的 Amazon Cognito CloudTrail 事件请在 CloudTrail 控制台中确保您选择管理事件选项以便您可以监控在您的Amazon资源的费用您还可选择见解事件选项当您想要识别帐户中的错误异常活动或异常用户行为时

Amazon Cognito 查询示例您可以在 Amazon CloudWatch 控制台中使用以下查询

常规查询

查找 25 个最近添加的日志事件

297

Amazon Cognito 开发人员指南合规性验证

fields timestamp message | sort timestamp desc | limit 25| filter eventSource = cognito-idpamazonawscom

获取 25 个包含异常的最近添加的日志事件列表

fields timestamp message | sort timestamp desc | limit 25| filter eventSource = cognito-idpamazonawscom and message like Exception

异常和错误查询

查找 25 个带有错误代码的最近添加的日志事件NotAuthorizedException以及 Amazon Cognito 用户池sub

fields timestamp additionalEventDatasub as user | sort timestamp desc | limit 25| filter eventSource = cognito-idpamazonawscom and errorCode= NotAuthorizedException

使用查找记录数sourceIPAddress和相应的eventName

filter eventSource = cognito-idpamazonawscom| stats count() by sourceIPAddress eventName

查找触发NotAuthorizedException错误

filter eventSource = cognito-idpamazonawscom and errorCode= NotAuthorizedException| stats count() as count by sourceIPAddress eventName| sort count desc | limit 25

找到前 25 个 IP 地址称为ForgotPasswordAPI

filter eventSource = cognito-idpamazonawscom and eventName = ForgotPassword| stats count() as count by sourceIPAddress| sort count desc | limit 25

Amazon Cognito 的合规性验证作为多个组成部分第三方审计员将评估 Amazon Cognito 的安全性和合规性Amazon合规性计划其中包括 SOCPCIFedRAMPHIPAA 及其他

有关特定合规性计划范围内的 Amazon 服务列表请参阅合规性计划范围内的 Amazon 服务有关常规信息请参阅Amazon 合规性计划

您可以使用 Amazon Artifact 下载第三方审计报告有关更多信息请参阅下载 Amazon Artifact 中的报告

您在使用 Amazon Cognito 时的合规性责任由您的数据的敏感性您公司的合规性目标以及适用的法律法规决定Amazon提供以下资源来帮助实现合规性

bull 安全性与合规性 Quick Start 指南安全性与合规性 Quick Start 指南 - 这些部署指南讨论了架构注意事项并提供了在Amazon上部署基于安全性和合规性的基准环境的步骤

bull 《设计符合 HIPAA 安全性和合规性要求的架构》白皮书 mdash 此白皮书介绍了公司如何使用Amazon创建符合 HIPAA 标准的应用程序

bull Amazon合规性资源 mdash 这一系列的操作手册和指南可能适用于您所在的行业和地区bull 使用规则评估资源中的 Amazon Config 开发人员指南ndashAmazon Config评估您的资源配置对内部实践

行业指南和法规的遵循情况

298

Amazon Cognito 开发人员指南故障恢复能力

bull Amazon Security Hub mdash 此Amazon服务提供了Amazon中安全状态的全面视图可帮助您检查是否符合安全行业标准和最佳实践

Amazon Cognito 中的恢复能力Amazon 全球基础设施围绕 Amazon 区域和可用区构建区域提供多个在物理上独立且隔离的可用区这些可用区通过延迟低吞吐量高且冗余性高的网络连接在一起利用可用区您可以设计和操作在可用区之间无中断地自动实现故障转移的应用程序和数据库与传统的单个或多个数据中心基础设施相比可用区具有更高的可用性容错性和可扩展性

有关 Amazon 区域和可用区的更多信息请参阅 Amazon 全球基础设施

主题bull 区域数据注意事项 (p 299)

区域数据注意事项Amazon Cognito 用户池每个用户池都在一个Amazon区域并且他们仅将用户配置文件数据存储在该区域中用户池可以将用户数据发送到其他Amazon区域具体取决于可选功能的配置方式

bull 如果默认 no-replyverificationemailcom 电子邮件地址设置用于通过 Amazon Cognito 用户池路由电子邮件地址验证则电子邮件将通过美国西部 (俄勒冈) 区域路由

bull 如果其他电子邮件地址用于向 Amazon Cognito 用户池配置 Amazon 简单电子邮件服务 (Amazon SES)则该电子邮件地址将通过Amazon与 Amazon SES 中的电子邮件地址关联的区域

bull 来自 Amazon Cognito 用户池的 SMS 消息通过同一地区 Amazon SNS 路由除非配置电子邮件或电话验证

bull 如果 Amazon Pinpoint 分析用于 Amazon Cognito 用户池则事件数据将路由到美国东部（弗吉尼亚北部）区域

Note

Amazon Pinpoint 可在多个中使用Amazon北美欧洲亚洲和大洋洲的区域Amazon Pinpoint区域包括 Amazon Pinpoint API如果 Amazon Cognito 支持亚马逊 Pinpoint 地区那么 AmazonCognito 会将事件发送到相同Amazon Pinpoint 地区如果一个区域不是由 Amazon Pinpoint 支持那么 Amazon Cognito 将仅限支持在 us-east-1 中发送事件有关 Amazon Pinpoint 详细地区信息请参阅Amazon Federation 终端节点和配额和将 Amazon Pinpoint 分析与 Amazon Cognito 用户池结合使用

Amazon Cognito 中的基础设施安全性作为一项托管服务Amazon Cognito 受到Amazon全局网络安全过程请参阅Amazon Web Services安全过程概述白皮书

您可以使用Amazon发布的 API 调用通过网络访问 Amazon Cognito客户端必须支持传输层安全性 (TLS)10 或更高版本建议使用 TLS 12 或更高版本客户端还必须支持具有完全向前保密 (PFS) 的密码套件例如 Ephemeral Diffie-Hellman (DHE) 或 Elliptic Curve Ephemeral Diffie-Hellman (ECDHE)大多数现代系统（如 Java 7 及更高版本）都支持这些模式

此外必须使用访问密钥 ID 和与 IAM 委托人关联的秘密访问密钥来对请求进行签名或者您可以使用Amazon Security Token Service (Amazon STS) 生成临时安全凭证来对请求进行签名

299

Amazon Cognito 开发人员指南配置和漏洞分析

Amazon Cognito 用户池中的配置和漏洞分析Amazon 负责处理来宾操作系统 (OS) 和数据库补丁防火墙配置和灾难恢复等基本安全任务这些流程已经过适当的第三方审核和认证有关更多详细信息请参阅以下资源

bull Amazon Cognito 的合规性验证 (p 298)bull 责任共担模式

Amazon Cognito 用户池的安全最佳实践可以向用户池添加多重验证 (MFA) 以保护用户的身份MFA 增加了另一种不单靠用户名和密码的身份验证方法可以选择使用短信或基于时间的一次性 (TOTP) 密码作为用户登录的第二安全要素也可以使用自适应身份验证其基于风险的模型可预测您可能何时需要另一身份验证要素它是用户池高级安全功能（还包括针对遭盗用凭证的保护）的一部分

主题bull 向用户池添加多重验证 (MFA) (p 300)bull 向用户池添加高级安全 (p 303)

向用户池添加多重验证 (MFA)多重身份验证 (MFA) 通过增加另一种身份验证方法而不是单靠用户名和密码来提高应用程序的安全性可以选择使用短信或基于时间的一次性 (TOTP) 密码作为用户登录的第二安全要素

借助自适应身份验证可以将用户池配置为响应增加的风险级别需要第二安全要素身份验证要向用户池添加自适应身份验证请参阅向用户池添加高级安全 (p 303)

当多重身份验证 (MFA) 设置为required则所有用户都必须完成 MFA 才能登录每个用户至少需要一个MFA 因素（例如 SMS 或 TOTP 设置）才能登录为了避免阻止用户登录 MFArequired则必须在用户加入中包含 MFA 设置

如果您启用 SMS 作为 MFA 因素您可以要求电话号码并在注册过程中进行验证如果您将 MFA 设置为required并且只支持 SMS 作为一个因素大多数用户将需要有一个电话号码没有电话号码的用户需要您的支持才能将电话号码添加到其个人资料中然后才能登录您可以将未经验证的电话号码用于 SMSMFA在多重身份验证成功后这些号码将具有已验证的状态

在初始登录过程中为 TOTP 令牌设置用户池中的用户启用或禁用 TOTP 作为用户池的 MFA 因子的设置控制用户是否可以为自己设置 TOTP如果您的用户已设置 TOTP他们可以将其用于 MFA即使稍后为用户池禁用了 TOTP

主题bull Prerequisites (p 300)bull 配置多重验证 (p 301)bull SMS 文本消息 MFA (p 301)bull TOTP 软件令牌 MFA (p 302)


300

Amazon Cognito 开发人员指南添加多重验证 (MFA)

bull 您只能选择 MFA 作为必需在 Amazon Cognito 用户池控制台中当您最初创建用户池时这些区域有SetUserPoolMfaConfigAPI 操作可用于将 MFA 设置为required用于现有用户池

bull 在启用 MFA 且选择短信作为第二安全要素时必须验证电话号码bull 高级安全功能要求 MFA 已启用并在 Amazon Cognito 用户池控制台中设置为可选有关更多信息请参阅

向用户池添加高级安全 (p 303)

配置多重验证您可以在 Amazon Cognito 控制台中配置 MFA

在 Amazon Cognito 控制台中配置 MFA

1 从左侧导航栏中选择 MFA 和验证2 选择 MFA 处于关闭可选还是必需状态

3 选择可选以按用户启用 MFA（或者如果使用的是基于风险的自适应身份验证）有关自适应身份验证的更多信息请参阅向用户池添加高级安全 (p 303)

4 选择要在应用程序中支持的第二安全要素用户可以使用短信或基于时间的一次性密码作为第二安全要素我们建议使用 TOTP这允许使用 SMS 作为密码恢复机制而不是身份验证因素

5 如果使用短信作为第二安全要素并且未定义具有此权限的 IAM 角色则可在控制台中创建一个此角色选择创建角色创建 IAM 角色以创建允许 Amazon Cognito 代表您向用户发送 SMS 消息的 IAM 角色有关更多信息请参阅 IAM 角色


SMS 文本消息 MFA如果用户登录时 MFA 启用它们先输入并提交其用户名和密码客户端应用程序将收到指示授权代码发送位置的 getMFA 响应客户端应用程序应向用户指明在哪里查找代码 (如代码被发送到哪个电话号码)接下来它提供了一个用于输入代码的表单最后客户端应用程序提交代码以完成登录过程将遮蔽目的地

301


它会隐藏除电话号码的最后 4 位数以外的所有数字如果一个应用程序正在使用 Amazon Cognito 托管 UI则 ap 会显示一个页面让用户输入 MFA 代码

SMA 文本消息授权代码的有效期为 3 分钟

如果用户无法再访问其发送短信 MFA 代码的设备则它们必须请求客户服务部门帮助具备必要 Amazon账户权限的管理员可以更改用户的电话号码但只能通过 Amazon CLI 或 API 进行

当用户成功通过短信 MFA 流程时其电话号码也将标记为ldquo已验证rdquo

Note

SMS for MFA 是单独收费的(向电子邮件地址发送验证代码是不收费的) 有关 Amazon SNS 定价的信息请参阅全球 SMS 定价有关提供 SMS 消息发送服务的最新国家地区列表请参阅支持的区域和国家地区

Important

要确保为验证电话号码或为 SMS 文本消息 MFA 发送 SMS 消息您必须请求增加 Amazon SNS 的支出限额Amazon Cognito 使用 Amazon SNS 向用户发送 SMS 消息Amazon SNS 发送 SMS 消息的数量取决于支出限额支出限制可以指定Amazon账户和单个消息且该限额仅适用于发送 SMS 消息的费用每个账户的默认支出限额 (如果未指定) 为每月 100 USD如果您要提高限额请提交SNS 限制提高案例中的Amazon Web Services Support中心在新限制值中输入所需的每月支出限额在使用案例描述字段中说明您要请求提高每月的 SMS 支出限额

要向用户池添加 MFA请参阅向用户池添加多重验证 (MFA) (p 300)

TOTP 软件令牌 MFA您的用户会面临质询要求其使用基于时间的一次性密码 (TOTP) 完成身份验证在激活 MFA 的 TOTP 软件令牌期间验证了用户名和密码后将启用此选项如果应用程序对用户登录使用 Amazon Cognito 托管UI则当用户会显示第二页此页面要求您的用户提交其用户名和密码然后输入 TOTP 密码

您可以通过 Amazon Cognito 控制台通过 Amazon Cognito 托管 UI 或使用 Amazon Cognito API 操作为用户池启用 TOTP MFA在用户池级别您可以通过调用 SetUserPoolMfaConfig 配置 MFA 和启用 TOTPMFA

Note

如果未为用户池启用 TOTP 软件令牌 MFA则用户无法与此令牌关联或验证此令牌他们收到了这个SoftwareTokenMFANotFoundException异常ldquouserPool 尚未启用软件令牌 MFArdquo 如果稍后为用户池禁用了软件令牌 MFA以前已关联并验证了 TOTP 令牌的用户可以继续将其用于MFA

为用户配置 TOTP 是一个多步骤过程在此过程中用户将收到一个秘密代码它们通过输入一次性密码来验证该代码接下来您可以为用户启用 TOTP MFA或将 TOTP 设置为用户的首选 MFA 方法


关联 TOTP 令牌

TOTP 令牌关联涉及向您的用户发送一个秘密代码他们必须使用一次性密码验证该代码此部分有三个步骤

1 当您的用户选择 TOTP 软件令牌 MFA 时调用 AssociateSoftwareToken 来返回为用户账户生成的唯一共享私有密钥代码对此 API 方法的请求需要访问令牌或会话字符串但不同时需要两者为方便起见您可以将私有密钥作为快速响应 (QR) 代码分发

302

Amazon Cognito 开发人员指南添加高级安全

Note

调用 AssociateSoftwareToken 会立即解除现有软件令牌与用户帐户的关联如果用户随后没有验证软件令牌则他们的帐户基本上设置为在没有 MFA 的情况下进行身份验证如果在用户池级别将 MFA 配置设置为可选则用户可以在没有 MFA 的情况下登录但是如果用户池的MFA 设置为 ldquo必需rdquo则系统会要求用户在登录时设置新的软件令牌 MFA

2 密钥代码或 QR 码将显示在您的应用程序上您的用户需要将其输入到一个 TOTP 生成应用程序 (如Google Authenticator) 中

3 您的用户将密钥代码输入到 TOTP 生成应用程序中以便将新账户与您的客户端应用程序相关联

验证 TOTP 令牌

下一步是验证 TOTP 令牌过程概述

1 当新的 TOTP 账户与应用程序关联后它将生成一个临时密码2 您的用户将该临时密码输入您的应用程序而您的应用程序则通过调用 VerifySoftwareToken 来响应在

Amazon Cognito 服务服务器上将生成一个 TOTP 代码并与用户的临时密码作比较如果二者匹配则服务将其标记为已验证

3 如果代码正确确认所用的时间在范围内重试次数也未超过最大值Amazon Cognito 还接受提前或延迟一个 30 秒时段以解决时钟偏差的 TOTP 令牌如果您的用户通过了所有步骤则验证完成

如果代码不正确则验证无法完成您的用户可以重试或取消我们建议您的用户同步其 TOTP 生成应用程序的时间

使用 TOTP MFA 登录

此时您的用户使用基于时间的一次性密码登录过程如下所述

1 用户将输入其用户名和密码来登录客户端应用程序2 TOTP MFA 质询被调用您的应用程序提示用户输入临时密码3 您的用户从关联的 TOTP 生成应用程序获取临时密码4 您的用户在您的客户端应用程序中输入 TOTP 代码您的应用程序通知 Amazon Cognito 服务验证该代

码每次登录时都应调用 RespondToAuthChallenge以获取对新的 TOTP 身份验证质询的响应5 如果令牌通过 Amazon Cognito 验证则登录成功您的用户可以继续完成身份验证流程

删除 TOTP 令牌

最后您的应用程序应允许用户删除 TOTP 令牌

1 客户端应用程序应要求用户输入其密码2 如果密码正确则删除 TOTP 令牌

Note

目前 API 中不支持删除 TOTP 软件令牌操作计划在未来版本中提供此功能使用 SetUserMFAPreference 为单独的用户禁用 TOTP MFA

向用户池添加高级安全在创建用户池之后即可访问高级安全性Amazon Cognito 控制台中导航栏上可以打开用户池高级安全功能并自定义为响应不同风险要执行的操作也可以使用审核模式收集有关检测到的风险的指标而不

303


执行操作在审核模式下高级安全功能会将指标发布到 Amazon CloudWatch请参阅查看高级安全指标 (p 309)

Note

Amazon Cognito 高级安全功能适用其他定价请参阅Amazon Cognito 定价页面

主题bull Prerequisites (p 304)bull 配置高级安全功能 (p 304)bull 检查遭盗用的凭证 (p 306)bull 使用自适应身份验证 (p 306)bull 查看高级安全指标 (p 309)bull 通过应用程序启用用户池高级安全 (p 310)


bull 用户池和应用程序客户端有关更多信息请参阅用户池入门 (p 19)bull 将多重身份验证 (MFA) 设置为可选以使用基于风险的自适应身份验证功能有关更多信息请参阅向用户

池添加多重验证 (MFA) (p 300)bull 如果您使用电子邮件进行通知请转到Amazon SES 控制台配置并验证要用于通知电子邮件的电子邮件地

址或域有关 Amazon SES 的更多信息请参阅在 Amazon SES 中验证身份

配置高级安全功能为用户池配置高级安全

1 从左侧导航栏中选择高级安全2 对于是否要为此用户池启用高级安全功能选择是以启用高级安全功能或者选择仅审核来收集信息并

将用户池数据发送到 Amazon CloudWatch

建议在启用操作之前先将高级安全功能保持在审核模式下两周这允许 Amazon Cognito 了解应用程序用户的使用模式

3 从下拉列表中选择您希望自定义哪个应用程序客户端的设置默认为对于所有应用程序客户端将设置保留为全局

4 对于对于对遭盗用的凭证您希望采取什么操作选择允许或阻止使用5 选择自定义何时阻止遭盗用的凭证以选择哪些事件应触发遭盗用的凭证检查

bull 登录bull 注册bull 密码更改

6 在当登录尝试被评为低中和高风险时您希望如何使用自适应身份验证下选择如何响应恶意登录尝试可以允许或阻止登录尝试或者在允许登录前要求额外的质询

要在检测到异常登录尝试时发送电子邮件通知请选择通知用户

304


7 如果在上一步中选择了通知用户则可通过使用通知消息自定义表单自定义电子邮件通知消息

8 选择自定义以自定义包含 HTML 和明文电子邮件版本的自适应身份验证通知要了解有关电子邮件模板的更多信息请参阅消息模板 (p 160)

9 键入不管高级安全风险评估如何都要始终允许或始终阻止的任何 IP 地址指定 IP 地址范围CIDR 表示法(例如 192168100024)


305


检查遭盗用的凭证Amazon Cognito 可检测用户的凭证（用户名和密码）是否已在别处遭盗用这种情况可能出现在用户在多个站点重复使用凭证时或它们使用容易猜到的密码时

从高级安全性页面上您可以选择在检测到泄露的凭证时是允许还是阻止用户阻止需要用户另外选择一个密码选择Allow会将所有尝试使用遭盗用凭证的情况发布到 Amazon CloudWatch有关更多信息请参阅查看高级安全指标 (p 309)

还可以选择在登录注册和密码更改期间Amazon Cognito 是否检查遭盗用的凭证

Note

目前Amazon Cognito 不检查采用安全远程密码 (SRP) 流的登录操作中的泄露凭证该流在登录期间不会发送密码将检查结合使用 AdminInitiateAuth API 与 ADMIN_NO_SRP_AUTH 流程以及结合使用 InitiateAuth API 与 USER_PASSWORD_AUTH 流程的登录是否存在遭盗用的凭证

要向用户池添加遭盗用凭证保护请参阅向用户池添加高级安全 (p 303)

使用自适应身份验证借助自适应身份验证可以将用户池配置为阻止可疑登录或添加第二安全要素身份验证以响应增加的风险级别对于每次登录尝试Amazon Cognito 都会生成一个风险分数来表示登录请求来自遭盗用源的可能性此风险分数基于许多因素包括它是否检测到新设备用户位置或 IP 地址自适应身份验证基于风险级别为在用户级别没有启用 MFA 类型的用户添加 MFA当在用户级别启用 MFA 类型时无论您如何配置自适应身份验证这些用户在身份验证过程中将始终收到第二个因素质询

Amazon Cognito 将向 Amazon CloudWatch 发布登录尝试其风险级别和失败的质询有关更多信息请参阅查看高级安全指标 (p 309)

要向用户池添加自适应身份验证请参阅向用户池添加高级安全 (p 303)

主题bull 自适应身份验证概述 (p 307)bull 创建设备指纹 (p 307)bull 查看用户事件历史记录 (p 307)bull 提供事件反馈 (p 309)bull 发送通知消息 (p 309)

306


自适应身份验证概述

从高级安全性页面上您可以选择自适应身份验证的设置包括在不同风险级别下采取什么操作以及向用户发送的通知消息的自定义设置

对于每个风险级别您可以选择以下选项

选项操作

允许允许登录尝试而无需额外因素

可选 MFA 如果用户配置了第二个因素（如 SMS 的电话号码或配置了 TOTP 软件令牌）则需要完成第二安全要素质询才能登录允许未配置第二个因素的用户登录不需要额外的安全要素

需要 MFA 如果用户配置了第二个因素（如 SMS 的电话号码或配置了 TOTP 软件令牌）则需要完成第二安全要素质询才能登录阻止未配置第二因素的用户登录

Block 阻止该风险级别下的所有登录尝试

Note

手机号码不需要验证即可用于短信作为第二个认证因素

创建设备指纹

当您调用 Amazon Cognito 身份验证 API（例如AdminInitiateAuth或者AdminRespondToAuthChallenge从服务器上传递用户的源 IP需要在 ContextData 参数中传递用户的源 IP除此之外还有通过使用 AmazonCognito 上下文数据收集库收集的服务器名称服务器路径和编码的设备指纹数据

有关从 Web 或移动应用程序启用高级安全的信息请参阅通过应用程序启用用户池高级安全 (p 310)

当应用程序从服务器调用 Amazon Cognito 时从客户端收集用户上下文数据以下是使用 JavaScript 开发工具包方法 getData 的示例

var encodedData = AmazonCognitoAdvancedSecurityDatagetData(username userPoolId clientId)

建议在应用程序中包含最新的 Amazon Cognito 开发工具包这使自适应身份验证能够收集设备指纹信息 mdash如设备 ID模型和时区有关 Amazon Cognito 软件开发工具包的更多信息请参阅安装用户池开发工具包

查看用户事件历史记录

您可以在 Amazon Cognito 控制台中从用户和组查看该用户的登录历史记录Amazon Cognito 将用户事件历史记录保留两年

307


每个登录事件都有一个事件 ID上下文数据 (例如位置)设备详细信息以及与其关联的风险检测结果

您也可以将事件 ID 与颁发的令牌关联颁发的令牌（如 ID 令牌和访问令牌）将在其负载中包含此事件 ID使用刷新令牌的事件将保留原始事件 ID原始事件 ID 可追溯到导致颁发 Amazon Cognito 令牌的登录事件的事件 ID这使您能够跟踪系统中的令牌在特定身份验证事件中的使用

308


提供事件反馈

事件反馈实时影响风险评估并随着时间的推移改进风险评估算法您可以通过 Amazon Cognito 控制台和API 操作提供有关登录尝试有效性的反馈

在控制台中的用户和组选项卡上将列出登录历史记录如果您单击某个条目则可以将事件标记为有效或无效还可以通过用户池 API 方法 AdminUpdateAuthEventFeedbackAmazon CLI 命令 admin-update-auth-event-feedback 提供反馈

发送通知消息

借助高级安全保护Amazon Cognito 可以通知您的用户发现了登录尝试提示他们单击链接以指示登录有效还是无效并使用他们的反馈来改进您的用户池风险检测准确性

在当登录尝试被评为低中和高风险时您希望如何使用自适应身份验证部分中选择将低中和高风险案例通知用户

可以自定义通知电子邮件并同时提供明文和 HTML 版本选择自定义from适应身份验证通知消息以自定义电子邮件通知要了解有关电子邮件模板的更多信息请参阅消息模板 (p 160)

查看高级安全指标Amazon Cognito 将高级安全功能的指标发布到您在 Amazon CloudWatch 中的账户高级安全指标同时按风险级别和请求级别分组

使用 CloudWatch 控制台查看指标

1 通过以下网址打开 CloudWatch 控制台httpsconsoleawsamazoncomcloudwatch2 在导航窗格中选择指标3 选择 Amazon Cognito4 选择一组聚合指标如按风险分类5 所有指标选项卡显示该选择的所有指标您可执行以下操作

bull 要对表进行排序请使用列标题

309


bull 要为指标绘制图表请选中该指标旁的复选框要选择所有指标请选中表的标题行中的复选框bull 要按资源进行筛选请选择资源 ID然后选择添加到搜索bull 要按指标进行筛选请选择指标名称然后选择添加到搜索

指标描述指标维度

损害凭据风险 Amazon Cognito 在其中检测到泄露凭证的请求

操作操作类型PasswordChangeSignIn或者SignUp是唯一的维度

UserPoolId 用户池标识符

RiskLevel高 (默认)中低

AccountTakeOverRisk Amazon Cognito 在其中检测到账户接管风险的请求



RiskLevel高中低

OverrideBlock 因开发人员提供的配置而被Amazon Cognito 阻止的请求



RiskLevel高中低

风险请求 Amazon Cognito 标记为有风险的请求

操作操作类型如PasswordChangeSignIn或者SignUp


NoRisk Amazon Cognito 未识别出任何风险的请求



Amazon Cognito 为您提供两组预定义指标以供在 CloudWatch 中分析按风险分类标识 Amazon Cognito 识别为有风险的请求的风险级别粒度并且按请求分类反映了按请求级别聚合的指标

汇总指标组描述

按风险分类请求 Amazon Cognito 识别为有风险的请求

按请求分类按请求汇总的指标

通过应用程序启用用户池高级安全在为用户池配置高级安全功能后需要在 Web 或移动应用程序中启用这些功能

310

Amazon Cognito 开发人员指南Amazon 托管策略

对 JavaScript 使用高级安全

1 可能需要将 Amazon Cognito 开发工具包更新为最新版本有关 Amazon Cognito 软件开发工具包的更多信息请参阅安装用户池开发工具包

2 要使用身份验证开发工具包启用托管 UI请参阅 CognitoAuth JavaScript 示例应用程序3 将 AdvancedSecurityDataCollectionFlag 设置为 true此外将 UserPoolId 设置为用户池

ID4 在你的应用程序中替 ltregiongt 换你的Amazon如 us-east-1并将此源参考添加到 JavaScript 文件中

ltscript src=httpsamazon-cognito-assetsltregiongtamazoncognitocomamazon-cognito-advanced-security-dataminjsgtltscriptgt

有关更多信息请参阅适用于 JavaScript 的 Amazon Cognito 身份验证开发工具包的示例

对 Android 使用高级安全


2 要使用身份验证开发工具包启用托管 UI请参阅 CognitoAuth Android 示例应用程序3 使用 transitive = true 导入时aws-android-sdk-cognitoauth通过格拉德尔中的

Maven

将此作为依赖项包含在 buildgradle 文件中

compile comamazonawsaws-android-sdk-cognitoidentityprovider-asf100

有关更多信息请参阅 AmazonSDK for Android-Amazon Cognito 身份提供商 ASF

对 iOS 使用高级安全


2 要使用身份验证开发工具包启用托管 UI请参阅 CognitoAuth iOS 示例应用程序3 要通过使用 Infoplist 配置 Auth 开发工具包请将 PoolIdForEnablingASF 密钥添加到 Amazon Cognito

用户池配置并将它设置为用户池 ID

要使用 AWSCognitoAuthConfiguration 配置身份验证开发工具包请使用此初始化程序并指定用户池 ID作为 userPoolIdForEnablingASF

有关更多信息请参阅 AWSCognitoIdentityProviderASF

AmazonAmazon Cognito 的托管策略

要向用户组和角色添加权限与自己编写策略相比使用 Amazon 托管策略更简单创建仅为团队提供所需权限的 IAM 客户托管策略需要时间和专业知识要快速入门您可以使用我们的 Amazon 托管策略这些策略涵盖常见使用案例可在您的 Amazon 账户中使用有关 Amazon 托管策略的更多信息请参阅《IAM用户指南》中的 Amazon 托管策略

Amazon 服务负责维护和更新 Amazon 托管策略您无法更改 Amazon 托管策略中的权限服务偶尔会向Amazon 托管策略添加额外权限以支持新功能此类更新会影响附加策略的所有身份（用户组和角色）

311

Amazon Cognito 开发人员指南策略更新

当启动新功能或新操作可用时服务最有可能会更新 Amazon 托管策略服务不会从 Amazon 托管策略中删除权限因此策略更新不会破坏您的现有权限

此外Amazon 还支持跨多种服务的工作职能的托管策略例如ReadOnlyAccess Amazon 托管策略提供对所有 Amazon 服务和资源的只读访问权限当服务启动新功能时Amazon 会为新操作和资源添加只读权限有关工作职能策略的列表和说明请参阅《IAM 用户指南》中的适用于工作职能的 Amazon 托管策略

客户可使用 IAM 控制台提供的大量策略授予对 Amazon Cognito 的访问权限

bull AmazonCognitoPowerUser-对身份池和用户池所有方面的访问和管理权限要查看该策略的权限请参阅卓越亚马逊认证高级用户

bull AmazonCognitoReadOnly-对身份池和用户池的只读访问权限要查看该策略的权限请参阅AmazonCognitoReadOnly

bull AmazonCognitoDeveloperAuthenticatedIdentities-让身份验证系统与 Amazon Cognito 集成的权限要查看该策略的权限请参阅卓越亚马逊认知开发人员身份验证

这些策略由 Amazon Cognito 团队维护因此即使 IAM 中添加了新 API用户也将一直拥有相同级别的访问权限

Note

由于创建新的身份池时还需要创建 IAM 角色您希望用来创建新身份池的所有 IAM 用户也都必须应用管理员策略

Cognito 更新到Amazon托管策略

查看有关更新的详细信息Amazon托管策略因为此服务开始跟踪这些更改如需有关此页面更改的自动警报您可以在 Cognito 上订阅 RSS 源文档历史记录页

更改说明日期

AmazonCognitoPowerUsermdash更新到现有策略

添加了一项新权限允许 AmazonCognito 调用亚马逊简单通知服务的GetSMSSandboxAccountStatusoperation

此更改允许 Amazon Cognito 用户池用户池决定您是否需要退出Amazon 简单通知服务沙箱以便通过用户池向所有最终用户发送消息

2021 年 6 月 1 日

Cognito 开始跟踪变更 Cognito 开始跟踪其Amazon托管策略

2021 年 3 月 1 日

312

Amazon Cognito 开发人员指南支持的资源

为 Amazon Cognito 资源添加标签标签是您或 Amazon 为 Amazon 资源分配的元数据标记每个标签均包含一个键和一个值对于您分配的标签需要定义键和值例如您可以将键定义为 stage将一个资源的值定义为 test

标签可帮助您

bull 标识和整理您的 Amazon 资源许多 Amazon 服务支持标记因此您可以将同一标签分配给来不同服务的资源以指示这些资源是相关的例如您可以将同一标签分配给您分配给 Amazon DynamoDB 表的Amazon Cognito 用户池

bull 跟踪您的 Amazon 成本您可以在 Amazon Billing and Cost Management 控制面板上激活这些标签Amazon 使用标签对您的成本进行分类并向您提供每月成本分配报告有关更多信息请参阅Amazon Billing and Cost Management 用户指南中的使用成本分配标签

bull 根据分配给资源的标签控制对资源的访问您可以通过在 Amazon Identity and Access Management(IAM) 策略的条件中指定标签键和值来控制访问权限例如您可以允许 IAM 用户更新用户池但前提是该用户池具有owner标签的值为该用户的名称有关更多信息请参阅使用标签控制访问中的IAM 用户指南

您可以使用Amazon CLI或 Amazon Cognito API 来添加编辑或删除用户池和身份池的标签尤其对于用户池您还可以使用 Amazon Cognito 控制台来管理标签

有关使用标签的提示请参阅Amazon回答博客上的Amazon标记策略文章

以下部分提供有关 Amazon Cognito 的标签的更多信息

Amazon Cognito 中支持的资源Amazon Cognito 中的以下资源支持标记

bull 用户池bull 身份池

标签限制以下基本限制适用于 Amazon Cognito 资源上的标签

bull 您可以分配给资源的最大标签数量 mdash 50bull 最大密钥长度 ndash 128 个 Unicode 字符bull 最大值长度 ndash 256 个 Unicode 字符bull 键和值的有效字符 mdash a-zA-Z0-9空格和以下字符_= +-和 bull 键和值区分大小写bull 请不要使用 aws 作为键的前缀它保留为供 Amazon 使用

使用 Amazon Cognito 控制台管理标签您可以使用 Amazon Cognito 控制台来管理分配给用户池的标签

313

Amazon Cognito 开发人员指南Amazon CLI 示例

对于身份池控制台不包含标记功能因此您必须以编程方式管理标签例如您可以使用 AmazonCLI

将标签添加到用户池


2 选择 Manage User Pools (管理用户池)3 在 Your User Pools (您的用户池) 页面上选择要添加标签的用户池4 在左侧导航菜单中选择 Tags (标签)5 除非您的用户池已具有标签否则请选择 Add tag (添加标签) 以添加第一个标签6 为 Tag key (标签键) 和 Tag value (标签值) 指定值7 对于每个要添加的其他标签请选择 Add another tag (添加其他标签)8 添加完标签后选择 Save changes (保存更改)

在 Tags (标签) 页面上您还可以编辑任何现有标签的键和值要删除标签请选择标签右上角的 x 标记

Amazon CLI 示例这些区域有Amazon CLI提供了可用来管理您分配给 Amazon Cognito 用户池和身份池的标签

分配标签使用以下命令可将标签分配给现有的用户池和身份池

Example 适用于用户池的 tag-resource 命令

使用将标签分配给用户池tag-resource中的cognito-idp命令集

$ aws cognito-idp tag-resource gt --resource-arn user-pool-arn gt --tags Stage=Test

此命令包含以下参数

bull resource-arnmdash 您向其应用标签的用户池的 Amazon 资源名称 (ARN)要查找 ARN请在 AmazonCognito 控制台中选择用户池并查看池 ARN上的常规设置选项卡

bull tagsmdash 标签的键值对

要一次分配多个标签请以逗号分隔的列表形式指定它们

$ aws cognito-idp tag-resource gt --resource-arn user-pool-arn gt --tags Stage=TestCostCenter=80432Owner=SysEng

Example 适用于身份池的 tag-resource 命令

将标签分配给身份池方法是使用tag-resource中的cognito-identity命令集

$ aws cognito-identity tag-resource gt --resource-arn identity-pool-arn

314

Amazon Cognito 开发人员指南查看标签

gt --tags Stage=Test


bull resource-arnmdash 您向其应用标签的身份池的 Amazon 资源名称 (ARN)要查找 ARN请在 AmazonCognito 控制台中选择身份池并选择编辑身份池然后在 Identity pool ID (身份池 ID) 中选择 ShowARN (显示 ARN)



$ aws cognito-identity tag-resource gt --resource-arn identity-pool-arn gt --tags Stage=TestCostCenter=80432Owner=SysEng

查看标签使用以下命令可查看您已分配给用户池和身份池的标签

Example 适用于用户池的 list-tags-for-resource 命令

查看分配给用户池的标签具体方法是使用list-tags-for-resource中的cognito-idp命令集

$ aws cognito-idp list-tags-for-resource --resource-arn user-pool-arn

Example 适用于身份池的 list-tags-for-resource 命令

查看分配给身份池的标签具体方法是使用list-tags-for-resource中的cognito-identity命令集

$ aws cognito-identity list-tags-for-resource --resource-arn identity-pool-arn

删除标签使用以下命令从用户池和身份池中删除标签

Example 适用于用户池的 untag-resource 命令

使用从用户池中删除标签untag-resource中的cognito-idp命令集

$ aws cognito-idp untag-resource gt --resource-arn user-pool-arn gt --tag-keys Stage CostCenter Owner

对于 --tag-keys 参数指定一个或多个标签键但不包含标签值

Example 适用于身份池的 untag-resource 命令

使用从身份池中删除标签untag-resource中的cognito-identity命令集

$ aws cognito-identity untag-resource gt --resource-arn identity-pool-arn gt --tag-keys Stage CostCenter Owner

315

Amazon Cognito 开发人员指南在创建资源时应用标签


Important

删除用户或身份池后与已删除池相关的标签在删除后的三十天内仍可显示在控制台或 API 调用中

在创建资源时应用标签使用以下命令可在创建用户池或身份池时分配标签

Example create-user-pool 命令以及标签

当您使用 create-user-pool 命令创建用户时您可以使用 --user-pool-tags 参数指定标签

$ aws cognito-idp create-user-pool gt --pool-name user-pool-name gt --user-pool-tags Stage=TestCostCenter=80432Owner=SysEng

Example create-identity-pool 命令以及标签

当您使用 create-identity-pool 命令创建用户池时您可以使用 --identity-pool-tags 参数指定标签

$ aws cognito-identity create-identity-pool gt --identity-pool-name identity-pool-name gt --allow-unauthenticated-identities gt --identity-pool-tags Stage=TestCostCenter=80432Owner=SysEng

使用 Amazon Cognito API 管理标签您可以在 Amazon Cognito API 中使用以下操作来管理用户池和身份池的标签

适用于用户池标签的 API 操作使用以下 API 操作来分配查看和删除用户池的标签

bull TagResourcebull ListTagsForResourcebull UntagResourcebull CreateUserPool

适用于身份池标签的 API 操作使用以下 API 操作来分配查看和删除身份池的标签

bull TagResourcebull ListTagsForResourcebull UntagResourcebull CreateIdentityPool

316

Amazon Cognito 开发人员指南操作配额

Amazon Cognito 中的配额Amazon Cognito 限制您可以在账户中执行的操作数量Amazon Cognito 还限制了 Amazon Cognito 资源的数量和规模

操作配额 (p 317)

bull 配额分类 (p 317)bull 操作特殊处理 (p 317)bull 类别操作 (p 318)bull 跟踪配额使用情况 (p 321)bull 优化配额 (p 322)bull 确定配额要求 (p 322)bull API 请求速率配额 (p 322)

资源配额 (p 323)

操作配额

配额分类Amazon Cognito 限制了操作数量例如InitiateAuth或者RespondToAuthChallenge可用于在应用程序中执行某些用户操作这些操作分为常见使用案例的类别例如UserAuthentication或者UserCreation有关分类操作的列表请参阅类别操作 (p 318)这些类别可以更轻松地监控使用情况和请求增加配额

操作配额定义为类别内所有操作的每秒允许请求数 (RPS)Amazon Cognito 用户池服务将配额应用于每个类别中的所有操作例如类别UserCreation 包括四项操作SignUpConfirmSignUpAdminCreateUser 和AdminConfirmSignUp它被分配的合并配额为30 RPS如果同时进行多个操作此类别中的每个操作最多可以单独调用 30 个 RPS也可以组合调用

Note

类别配额是针对每个Amazon帐户和区域中的所有用户池

操作特殊处理操作配额是在类别级别对合并请求总数进行测量和强制执行的但AdminRespondToAuthChallenge和RespondToAuthChallenge操作其中应用特殊处理规则

这些区域有UserAuthentication类别包括四项行动AdminInitiateAuthInitiateAuthAdminRespondToAuthChallenge和RespondToAuthChallenge这些区域有InitiateAuth和AdminInitiateAuth操作按类别配额进行测量和强制执行匹配的RespondToAuthChallenge和AdminRespondToAuthChallenge操作受到一个单独的配额该配额是UserAuthentication类别限制以适应开发人员应用程序中设置的多个身份验证挑战这种提升的配额足以涵盖大多数使用案例超出每次身份验证调用三次阈值超出率将计入UserAuthentication类别限制

例如如果您的UserAuthentication类别为 80 RPS您可以调用RespondToAuthChallenge或者AdminRespondToAuthChallenge最多可达 240 个 RPS（80 个 RPS x 3 个）如果应用程序设置为

317

Amazon Cognito 开发人员指南类别操作

每次身份验证调用有四轮质询并且您每秒有 70 次登录则总计RespondToAuthChallenge将是 280 个RPS（70 x 4）这是比配额高出 40 个 RPS额外的 40 RPS 将添加到 70InitiateAuth调用的总使用率UserAuthentication类别是 110 RPS（40 + 70）这超过了设置为 80 RPS 的类别配额因此此应用程序将受到限制因为它比 80 RPS 的类别配额高出 30 RPS

类别操作您可以在下表中找到操作及其各自类别之间的映射只能根据客户的要求提高可调的类别限制有关更多信息请参阅 API 请求速率配额 (p 322)可调配额在帐户级别应用有些类别操作受到更多限制的配额规则的约束在用户池级别具有下限阈值您可以在表格中找到这些类别并在表下方的注释中找到它们的配额

Note

每个类别的费率限制取决于每月活跃用户 (MAU)默认限制支持最多 200 万 MAU如果您的 MAU少于 100 万个建议不要提交限额增加请求

类别操作配额适用于用户池中的所有用户还有适用于每个用户的每个用户配额对于每个用户每秒最多可发出 10 个请求这些请求是 ldquo读取rdquo 操作包括登录或获取配置文件或设备信息您还可以创建每秒最多十个 ldquo写入rdquo 操作的请求包括更新配置文件信息或 MFA 设置您不能更改每个用户配额

类别

name

操作描述默认配额

（以每秒请求数表示）

可调整

UserAuthenticationbull InitiateAuthbull RespondToAuthChallengebull AdminInitiateAuthbull AdminRespondToAuthChallenge

对用户进行身份验证（登录）的操作

这些操作需要操作特殊处理 (p 317)

120 是

UserCreation bull SignUpbull ConfirmSignUpbull AdminCreateUserbull AdminConfirmSignUp

创建或确认本地Amazon Cognito用户的操作本地用户是由 Cognito用户池直接创建和验证的用户

30 是

UserFederation Amazon Cognito管理了通过第三方IdP 将用户联合到Cognito 的操作

将用户与第三方身份提供商联合（身份验证）到您的Cognito 用户池的操作

25 是

UserAccountRecoverybull ChangePasswordbull ConfirmForgotPasswordbull ForgotPasswordbull AdminResetUserPasswordbull 管理员集用户密

码

恢复用户帐户或更改或更新用户密码的操作

30 否

UserRead bull 管理员用户bull GetUser

从用户池中检索用户的操作

25 是

318


类别

name



可调整

用户更新 bull AdminAddUserToGroupbull AdminDeleteUserAttributesbull AdminUpdateUserAttributesbull AdminDeleteUserbull AdminDisableUserbull 管理员启用用户bull 管理员链接提供

者用户bull 管理员禁用用户

的提供程序bull VerifyUserAttributebull DeleteUserbull 删除用户属性bull UpdateUserAttributesbull 管理员用户全局

注销bull 全局注销bull AdminRemoveUserFromGroup

客户用于管理用户和用户属性的操作

25 否

UserResourceReadbull AdminGetDevicebull AdminListGroupsForUserbull AdminListDevicesbull GetDevicebull ListDevicesbull GetUserAttributeVerificationCodebull ResendConfirmationCodebull 管理员列表用户

自动通知

从 AmazonCognito（如设备或组）检索用户资源信息的操作

50 是

UserResourceUpdatebull 管理员忘记设备bull AdminUpdateAuthEventFeedbackbull 管理员集用户

MFP 参考bull AdminSetUserSettingsbull 管理设备bull UpdateDeviceStatusbull 更新发布反馈bull 确认设备bull SetUserMFAPreferencebull 设置用户设置bull VerifySoftwareTokenbull AssociateSoftwareTokenbull ForgetDevice

更新用户资源信息（如组）的操作

25 否

319


类别

name



可调整

UserList bull ListUsersbull 列表用户组合

返回用户列表的操作

30 否

UserPoolRead bull DescribeUserPoolbull ListUserPools

读取用户池的操作

15 否

UserPoolUpdate bull CreateUserPoolbull UpdateUserPoolbull DeleteUserPool

创建更新和删除用户池的操作

15 否

UserPoolResourceReadbull DescribeIdentityProviderbull DescribeResourceServerbull DescribeUserImportJobbull DescribeUserPoolDomainbull GetCSVHeaderbull GetGroupbull 获取签名证书bull 获取提供者按标

识符bull 获取用户池图bull ListGroupsbull 列表

ListIdentityProvidersbull ListResourceServersbull ListTagsForResourcebull ListUserImportJobsbull 描述配置bull GetUICustomization

从用户池（如组）检索资源的操作

20 否

320

Amazon Cognito 开发人员指南跟踪配额使用情况

类别

name



可调整

UserPoolResourceUpdatebull AddCustomAttributesbull CreateGroupbull CreateIdentityProviderbull CreateResourceServerbull CreateUserImportJobbull CreateUserPoolDomainbull DeleteGroupbull DeleteIdentityProviderbull DeleteResourceServerbull DeleteUserPoolDomainbull SetUserPoolMfaConfigbull StartUserImportJobbull StopUserImportJobbull UpdateGroupbull UpdateIdentityProviderbull UpdateResourceServerbull 塞特里斯克配置bull SetUICustomizationbull TagResourcebull UntagResource

更新用户池（如组）资源信息的操作

15 否

UserPoolClientReadbull DescribeUserPoolClientbull ListUserPoolClients

列出用户池客户端的操作

15 否

UserPoolClientUpdatebull CreateUserPoolClientbull DeleteUserPoolClientbull UpdateUserPoolClient

创建更新和删除用户池客户端的操作

15 否

UserToken bull 撤销令牌创建更新和删除令牌的操作

120 否

此类别中的任何单独操作都有一个约束可以阻止单个用户池以高于 5 RPS 的速率调用操作

跟踪配额使用情况每个 API 类别都具有CallCount和ThrottleCount在账户级别应用的 CloudWatch 指标您可以使用CallCount来跟踪客户与类别相关的呼叫总数您可以使用ThrottleCount来跟踪与类别相关的受限调用的总数您可以使用CallCount和ThottleCount指标Sum统计数据来计算类别中的呼叫总数有关CloudWatch 使用情况指标的更多信息请参阅CloudWatch 使用情况指标

利用率和使用率是两个术语可以帮助您了解服务配额监控利用率是正在使用的服务配额的百分比例如如果配额值为 200 个资源并且正在使用 150 个资源则利用率为 75使用量是指正在用于服务配额的资源或操作的数量

通过 CloudWatch 指标跟踪使用情况

321

Amazon Cognito 开发人员指南确定配额要求

您可以使用 CloudWatch 跟踪和收集 Amazon Cognito 用户池利用率指标云监视仪表板将显示有关每个Amazon服务您可以使用 CloudWatch 来创建指标警报可以将警报设置为向您发送通知或更改您正在监视的特定资源有关 CloudWatch 指标的更多信息请参阅有关 Service Quotas 的更多信息跟踪您的CloudWatch 使用量指标 (p 289)

通过 Service Quotas 度量跟踪利用率

Amazon Cognito 用户池与 Service Quotas 集成服务配额是一个基于浏览器的界面您可以使用该界面查看和管理您的服务配额使用情况在 Service Quotas 控制台中您可以查找特定配额的值查看监控信息请求增加配额以及设置 CloudWatch 警报在您的帐户处于活动状态一段时间后您可以查看资源利用率图表

有关在 Service Quotas 控制台中查看配额的更多信息请参阅查看 Service Quotas

确定配额要求要计算配额要求请确定在特定时间段内将与您的应用程序进行交互的活动用户数例如如果您的应用程序预计在 8 小时内平均有 100 万活跃用户登录那么您需要能够对平均每秒 35 个用户进行身份验证

此外如果您假定平均用户会话为两小时并且令牌配置为在一小时后过期则每个用户必须在此会话期间刷新其令牌一次然后支持此负载的用户身份验证类别所需的平均配额为 70 RPS

如果通过计算 8 小时内用户登录频率的差异假定峰值与平均比率为 31则需要 200 RPS 的用户身份验证配额

Note

如果您为每个用户操作调用多个操作则需要在类别级别总结各个操作调用率

优化配额按照以下方法之一处理高峰呼叫率

在退出等待期后重试尝试

您可以在每次 API 调用时捕获错误然后在退出期后重试尝试您可以根据业务需求和负载调整退避算法亚马逊软件开发工具包具有内置的重试逻辑有关 Amazon Tools 和 SDK 的更多信息请参阅要构建的工具Amazon

对频繁更新的属性使用外部数据库

如果您的应用程序需要对用户池进行多次调用以读取或写入自定义属性请使用外部存储您可以使用首选数据库存储自定义属性也可以在登录期间使用缓存图层加载用户配置文件您可以在需要时从缓存中引用此配置文件而不是从用户池重新加载用户配置文件

在客户端验证 JWT 令牌

应用程序必须在信任 JWT 令牌之前验证它们您可以在客户端验证令牌的签名和有效性而无需向用户池发送 API 调用验证令牌后您可以信任令牌中的声明并使用声明而不是使用更多getUserAPI 调用有关 JSON 令牌验证的更多信息请参阅验证 JSON Web 令牌

API 请求速率配额Amazon Cognito 限制您可以在账户中执行的用户池操作的数量您可以请求提高 Amazon Cognito 中的可调整 API 请求费率配额要申请提高配额您可以使用 Service Quotas Quot Quot 控制台使用 Service QuotQuot 提高窗体使用RequestServiceQuotaIncreaseAPI 或ListAWSDefaultServiceQuotasAPI

322

Amazon Cognito 开发人员指南资源配额

bull 要使用 Service Quitas 控制台请求提高配额请参阅请求提升 API 配额中的Service Quotas 用户指南bull 如果 Service Quitas 中尚未提供配额请使用提高服务限制表单

Note

只能提高可调整配额

资源配额资源配额是限制资源数量和大小的配额您可以请求提高 Amazon Cognito 中的可调整的资源配额要申请提高配额您可以使用 Service Quotas Quot Quot 控制台或使用提高服务限制表单要从 Service Quotas控制台请求配额请参阅请求增加配额中的Service Quotas 用户指南如果 Service Quitas 中尚未提供配额请使用提高服务限制表单

可调整资源配额

下表提供了 Amazon Cognito 的可调资源配额这些配额可以更改

用户池资源配额

资源配额

每个用户池的最大应用程序客户端数 1000

每个账户的最大用户池数 1000

每个用户池的最大用户导入作业数 1000

每个用户池的最大身份提供商数量 300

每个用户池的最大资源服务器数 25

每个用户池的最大用户数 40000000

身份池（联合用户）资源配额

资源配额

每个账户的最大身份池数 1000

每个身份池的最大 Amazon Cognito 用户池提供商数

50

同步资源配额

资源配额

每个身份的最大数据集数 20

每个数据集的最大记录数 1024

323

Amazon Cognito 开发人员指南不可调整的资源配额

资源配额

单个数据集的最大大小 1MB

不可调整的资源配额下表描述了 Amazon Cognito 不可调配额这些配额不能更改

用户池令牌有效性配额

Token 配额

ID 令牌 5 分钟 mdash 1 天

刷新令牌一小时 mdash 三千五百五十天

访问令牌 5 分钟 mdash 1 天


资源配额

每个用户池的最大自定义属性数 50

每个属性的最大字符数 2048 字节

自定义属性名称中的最大字符数 20

密码中的最小字符数 6mdash99

每个每天发送的最大电子邮件数Amazon账户 sup1 50

电子邮件主题中的最大字符数 140

电子邮件中的最大字符数 20000

SMS 验证消息中的最大字符数 140

密码中的最大字符数 256

身份提供商名称中的最大字符数 40

每个身份提供商的最大标识符数 50

链接到用户的最大标识数 5

每个应用程序客户端的最大回调 URL 数 100

每个应用程序客户端的最大注销 URL 数 100

每个资源服务器的最大范围数 100

每个应用程序客户端的最大范围数 50

每个账户的最大自定义域数 4

每个用户可以属于的组的最大数量 100

324


资源配额

每个用户池的最大组数 10000

sup1 仅当您使用 Amazon Cognito 用户池的默认电子邮件功能时此配额才适用要启用更高的电子邮件传输量请将您的用户池配置为使用您的 Amazon SES 电子邮件配置有关更多信息请参阅 Amazon Cognito用户池的电子邮件设置 (p 134)

用户池代码有效性资源配额

资源配额

注册确认代码 24 小时

用户属性验证码有效性 24 小时

多重验证代码 3 minutes

忘记密码代码 1 小时

托管 UI 配额

工作流名称配额

客户端凭证每秒 150 个请求


资源配额

身份池名称的最大字符长度 128 字节

登录提供商名称的最大字符长度 2048 字节

每个身份池的最大身份数无限

可以为其指定角色映射的最大身份提供商数量 10

单个列表或查找调用的最大结果数 60

基于角色的访问控制 (RBAC) 规则的最大数 25

同步资源配额

资源配额

数据集名称中的最大字符数 128 字节

请求成功后批量发布的最短等待时间 24 小时

325

Amazon Cognito 开发人员指南用户池 API 参考

Amazon Cognito API 参考使用以下链接以转到相关 API 参考页面

bull Amazon Cognito 用户池 API 参考bull Amazon Cognito 身份池 (联合身份) API 参考bull Amazon Cognito 同步 API 参考bull Amazon Cognito 用户池

Amazon Cognito 用户池 API 参考借助 Amazon Cognito 用户池您可以让 Web 和移动应用程序用户注册和登录您可以更改经过身份验证的用户的密码并为未经身份验证的用户启动忘记密码流程有关更多信息请参阅 User池身份验证流程 (p 285) 和将令牌与用户池结合使用 (p 139)

有关完整的用户池 API 参考请参阅Amazon Cognito 用户池 API 参考

Amazon Cognito 用户池身份验证 API 参考在为用户池配置域后Amazon Cognito 将托管一台身份验证服务器您可以在其中向应用程序添加注册和登录网页有关更多信息请参阅添加应用程序以启用托管 UI

本节介绍从用户池客户端将 HTTPS 合同与 Amazon Cognito 身份验证服务器联合包括示例请求和响应它介绍了身份验证服务器在肯定条件和否定条件下的预期行为

除了服务器合同 REST API 之外Amazon Cognito 还提供了适用于 AndroidiOS 和 JavaScript 的验证开发工具包简化了构建请求以及与服务器交互的过程了解有关的更多信息Amazon Cognito 开发工具包

有关规范的更多信息请参阅 OpenID Connect 10 和 OAuth 20

主题bull AUTHORIZATION 终端节点 (p 326)bull TOKEN 终端节点 (p 331)bull USERINFO 终端节点 (p 334)bull LOGIN 终端节点 (p 336)bull LOGOUT 终端节点 (p 337)bull 撤销终端节点 (p 338)

AUTHORIZATION 终端节点oauth2authorize 终端节点让用户登录

GET oauth2authorizeoauth2authorize 终端节点只支持 HTTPS GET用户池客户端通常通过浏览器发出此请求Web 浏览器包括 Chrome 或 FirefoxAndroid 浏览器包括自定义 Chrome 选项卡iOS 浏览器包括 Safari View 控件

326

Amazon Cognito 开发人员指南AUTHORIZATION 终端节点

授权服务器在访问授权终端节点时需要 HTTPS 而不是 HTTP 作为协议有关规范的更多信息请参阅授权终端节点

请求参数

response_type

响应类型必须为 code 或 token指示客户端需要最终用户的授权代码 (授权代码授予流) 还是直接为最终用户发布令牌 (隐式流)

必填项client_id

客户端 ID

必须是用户池中的预注册客户端并且必须已启用联合功能

必填项redirect_uri

在用户授权之后身份验证服务器将浏览器重定向到的 URL

重定向 URI 必须具有以下属性bull 它必须是绝对 URIbull 必须预先向客户端注册bull 它不能包含片段组件


Amazon Cognito 要求HTTPSOVERHTTP但除外部httplocalhost只用于测试目的

应用程序回调 URL（如 myappexample）也受支持

必填项state

客户端添加到初始请求的不透明值授权服务器在重定向回客户端时包括此值

客户端必须使用此值来防止 CSRF 攻击

此值可选但强烈建议使用identity_provider

由开发人员直接用来在特定提供商处进行身份验证bull 对于社交登录有效值为 FacebookGoogleLoginWithAmazon 和 SignInWithApplebull 对于 Amazon Cognito 用户池有效值为COGNITObull 对于其他身份提供商这将是您在用户池中分配给 IdP 的名称

可选idp_identifier

开发人员此参数映射到提供商名称而不公开提供商名称

可选scope

可以是任意系统预留范围或与客户端关联的自定义范围的组合范围必须以空格分隔系统预留范围为openidemailphoneprofile 和 awscognitosigninuseradmin使用的任意范围必须与客户端关联否则它将在运行时被忽略

327


如果客户端不请求任何范围则身份验证服务器使用与客户端关联的所有范围

如果请求 openid 范围则只返回 ID 令牌只有在以下情况下才能对 Amazon Cognito 用户池使用访问令牌awscognitosigninuseradmin范围如果同时请求了 phone 范围则只能请求emailprofile 和 openid 范围这些范围控制进入 ID 令牌中的声明

可选code_challenge_method

用于生成质询的方法这些区域有PKCE RFC 中心定义两个方法S256 和 Ingnito 身份验证服务器但是Amazon Cognito 身份验证服务器仅支持 S256

可选code_challenge

从 code_verifier 生成的质询

仅在指定 code_challenge_method 时必需

具有正向响应的示例请求

授予授权代码

示例请求

GET httpsmydomainauthus-east-1amazoncognitocomoauth2authorize response_type=codeamp client_id=ad398u21ijw3s9w3939amp redirect_uri=httpsYOUR_APPredirect_uriamp state=STATEamp scope=openid+profile+awscognitosigninuseradmin

示例响应

Amazon Cognito 身份验证服务器使用授权代码和状态重定向回您的应用程序代码和状态必须在查询字符串参数中返回而不是在片段中查询字符串是 Web 请求的一部分显示在ldquordquo字符之后该字符串可以包含一个或多个使用ldquoamprdquo字符分隔的参数片段是 Web 请求中显示在ldquordquo字符后的部分用于指定文档的子部分

Note

响应返回一次性使用代码该代码在五分钟内有效

HTTP11 302 FoundL ocation httpsYOUR_APPredirect_uricode=AUTHORIZATION_CODEampstate=STATE

具有 PKCE 的授权代码授予

示例请求

GET httpsmydomainauthus-east-1amazoncognitocomoauth2authorize response_type=codeamp client_id=ad398u21ijw3s9w3939amp redirect_uri=httpsYOUR_APPredirect_uriamp state=STATEamp

328


scope=awscognitosigninuseradminamp code_challenge_method=S256amp code_challenge=CODE_CHALLENGE

示例响应

身份验证服务器使用授权代码和状态重定向回您的应用程序代码和状态必须在查询字符串参数中返回而不是在片段中

HTTP11 302 Found Location httpsYOUR_APPredirect_uricode=AUTHORIZATION_CODEampstate=STATE

不带 openid 范围的令牌授予

示例请求

GET httpsmydomainauthus-east-1amazoncognitocomoauth2authorize response_type=tokenamp client_id=ad398u21ijw3s9w3939amp redirect_uri=httpsYOUR_APPredirect_uriamp state=STATEamp scope=awscognitosigninuseradmin

示例响应

Amazon Cognito 授权服务器使用访问令牌重定向回您的应用程序由于未请求 openid 范围不会返回 ID令牌此流中从不返回刷新令牌令牌和状态在片段中返回而不是在查询字符串中

HTTP11 302 Found Location httpsYOUR_APPredirect_uriaccess_token=ACCESS_TOKENamptoken_type=bearerampexpires_in=3600ampstate=STATE

具有 openid 范围的令牌授予

示例请求

GET httpsmydomainauthus-east-1amazoncognitocomoauth2authorize response_type=tokenamp client_id=ad398u21ijw3s9w3939amp redirect_uri=httpsYOUR_APPredirect_uriamp state=STATEamp scope=awscognitosigninuseradmin+openid+profile

示例响应

授权服务器重定向回您的应用程序带有访问令牌和 ID 令牌 (因为包括了 openid 范围)

HTTP11 302 Found Location httpsYOUR_APPredirect_urid_token=ID_TOKENampaccess_token=ACCESS_TOKENamptoken_type=bearerampexpires_in=3600ampstate=STATE

329


负向响应的示例

以下是负向响应的示例

bull 如果client_id和redirect_uri是有效的但请求参数存在其他问题（例如如果response_type不包括在内如果code_challenge已提供但code_challenge_method未提供或code_challenge_method不是 S256）身份验证服务器会将该错误重定向到客户端的redirect_uri

HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_request

bull 如果客户端请求 ldquo代码rdquo 或 ldquo令牌rdquoresponse_type但没有这些请求的权限则 Amazon Cognito 授权服务器应返回unauthorized_client转换到客户端的redirect_uri 具体如下所示

HTTP 11 302 Found Location httpsclient_redirect_urierror=unauthorized_client

bull 如果客户端请求无效未知或范围格式错误Amazon Cognito 授权服务器将返回invalid_scope添加到客户端的redirect_uri 具体如下所示

HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_scope

bull 如果服务器中有意外的错误身份验证服务器会返回server_error转换到客户端的redirect_uri不要在浏览器中向最终用户显示 HTTP 500 错误因为此错误不发送到客户端应返回以下错误

HTTP 11 302 Found Location httpsclient_redirect_urierror=server_error

bull 通过联合第三方身份提供商进行身份验证时Cognito 可能会遇到以下连接问题bull 如果从身份提供商处请求令牌时连接超时身份验证服务器会将该错误重定向到客户端的redirect_uri如下所示

HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_requestamperror_description=Timeout+occurred+in+calling+IdP+token+endpoint

bull 如果在调用 jwks 终端节点时发生连接超时id_token验证时身份验证服务器会将该错误重定向到客户端的redirect_uri如下所示

HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_requestamperror_description=error_description=Timeout+in+calling+jwks+uri

bull 通过联合第三方身份提供商进行身份验证时提供商可能会因配置错误或其他原因返回错误响应如下所示bull 如果从其他提供商处收到错误响应身份验证服务器会将该错误重定向到客户端的 redirect_uri如

下所示

HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_requestamperror_description=[IdP name]+Error+-+[statuscode]+error getting token

bull 如果从 Google 收到错误响应身份验证服务器会将该错误重定向到客户端的redirect_uri如下所示HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_requestamperror_description=Google+Error+-+[status code]+[Googleprovided error code]

bull 在极少数情况下如果 Cognito 在与外部身份提供商建立连接时遇到通信协议异常身份验证服务器会将该错误重定向到客户端的 redirect_uri并显式以下错误消息bull HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_requestamperror_description=Connection+reset

330

Amazon Cognito 开发人员指南TOKEN 终端节点

bull HTTP 11 302 Found Location httpsclient_redirect_urierror=invalid_requestamperror_description=Read+timed+out

TOKEN 终端节点oauth2token 终端节点获取用户的令牌

POST oauth2tokenoauth2token 终端节点只支持 HTTPS POST用户池客户端直接对此终端节点发出请求而不通过系统浏览器

有关规范的更多信息请参阅令牌终端节点

标头中的请求参数

授权

如果向客户端发布了密钥则客户端必须通过基本 HTTP 授权在其授权标头中传递 client_id 和client_secret密钥是基本 Base64Encode(client_idclient_secret)

Content-Type

必须始终为 applicationx-www-form-urlencoded

正文中的请求参数

grant_type

授予类型

必须为 authorization_code 或 refresh_token 或 client_credentials

必填项client_id

客户端 ID

必须是用户池中的预注册客户端必须为客户端启用 Amazon Cognito 联合功能

如果客户端是公有的且没有密钥则为必需scope

可以是任何与客户端关联的自定义范围的组合请求的任意范围必须预先与客户端关联否则它将在运行时被忽略如果客户端不请求任何范围则身份验证服务器使用与客户端关联的所有自定义范围

可选仅当 grant_type 为 client_credentials 时使用redirect_uri

必须相同redirect_uri这是用来获得authorization_code在oauth2authorize

仅当 grant_type 为 authorization_code 时必需refresh_token

刷新令牌

331


Note

仅当 grant_type 为 authorization_code 时令牌终端节点才返回 refresh_tokencode

如果 grant_type 为 authorization_code则必需code_verifier

证明密钥

如果 grant_type 为 authorization_code 并且使用 PKCE 请求了授权代码则必需


为获取令牌交换授权代码

示例请求

POST httpsmydomainauthus-east-1amazoncognitocomoauth2tokenamp Content-Type=applicationx-www-form-urlencodedamp Authorization=Basic aSdxd892iujendek328uedj grant_type=authorization_codeamp client_id=djc98u3jiedmi283eu928amp code=AUTHORIZATION_CODEamp redirect_uri=commyclientappmyclientredirect

示例响应

HTTP11 200 OK Content-Type applicationjson access_tokeneyJz9sdfsdfsdfsd refresh_tokendn43ud8uj32nk2je id_tokendmcxd329ujdmkemkd349r token_typeBearer expires_in3600

Note

仅当 grant_type 为 authorization_code 时令牌终端节点才返回 refresh_token

为获取访问令牌交换客户端凭证

示例请求

POST httpsmydomainauthus-east-1amazoncognitocomoauth2token gt Content-Type=applicationx-www-form-urlencodedamp Authorization=Basic aSdxd892iujendek328uedj grant_type=client_credentialsamp scope=resourceServerIdentifier1scope1 resourceServerIdentifier2scope2

示例响应

332


HTTP11 200 OK Content-Type applicationjson access_tokeneyJz9sdfsdfsdfsd token_typeBearer expires_in3600

为获取令牌交换具有 PKCE 的授权代码授予

示例请求

POST httpsmydomainauthus-east-1amazoncognitocomoauth2token Content-Type=applicationx-www-form-urlencodedamp Authorization=Basic aSdxd892iujendek328uedj grant_type=authorization_codeamp client_id=djc98u3jiedmi283eu928amp code=AUTHORIZATION_CODEamp code_verifier=CODE_VERIFIERamp redirect_uri=commyclientappmyclientredirect

示例响应


Note


为获取令牌交换刷新令牌

示例请求

POST httpsmydomainauthus-east-1amazoncognitocomoauth2token gt Content-Type=applicationx-www-form-urlencoded Authorization=Basic aSdxd892iujendek328uedj grant_type=refresh_tokenamp client_id=djc98u3jiedmi283eu928amp refresh_token=REFRESH_TOKEN

示例响应

HTTP11 200 OK

333

Amazon Cognito 开发人员指南USERINFO 终端节点

Content-Type applicationjson access_tokeneyJz9sdfsdfsdfsd refresh_tokendn43ud8uj32nk2je id_tokendmcxd329ujdmkemkd349r token_typeBearer expires_in3600

Note



错误响应示例

HTTP11 400 Bad Request Content-Type applicationjsoncharset=UTF-8 errorinvalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type|

invalid_request

请求缺少必需的参数包括不支持的参数值 (除了 unsupported_grant_type 之外) 或者格式错误例如grant_type 是 refresh_token 但未包括 refresh_token

invalid_client

客户端身份验证失败例如客户端的授权标头中包含 client_id 和 client_secret但没有这样的客户端带有 client_id 和 client_secret

invalid_grant

已撤销刷新令牌

授权代码已使用或不存在unauthorized_client

客户端不允许代码授予流或刷新令牌unsupported_grant_type

如果 grant_type 是 authorization_code 或 refresh_token 之外的任意内容则返回

USERINFO 终端节点oauth2userInfo 终端节点将返回有关经过身份验证的用户的信息

GET oauth2userInfo用户池客户端直接对此终端节点发出请求而不通过浏览器

有关更多信息请参阅 OpenID Connect (OIDC) 规范中的 UserInfo 终端节点

334


主题bull 标头中的请求参数 (p 335)bull 示例请求 (p 335)bull 示例正向响应 (p 335)bull 示例负向响应 (p 335)

标头中的请求参数授权持有人ltaccess_tokengt

使用授权标头字段传递访问令牌

必填项

示例请求GET httpsltyour-user-pool-domaingtoauth2userInfo Authorization Bearer ltaccess_tokengt

示例正向响应HTTP11 200 OK Content-Type applicationjsoncharset=UTF-8 sub 248289761001 name Jane Doe given_name Jane family_name Doe preferred_username jdoe email janedoeexamplecom

有关 OIDC 声明的列表请参阅标准声明

示例负向响应无效的请求

HTTP11 400 Bad Request WWW-Authenticate error=invalid_request error_description=Bad OAuth2 request at UserInfo Endpoint

invalid_request

请求缺少必需的参数包括不支持的参数值或者格式错误

令牌无效

HTTP11 401 Unauthorized

335

Amazon Cognito 开发人员指南LOGIN 终端节点

WWW-Authenticate error=invalid_token error_description=Access token is expired disabled or deleted or the user has globally signed out

invalid_token

访问令牌已过期已撤销格式不正确或无效

LOGIN 终端节点login 终端节点让用户登录它加载登录页面并向用户显示为客户端配置的身份验证选项

GET loginlogin 终端节点只支持 HTTPS GET用户池客户端通过系统浏览器发出此请求JavaScript 的系统浏览器包括 Chrome 或 FirefoxAndroid 浏览器包括自定义 Chrome 选项卡iOS 浏览器包括 Safari View 控件

请求参数

client_id

您的应用程序的应用程序客户端 ID要获取应用程序客户端 ID请在用户池中注册该应用程序有关更多信息请参阅配置用户池应用程序客户端 (p 164)


身份验证成功后用户重定向到的 URI它应在指定的 response_type 的 client_id 上配置

必填项response_type

OAuth 响应类型对于代码授予流它可能是 code对于隐式流它可能是 token

必填项state

客户端添加到初始请求的不透明值然后在重定向时将该值返回给客户端


此值可选但强烈建议使用scope

可以是任何系统预留范围或与客户端关联的自定义范围的组合范围必须以空格分隔系统预留范围为openidemailphoneprofile 和 awscognitosigninuseradmin使用的任意范围必须预先与客户端关联否则它将在运行时被忽略


只有在请求 openid 范围时才返回 ID 令牌只有在以下情况下才能对 Amazon Cognito 用户池使用访问令牌awscognitosigninuseradmin范围只有在同时请求了 phone 范围时才能请求emailprofile 和 openid 范围这些范围控制进入 ID 令牌中的声明

可选

336

Amazon Cognito 开发人员指南LOGOUT 终端节点

示例请求提示用户登录

此示例显示登录屏幕

GET httpsmydomainauthus-east-1amazoncognitocomlogin response_type=codeamp client_id=ad398u21ijw3s9w3939amp redirect_uri=httpsYOUR_APPredirect_uriamp state=STATEamp scope=openid+profile+awscognitosigninuseradmin

LOGOUT 终端节点logout 终端节点用于注销用户

GET logoutlogout 终端节点只支持 HTTPS GET用户池客户端一般通过系统浏览器发出此请求在 Android 中这通常是ldquoCustom Chromerdquo选项卡在 iOS 中是ldquoSafari View Controlrdquo

请求参数

client_id

您的应用程序的应用程序客户端 ID要获取应用程序客户端 ID您必须在用户池中注册该应用程序有关更多信息请参阅配置用户池应用程序客户端 (p 164)

必填项logout_uri

您为客户端应用程序注册的注销 URL有关更多信息请参阅配置用户池应用程序客户端 (p 30)

可选

示例请求

示例 1注销并重定向回客户端

此示例将清除现有会话并重定向回客户端两个参数都是必需的

GET httpsmydomainauthus-east-1amazoncognitocomlogout

client_id=ad398u21ijw3s9w3939amplogout_uri=httpsmyclientlogout

示例 2注销并提示用户以其他用户身份登录

此示例使用与 GET oauth2authorize 相同的参数来清除现有会话并显示登录屏幕

GET httpsmydomainauthus-east-1amazoncognitocomlogout response_type=codeamp client_id=ad398u21ijw3s9w3939amp

337

Amazon Cognito 开发人员指南撤销终端节点

redirect_uri=httpsYOUR_APPredirect_uriamp state=STATEamp scope=openid+profile+awscognitosigninuseradmin

撤销终端节点这些区域有revocation终端节点将使提供的令牌无效

POST oauth2撤销revocation 终端节点只支持 HTTPS POST用户池客户端直接对此终端节点发出请求而不通过系统浏览器


授权


Content-Type



t确定

这些区域有刷新tokenthat客户要撤销从刷新令牌发出的访问令牌也会被撤销

必需

撤销请求示例示例

POST revoke HTTP11 Host httpsauth-domainauthus-east-1amazoncognitocom Accept applicationjson Content-Type applicationx-www-form-urlencoded Authorization Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW token=2YotnFZFEjr1zCsicMWpAA

撤销错误响应

成功的响应包含一个空正文错误响应是一个带有错误字段的 JSON 对象并且可能error_description字段

终端节点错误

bull HTTP 400 和错误消息invalid_request如果令牌不存在于请求中或者如果应用程序客户端已禁用该功能则返回

bull HTTP 400 和错误消息unsupported_token_type如果撤销请求中发送的令牌不是刷新令牌则返回bull HTTP 401 和错误消息invalid_client如果客户端凭据无效则返回bull HTTP 200如果令牌已被吊销或客户端提交了无效的令牌

338

Amazon Cognito 开发人员指南身份池 API 参考

Amazon Cognito 身份池 (联合身份) API 参考有了 Amazon Cognito 身份池您的 Web 和移动应用程序用户便可以获得具有有限权限的临时权限Amazon凭据使他们能够访问其他Amazon服务

有关完整的身份池 (联合身份) API 参考请参阅Amazon Cognito API 参考

Amazon Cognito 同步 API 参考Amazon Cognito Sync 是一种Amazon服务和客户端库用于跨设备同步与应用程序相关的用户数据

有关 Amazon Cognito 同步 API 参考的更多信息请参阅Amazon Cognito 同步 API 参考

339


Amazon Cognito 文档历史记录下表介绍了此版本 Amazon Cognito 的文档

bull 原始 API 版本

Amazon Cognito 用户池2021-15

Amazon Cognito 联合身份2014-06-30

Amazon Cognito Sync2014-06-30

变更描述日期

撤销令牌 API 和撤销终端节点您可以使用撤销令牌操作撤消刷新令牌 (p 144)对于用户

2021 年 6 月 10 日

向 GitHub 发布指南降价与所有Amazon文档本指南现在有降价可供查看和评论httpsgithubcomawsdocsamazon-cognito-developer-guide

2021 年 3 月 23 日

多租户最佳实践多租户应用程序的最佳做法已添加到文档中

2021 年 3 月 4 日

访问控制属性 Amazon Cognito 身份池提供访问控制 (AFAC) 属性作为客户授予用户访问Amazon资源的费用授权可以根据身份提供商提供的用户属性进行用户用于与 AmazonCognito 联合

2021 年 1 月 15 日

自定义 SMS 发件人 Lambda 触发器和自定义电子邮件发件人Lambda 触发器

自定义 SMS 发件人 Lambda 触发器和自定义电子邮件发件人Lambda 触发器允许第三方提供商从 Lambda 函数代码中向用户发送电子邮件和 SMS 通知

2020 年 11 月

Amazon Cognito 令牌更新已将更新的过期信息添加到访问ID 和刷新令牌中

2020 年 10 月 29 日

Amazon Cognito Service Quotas Service Quotas 适用于 AmazonCognito 类别配额您可以使用Service Quotas 控制台查看配额使用情况请求增加配额并创建 CloudWatch 警报以监控您的配额使用情况作为此更改的一部分更新了 Amazon Cognito用户池的可用 CloudWatch 指标部分以反映新信息新的节名称为跟踪 CloudWatch 和 ServiceQuotas 中的配额和使用情况

2020 年 10 月 29 日

Amazon Cognito 配额分类配额类别可用于帮助您监控配额使用情况并请求增加配额配额根据常见使用案例分组为类别

2020 年 8 月 17 日

340


变更描述日期

Amazon Cognito Pinpoint 文档更新

添加了新的服务相关角色更新了有关 ldquo将 Amazon Pinpoint 分析与 Amazon Cognito 用户池结合使用rdquo 的说明

2020 年 5 月 13 日

美国支持 AmazonCognitoAmazonGovCLoud

Amazon Cognito 现在支持AmazonGovCloud (US) 区域

2020 年 5 月 13 日

新 Amazon Cognito 专用安全性章节

ldquo安全性rdquo 一章可帮助您的组织深入了解Amazon服务我们的新章节提供有关云及云中安全性的信息

2020 年 4 月 30 日

Amazon Cognito 身份池现在支持Sign in with Apple

Sign in with Apple 功能现已在所有运营 Amazon Cognito 的区域推出cn-north-1 region 除外

2020 年 4 月 7 日

新的 Facebook API 版本控制在 Facebook API 中添加了版本选择

2020 年 4 月 3 日

用户名不区分大小写更新添加了关于在创建用户池之前启用用户名不区分大小写 (p 19)的建议

2020 年 2 月 11 日

有关 Amazon Amplify 的新信息添加了有关的信息集成 AmazonCognito (p 15)与您的 Web 或移动应用程序一起使用AmazonAmplify软件开发工具包和库删除了有关使用之前的Amazon Cognito 开发工具包的信息Amazon Amplify

2019 年 11 月 22 日

用户池触发器的新属性 Amazon Cognito 现在包含clientMetadata参数传递给事件信息中的Amazon Lambda函数用于大多数用户池触发器您可以使用此参数来通过其他数据强化自定义身份验证工作流

2019 年 10 月 4 日

更新限制更新了对 ListUsers API 操作的限制有关更多信息请参阅Amazon Cognito 中的配额 (p 317)

2019 年 6 月 25 日

新限制用户池中的软性限制现在包含对用户数量的限制有关更多信息请参阅Amazon Cognito 中的配额 (p 317)

2019 年 6 月 17 日

Amazon SES 电子邮件设置用于 Amazon Cognito 用户池

您可以配置用户池以便 AmazonCognito 使用 Amazon SES 配置向您的用户发送电子邮件此设置允许 Amazon Cognito 发送比其他可能的交付容量更高的电子邮件有关更多信息请参阅Amazon Cognito 用户池的电子邮件设置 (p 134)

2019 年 4 月 8 日

341


变更描述日期

标记支持添加了有关的信息为 AmazonCognito 资源添加标签 (p 313)

2019 年 3 月 26 日

更改自定义域的证书如果您使用自定义域承载 AmazonCognito 托管 UI则可以根据需要更改此域的 SSL 证书有关更多信息请参阅更改自定义域的SSL 证书 (p 37)

2018 年 12 月 19 日

新限制添加了针对每个用户可以属于的最大组数的新限制有关更多信息请参阅Amazon Cognito 中的配额 (p 317)

2018 年 12 月 14 日

已更新限制更新了用户池的软限制有关更多信息请参阅Amazon Cognito中的配额 (p 317)

2018 年 12 月 11 日

用于验证电子邮件地址和电话号码的文档更新

添加了有关配置用户池以在用户注册您的应用程序时要求进行电子邮件或电话验证的信息有关更多信息请参阅在注册时验证联系人信息 (p 110)

2018 年 11 月 20 日

用于测试电子邮件的文档更新添加了有关在测试应用程序时从Amazon Cognito 启动电子邮件的指导信息有关更多信息请参阅在测试应用程序时发送电子邮件 (p 115)

2018 年 11 月 13 日

Amazon Cognito 高级安全性新增的安全功能使开发人员能够保护他们的应用程序和用户免受恶意的自动程序攻击确保用户账户拒绝被盗用的凭据并根据计算的登录尝试风险自动调整登录所需的难度

2018 年 14 月 6 日

Amazon Cognito 托管 UI 的自定义域

允许开发人员将自己的完全自定义域用于 Amazon Cognito 用户池中的托管 UI

2018 年 4 月 6 日

Amazon Cognito 用户池 OIDC 身份提供商

已添加ldquo通过 OpenID Connect(OIDC) 身份提供商 (如Salesforce 或 Ping Identity) 登录用户池rdquo

2018 年 5 月 17 日

Amazon Cognito 开发人员指南更新

添加了顶层内容 ldquo什么是 AmazonCognitordquo 和 ldquoAmazon Cognito 入门rdquo还添加了常见场景并重新组织了用户池 TOC添加了新的ldquoAmazon Cognito 用户池入门rdquo 部分

2018 年 4 月 6 日

Amazon Cognito Lambda 迁移触发器

添加了介绍 Lambda 迁移触发器功能的页面

2018 年 2 月 8 日

342


变更描述日期

Amazon Cognito 高级安全性测试版

添加的新安全功能可让开发人员保护应用和用户远离恶意自动程序确保已在 Internet 上泄露的凭证无法登录用户账户并根据登录尝试计算出风险据此自动调整登录所需的难度

2017 年 11 月 28 日

Amazon Pinpoint 集成增加了使用 Amazon Pinpoint 为您的 Amazon Pinpoint 用户池应用程序提供分析并丰富 AmazonPinpoint 市场活动的用户数据的能力有关更多信息请参阅将 Amazon Pinpoint 分析与Amazon Cognito 用户池结合使用 (p 107)

2017 年 9 月 26 日

Amazon Cognito 用户池的联合身份和内置应用程序 UI 功能

添加了允许用户通过FacebookGoogleLogin withAmazon 或 SAML 身份提供商登录用户池的功能添加了可自定义的内置应用程序 UI 和带自定义声明的 OAuth 20 支持

2017 年 8 月 10 日

HIPAA 和 PCI 合规性相关的功能变更

添加了允许用户使用电话号码或电子邮件地址作为用户名的功能

2017 年 6 月 7 日

用户组和基于角色的访问控制功能

添加了创建和管理用户组的管理功能管理员可以根据组成员资格和管理员创建的规则将IAM 角色分配给用户有关更多信息请参阅向用户池添加组 (p 118) 和基于角色的访问控制 (p 193)

2016 年 12 月 15 日

文档更新更新了经过开发人员验证的身份(身份池) (p 224) 中的 iOS 代码示例

2016 年 11 月 18 日

文档更新添加了有关用户账户的确认流程的信息有关更多信息请参阅注册并确认用户账户 (p 109)

2016 年 11 月 9 日

创建用户账户功能增加了通过 Amazon Cognito 控制台和 API 创建用户账户的管理功能有关更多信息请参阅以管理员身份创建用户账户 (p 115)

2016 年 10 月 6 日

文档更新更新了显示如何将 AmazonLambda 触发器与用户池结合使用的示例有关更多信息请参阅使用 Lambda 触发器自定义用户池工作流 (p 63)

2016 年 9 月 27 日

343


变更描述日期

用户导入功能添加了 Cognito 用户池的批量导入功能使用此功能将用户从现有身份提供商迁移到 AmazonCognito 用户池有关更多信息请参阅通过 CSV 文件将用户导入用户池中 (p 125)

2016 年 9 月 1 日

Cognito 用户池公开发布添加了 Cognito 用户池功能借助此功能使用用户池创建和维护用户目录并将注册信息和登录信息添加到移动应用程序或Web 应用程序中有关更多信息请参阅Amazon Cognito userpools (p 18)

2016 年 7 月 28 日

SAML 支援使用身份提供商通过安全断言标记语言 20 (SAML 20) 添加了对身份验证的支持有关更多信息请参阅SAML 身份提供商 (身份池) (p 223)

2016 年 6 月 23 日

CloudTrail 集成添加了与 Amazon CloudTrail 的集成有关更多信息请参阅使用记录 Amazon Cognito API 调用Amazon CloudTrail (p 295)

2016 年 2 月 18 日

事件与 Lambda 的集成使您能够执行Amazon Lambda函数以响应 Amazon Cognito中的重要事件有关更多信息请参阅Amazon Cognito 事件 (p 264)

2015 年 4 月 9 日

Amazon Kinesis 的数据流提供了对数据流的控制和了解有关更多信息请参阅AmazonCognito 流 (p 262)

2015 年 3 月 4 日

推送同步启用了对无提示推送同步的支持有关更多信息请参阅AmazonCognito 同步 (p 238)

2014 年 11 月 6 日

OpenID 连接支持启用了对 OpenID Connect 提供商的支持有关更多信息请参阅身份池 (联合身份) 外部身份提供商 (p 203)

2014 年 10 月 23 日

添加了对经过开发人员验证的身份的支持

使拥有自己的身份验证和身份管理系统的开发人员被视为 AmazonCognito 中的身份提供商有关更多信息请参阅经过开发人员验证的身份 (身份池) (p 224)

2014 年 9 月 29 日

Amazon Cognito 正式上市 2014 年 7 月 10 日

344


本文属于机器翻译版本若本译文内容与英语原文存在差异则一律以英文原文为准

cccxlv

Amazon Cognito

Table of Contents

什么是 Amazon Cognito

Amazon Cognito 的特点

Amazon Cognito 入门

区域可用性

Amazon Cognito 定价

使用 Amazon Cognito 控制台


获取 Amazon Web Services 账户和您的根用户凭证

创建 IAM 用户

作为 IAM 用户登录

创建 IAM 用户访问密钥

Amazon Cognito 常见场景

使用用户池进行身份验证

使用用户池访问您的服务器端资源

使用 API Gateway 和 Lambda 访问资源

访问Amazon包含用户池和身份池的服务


访问Amazon AppSyncAmazon Cognito 资源

Amazon Cognito 教程

教程创建用户池

相关资源

教程创建身份池

相关资源

教程清理您的Amazon资源

将与 Web 和移动应用程序集成

Amazon Cognito 身份验证Amazon AmplifyFramework

多租户应用程序最佳实践

基于用户池的多租户

基于应用程序客户端的多租户

基于集团的多租户

基于属性的自定义多租户

多租户安全建议

Amazon Cognito user pools

用户池入门

先决条件注册 Amazon 账户

下一步

步骤 1 创建用户池

下一步

步骤 2 添加应用程序以启用托管 Web UI

下一步

步驟 3 向用户池添加社交登录 (可选)

第 1 步向社交 IdP 注册





第 2 步将社交 IdP 添加到用户池

第 3 步测试社交 IdP 配置

下一步

步骤 4 将使用 SAML 身份提供商的登录添加到用户池 (可选)

后续步骤

使用 Amazon Cognito 托管 UI 进行注册和登录

使用 Amazon Amplify 设置托管 UI

使用 Amazon Cognito 控制台设置托管 UI

配置用户池应用程序客户端








应用程序客户端设置

配置用户池域

将 Amazon Cognito 域用于托管 UI

Prerequisites





将您自己的域用于托管 UI


Prerequisites







自定义内置登录网页和注册网页

为应用程序指定自定义徽标

为应用程序指定 CSS 自定义项

为用户池指定应用程序 UI 自定义设置（Amazon Web Services Management Console）

为用户池指定应用程序 UI 自定义设置（Amazon CLI 和 Amazon API）

为您的用户池定义资源服务器

为您的用户池定义资源服务器 (Amazon Web Services Management Console)

为您的用户池定义资源服务器（Amazon CLI 和 Amazon API）

通过第三方添加用户池登录

向用户池添加社交身份提供商

Prerequisites








向用户池添加 SAML 身份提供商

SAML 用户池 IdP 身份验证流程

选择 SAML 身份提供商名称

为用户池创建和管理 SAML 身份提供商 (Amazon Web Services Management Console)

为用户池创建和管理 SAML 身份提供商（Amazon CLI 和 Amazon API）

将第三方 SAML 身份提供商与 Amazon Cognito 用户池集成

向用户池添加 OIDC 身份提供商

Prerequisites

第 1 步向 OIDC IdP 注册

第 2 步将 OIDC IdP 添加到用户池



第 3 步测试 OIDC IdP 配置

OIDC 用户池 IdP 身份验证流程

指定适用于用户池的身份提供商属性映射

关于映射的需知信息

指定适用于用户池的身份提供商属性映射 (Amazon Web Services Management Console)

指定适用于用户池的身份提供商属性映射（Amazon CLI 和 Amazon API）

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

重要注意事项

添加用户池 Lambda 触发器

用户池 Lambda 触发器事件

用户池 Lambda 触发器通用参数

用户池 Lambda 触发器源

注册后 Lambda 器

注册后 Lambda 流程

客户端注册流程


注册前触 Lambda 参数


注册前响应参数

注册教程

注册前示例自动确认注册的域中的用户

注册前示例自动确认和自动验证所有用户

确认 Lambda 器

确认后 Lambda 流程

客户端确认注册流程



确认后触 Lambda 器参数


确认后响应参数

用户确认教程

确认后示例

身份验证前 Lambda 器

身份验证前 Lambda 流程



身份验证前 Lambda 器参数



身份验证教程

身份验证前示例

身份验证后触 Lambda 器




身份验证后 Lambda 器参数



身份验证教程

身份验证后示例






定义身份验证质询示例










验证身份验证质询响应示例

令牌生成前 Lambda 器


令牌生成前触 Lambda 器参数



令牌生成前示例添加新声明并禁止现有声明

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



迁移用户 Lambda 触发器参数



例如迁移已有密码的用户

自定义消息 Lambda 触发器


自定义消息 Lambda 触发器参数


自定义消息响应参数

注册自定义消息示例

管理员创建用户的自定义消息示例

自定义发件人 Lambda 触发器

Resources

自定义电子邮件 Lambda 触发器


自定义电子邮件发件人 Lambda 触发源

自定义 SMS 发件人 Lambda 触发器

启用CustomSMSSenderLambda 触发器

代码示例



查找 Amazon Cognito 和 Amazon Pinpoint 区域映射

指定 Amazon Pinpoint 分析设置 (Amazon Web Services Management Console）

指定 Amazon Pinpoint 分析设置 (Amazon CLI和AmazonAPI）


注册并确认用户账户

用户账户确认概述

在注册时验证联系人信息


使用电子邮件或电话验证的身份验证流程

在您要求用户确认电子邮件地址和电话号码的情况下

允许用户在您的应用程序中注册但以管理员身份进行确认

计算 SecretHash 值

无需验证电子邮件或电话号码即可确认用户账户

当用户更改其电子邮件或电话号码时应进行验证

针对由管理员或开发人员创建的用户账户的确认和验证过程

针对导入的用户账户的确认和验证过程

在测试应用程序时发送电子邮件

以管理员身份创建用户账户

针对由管理员或开发人员创建的用户的身份验证流程

在 Amazon Web Services Management Console中创建新用户

策略Tab


Users 选项卡

向用户池添加组

向组分配 IAM 角色

将优先级值分配到组

使用组来控制使用 Amazon API Gateway 的权限

组的限制

在 Amazon Web Services Management Console中创建新组

管理和搜索用户账户

查看用户属性

搜索用户属性

使用 Amazon Web Services Management Console搜索用户

使用 ListUsers API 搜索用户

使用 ListUsers API 的示例

恢复用户帐户

忘记密码行为

将用户导入一个用户池

利用用户迁移 Lambda 触发器将用户导入用户池

通过 CSV 文件将用户导入用户池中











上传 csv 文件





在 CloudWatch 控控制台中查看用户池导入结果

查看结果

解析结果


Amazon Cognito 用户池的电子邮件设置

默认电子邮件功能

Amazon SES 电子邮件配置

为您的用户池配置电子邮件

第 1 步使用 Amazon SES 验证您的电子邮件地址

第 2 步将您的账户移出 Amazon SES 沙盒

第 3 步向 Amazon Cognito 授予电子邮件权限



第 4 步配置您的用户池

Amazon Cognito 用户池的 SMS 消息设置

首次在 Amazon Cognito 用户池中设置 SMS 消息

步骤 1 确认您处于 SMS 沙箱中

步骤 2 在 Amazon SNS 中验证 Amazon Cognito 的电话号码

步骤 3 获取向美国电话号码发送 SMS 消息的发起身份

步骤 4 将您的账户从 Amazon SNS 沙箱中移出

步骤 5 在 Amazon Cognito 中完成用户池设置

将令牌与用户池结合使用

使用 ID 令牌

使用访问令牌

访问令牌标头

访问令牌负载

访问令牌签名

使用刷新令牌

撤销RefreshToken

RevokingTokens

启用令牌吊销

Revoke 令牌

验证 JSON Web 令牌

Prerequisites

第 1 步确认 JWT 的结构

第 2 步验证 JWT 签名

第 3 步验证声明

在成功进行用户池身份验证后访问资源

在登录后访问服务器端资源


在登录后使用身份池访问 Amazon 服务

使用 Amazon Web Services Management Console设置用户池

使用 Amazon Web Services Management Console设置身份池

将用户池与身份池集成

用户池参考 (Amazon Web Services Management Console)

添加用户池名称

导入和创建用户与组

配置用户池属性

标准属性

编辑标准属性

用户名和首选用户名

别名概述

使用别名简化用户注册信息和登录



自定义属性

属性权限和范围

添加用户池密码要求

创建密码策略

配置ldquo管理员创建用户策略rdquo

配置电子邮件或电话验证

授权 Amazon Cognito 代表您发送 SMS 消息

配置 SMS 和电子邮件验证消息以及用户邀请消息

消息模板

自定义 SMS 消息


自定义电子邮件验证消息

自定义用户邀请消息

自定义您的电子邮件地址

授权 Amazon Cognito 代表您发送 Amazon SES 电子邮件 (从自定义 FROM 电子邮件地址)

将成本分配标签添加到您的用户池

指定用户池设备跟踪设置

设置记忆设备

使用记忆设备停止多重验证 (MFA)


配置用户池 Lambda 触发器

查看您的用户池创建设置

配置用户池分析

配置应用程序客户端设置

为用户池添加域名

自定义内置应用程序 UI 以便注册用户和让用户登录

为用户池添加资源服务器

为用户池配置身份提供商


允许用户使用 OpenID Connect (OIDC) 身份提供商进行登录


为用户池配置属性映射

管理错误响应

Amazon Cognito 身份池 (联合身份)

Amazon Cognito 身份池入门 (联合身份)

注册 Amazon 账户

在 Amazon Cognito 中创建一个身份池

安装移动或 JavaScript 开发工具包

整合身份提供商

获取凭证

使用身份池 (联合身份)

用户 IAM 角色

经过身份验证和未经身份验证的身份

启用或禁用未经身份验证的身份

更改与身份类型关联的角色

启用或编辑身份验证提供商

删除身份池

从身份池删除身份

管理数据集

为身份创建数据集

删除与身份关联的数据集

批量发布数据

启用推送同步

设置 Amazon Cognito 流

设置 Amazon Cognito 活动

身份池概念 (联合身份)

身份池 (联合身份) 身份验证流程

IAM 角色

设置信任策略

访问策略

访问策略示例

角色信任和权限


将属性用于访问控制与 Amazon Cognito 身份池一起使用

使用属性作为访问控制策略示例

禁用访问控制的属性（控制台）

默认提供商映射

基于角色的访问控制

为角色映射创建角色

授予传递角色权限

使用令牌向用户分配角色

使用基于规则的映射向用户分配角色

基于规则的映射中使用的令牌声明

基于角色的访问控制的最佳实践

获取凭证

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

访问Amazon服务

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

身份池 (联合身份) 外部身份提供商

Facebook (身份池)

设置 Facebook

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

在 Amazon Cognito 联合身份控制台中配置外部提供商

使用 Facebook

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

Login with Amazon (身份池)

设置 Login with Amazon


使用 Login with AmazonAndroid

使用 Login with AmazoniOS - Objective-C

使用 Login with AmazoniOS - Swift

使用 Login with AmazonJavaScript

使用 Login with AmazonXamarin

Google (身份池)

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

Sign in with Apple（身份池）

设置 Sign in with Apple

配置外部提供商Amazon Cognito 联合身份控制台控制台中

在 Amazon Cognito 联合身份 CLI 中以 Sign with Apple 作为提供商的示例

使用 Sign with AppleAndroid

使用 Sign in with AppleiOS - Objective-C

所用 Sign in with AppleiOS - Swift

使用 Sign with AppleJavaScript

使用 Sign with AppleXamarin

Open ID Connect 提供商 (身份池)

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

SAML 身份提供商 (身份池)

为 SAML 提供商配置身份池

配置 SAML 身份提供商

使用 SAML 自定义用户角色

使用 SAML 身份提供商对用户进行身份验证

Android

iOS

经过开发人员验证的身份 (身份池)

了解身份验证流程

定义开发人员提供商名称并将其与身份池关联

实施身份提供商

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

更新登录映射 (仅限 Android 和 iOS)

Android

iOS - Objective-C

iOS - Swift

获取令牌 (服务器端)

连接到现有社交身份

支持在提供商之间转换

Android

iOS - Objective-C

iOS - Swift

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript

最初未经身份验证的用户

切换为经过身份验证的用户

Unity

Xamarin


Amazon Cognito Sync 入门


在 Amazon Cognito 中设置身份池

存储和同步数据

同步数据


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

了解数据集

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

在数据集中读取并写入数据

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

Android

iOS - Objective-C

iOS - Swift

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

处理回调

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

推送同步

创建 Amazon SSimple Notification Service (Amazon SNS) 应用

在 Amazon Cognito 控制台中启用推送同步

在您的应用程序中使用推送同步Android

在您的应用程序中使用推送同步iOS ndash Objective-C

在您的应用程序中使用推送同步iOS ndash Swift

Amazon Cognito 流

Amazon Cognito 事件

Amazon Cognito 中的安全保护

Amazon Cognito 中的数据保护

数据加密

Amazon Cognito 的 Identity and Access Management

Audience

使用身份进行身份验证

Amazon Web Services 账户根用户

IAM 用户和组

IAM 角色

使用策略管理访问

基于身份的策略

基于资源的策略

访问控制列表 (ACL)

其他策略类型

多个策略类型

Amazon Cognito 如何与 IAM 协同工作















Amazon Cognito 的基于身份的策略示例

策略最佳实践

使用 Cognito 控制台

允许用户查看他们自己的权限

限制对特定身份池的控制台访问权限

允许池中的所有身份访问特定数据集

Amazon Cognito 身份和访问疑难解答

我无权在 Cognito 中执行操作

我无权执行 iamPassRole

我想要查看我的访问密钥

我是管理员并希望允许其他人访问 Cognito

我想要允许我的Amazon帐户来访问我的 Cognito 资源

对 Amazon Cognito 使用服务相关角色

Amazon Cognito 的服务相关角色权限

为 Amazon Cognito 创建服务相关角色

编辑 Amazon Cognito 的服务相关角色

删除 Amazon Cognito 的服务相关角色

Amazon Cognito 服务相关角色支持的区域


User池身份验证流程




内置身份验证流程和质询

自定义身份验证流程和质询

在自定义身份验证流程中使用 SRP 密码验证



Amazon Cognito 中的日志记录和监控

跟踪 CloudWatch 和 Service Quotas 中的配额和使用情况

Amazon Cognito 用户池指标

Amazon Cognito 用户池的尺寸

使用 Service Quotas 控制台跟踪指标

使用 CloudWatch 控制台跟踪指标

为配额创建 CloudWatch 警报

使用记录 Amazon Cognito API 调用Amazon CloudTrail

CloudTrail 中的 Amazon Cognito 信息

例如Amazon Cognito 日志文件条目

使用 Amazon CloudTrail Watch Logs Insights 分析 Amazon Cognito 事件

Amazon Cognito 查询示例

Amazon Cognito 的合规性验证

Amazon Cognito 中的恢复能力

区域数据注意事项

Amazon Cognito 中的基础设施安全性

Amazon Cognito 用户池中的配置和漏洞分析

Amazon Cognito 用户池的安全最佳实践

向用户池添加多重验证 (MFA)

Prerequisites

配置多重验证

SMS 文本消息 MFA

TOTP 软件令牌 MFA

关联 TOTP 令牌

验证 TOTP 令牌


删除 TOTP 令牌

向用户池添加高级安全

Prerequisites

配置高级安全功能

检查遭盗用的凭证

使用自适应身份验证


创建设备指纹


提供事件反馈

发送通知消息

查看高级安全指标

通过应用程序启用用户池高级安全






为 Amazon Cognito 资源添加标签

Amazon Cognito 中支持的资源

标签限制

使用 Amazon Cognito 控制台管理标签

Amazon CLI 示例

分配标签

查看标签

删除标签

在创建资源时应用标签

使用 Amazon Cognito API 管理标签

适用于用户池标签的 API 操作

适用于身份池标签的 API 操作

Amazon Cognito 中的配额

操作配额

配额分类

操作特殊处理

类别操作

跟踪配额使用情况

确定配额要求

优化配额

API 请求速率配额

资源配额


不可调整的资源配额

Amazon Cognito API 参考

Amazon Cognito 用户池 API 参考

Amazon Cognito 用户池身份验证 API 参考

AUTHORIZATION 终端节点

GET oauth2authorize

请求参数


授予授权代码





TOKEN 终端节点

POST oauth2token









USERINFO 终端节点

GET oauth2userInfo


示例请求

示例正向响应

示例负向响应

无效的请求

令牌无效

LOGIN 终端节点

GET login

请求参数

LOGOUT 终端节点

GET logout

请求参数

示例请求

撤销终端节点

POST oauth2撤销




撤销错误响应

Amazon Cognito 身份池 (联合身份) API 参考

Amazon Cognito 同步 API 参考

Amazon Cognito 文档历史记录


Amazon Cognito 开发人员指南Copyright copy Amazon Web Services Inc andor its affiliates All rights reserved

Amazon 的商标和商业外观不得用于任何非 Amazon 的商品或服务也不得以任何可能引起客户混淆或者贬低或诋毁Amazon 的方式使用所有非 Amazon 拥有的其他商标均为各自所有者的财产这些所有者可能附属于 Amazon与Amazon 有关联或由 Amazon 赞助也可能不是如此

Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异要查看适用于中国区域的差异请参阅中国的 Amazon Web Services 服务入门
















iii










iv












v















vi
















vii







DynamoDB



主题

1





用户池提供




身份池








2











3


4









访问资源




5








Important




Note







Note



6




user



Note












7


相关主题


8











9







10





11



12





创建用户池





创建身份池




13







删除用户池


14







15



Note









工作量级别



16






工作量级别









17



用户池提供







18






注册Amazon账户





创建用户池



Note


19








Note






Note


Note


20




















21



中
















22



11 选择 Save












23


















24















httpswwwexamplecom






25



Note
















26


Note



作




Note












27











28



配置应用程序


Note






配置域








29








Note









Note


30


















31











回调 URL







Note





32


Note








求






Note






33



Prerequisites










配置用户池域








如需删除域






34








Prerequisites



Note


Note




35





















36



Note






c 选择创建

Note













37










Note

















38















39











Note


40













Note



概述


41



Note


Note




例如












42
















Note


43





Note








44



中

















11 选择 Save

45















择Save

46
















47













httpswwwexamplecom







Note


48




Note



Note











49











Note




50
















Note



51






Note






Note









52









Note









Note


53












删除 IdP





Note





54




Note









Note



55






向 OIDC IdP 注册


链接到 OIDC IdP











Note


56





httpswwwexamplecom













httpswwwexamplecom




57








Note



Note




httpswwwexamplecom




58














59



Note









60




Facebook id

Google sub









Note







61














Note






62



















身份验证事件







注册









63












64


JSON





区域









65


响应

























66

















67






JSON



68



userAttributes



clientMetadata



Note


autoConfirmUser




autoVerifyPhone




平台教程



69


平台教程



JavaScript




Nodejs



70




Python






JSON



Note


Nodejs


71






Python






JSON





72







JSON


73




userAttributes





平台教程





Nodejs





74







JSON



75


Note








JSON


76




userAttributes







平台教程





Nodejs



77



Python




JSON






78





JSON



newDeviceUsed


userAttributes





79



平台教程





Nodejs




Python





JSON


80












81


Note










82









JSON




userAttributes



83


session



Important


challengeResult






challengeName





Nodejs


84










85




JSON



userAttributes






challengeResult


86


challengeMetadata








challengeMetadata




Nodejs



87











JSON

request

88




userAttributes





challengeAnswer




answerCorrect



89


Nodejs















90


JSON




groupConfiguration


groupsToOverride





91





claimsToSuppress






Nodejs




JSON

request response


92


Nodejs




JSON

request response







93





JSON



userName




clientMetadata



userAttributes

此字段为必填

94



Note


Attributes 要求





Note


finalUserStatus



Note


messageAction




forceAliasCreation





95


Nodejs


var user






Note


96













JSON


97



userAttributes






smsMessage



emailSubject






98


Nodejs




JSON



99





Nodejs




JSON


100




Note






Amazon KMS


客户主密钥





Note


101





Important









使用以下命令






102









103












Note



Important






104












代码示例




105
















106







ap-northeast-1

ap-northeast-2

ap-south-1

ap-southeast-1

ap-southeast-2

ca-central-1

eu-central-1

eu-west-1

eu-west-2

us-east-1

us-east-2

us-west-2

us-east-1

us-east-1


us-east-1


us-east-1


us-east-1 eu-west-1

us-east-1

us-east-1

us-east-1


区域映射示例


Note


107





项目

Note



Note








108


Note








户 (p 115)



109








需要重置密码








110














配置用户池





电子邮件


111


电话号码





无














112




















113












114









Important







115






消息

Note






牌



策略Tab



116




Note






117




Note







118














119










120


bull 删除用户










121






Note







122














123











Important




124





Note


基本步骤如下





Note





125








126









示例响应





127



Note





Note









128















bull get-csv-header











129


示例响应





法启动

上传 csv 文件







示例响应


130







示例响应




131






示例响应





示例响应




132


查看结果










解析结果












Note


133

















134


Note



















135

















136





















137
















Note






138









Important





139


Important


ID 令牌标头



密钥 ID (kid）





ID 令牌负载



主题 (sub）


发布者 (iss）



140




受众 (aud）








Note


ID 令牌签名




Important




141


密钥 ID (kid）







主题 (sub）






发布者 (iss）



142








Note




Note



Note






143




Note








144




Note







1 标头

145


2 Payload3 签名

111111111112222222222233333333333




1 解码 ID 令牌





Note




密钥 ID (kid）


146


算法 (alg）








Nodejs








147









148






149





要配置身份池



150








JavaScript




Android



)

iOS - Objective-C


151



iOS - Swift





152











bull address

bull birthdate

bull email

bull family_name

bull gender

bull given_name

bull locale

bull middle_name

bull name

bull nickname

bull phone_number

bull picture


bull profile

bull updated_at

bull website

153


bull zoneinfo


Note



Note



email



phone




Important


preferred_username


编辑标准属性


Important


154











Note



Note





155



Note














Note





156





Note














Note




157














= + - ^ $ [ ] ( ) amp gt lt | _ ~ `


158





Note








Notes




Important



159















Note




160


模板占位符

描述 Token

验证代码

临时密码

用户名 username

Note






描述 Token


城市 city






事件 ID 事件 id



Important





161


Important





Important




Important







162



Note






Important






163








Note








164


Important









Note










165


Warning







Note




项目Note



Note



166









Note


OAuth 20 规范












167




















168

















169








Note





httpswwwexamplecom









170






Note



Note








Note


Note




171




Note













bull InitiateAuth






172



Note


ForgotPassword






ConfirmSignUp


SignUp


导入的用户






173












174




注册Amazon账户







Note





175











Note




176














177


Warning






Warning







178














179












180









181











API 摘要

GetId




182









GetOpenIdToken






关联登录名


合并身份




183



关联登录名


合并身份










Note



184
















AmazonAppSync

AmazonComprehend


AmazonSimpleDB

AmazonTranscribe

185



AmazonRekognition

AmazonSES

AmazonTranslate



AmazonKMS


AmazonSumerian

AmazonSNS



AmazonLambda

AmazonPinpoint

Amazon S3 AmazonSQS



Note









186









187


]









188


]















189















申请

190






权限策略



信任策略


191
















192












Note





193






Note








194







Note








bull cognitogroups

bull cognitoroles


Amazon



195


Facebook



Google


Apple


OpenID


SAML




Important





196


Note


Android








Note





Note


197








Note





Note


iOS - Swift

198





import AWSCore



Note





Note



199







)








200







Note












201


Note






Android








202



JavaScript



Unity



Xamarin






203





设置 Facebook


Android


iOS - Objective-C


iOS - Swift


JavaScript


Unity


Xamarin





204











Note


iOS - Objective-C





205




iOS - Swift






JavaScript







206





)


Note


Unity






207





Xamarin for iOS






208


Note













209











Xamarin for iOS


210










AndroidNote


设置 Google

211












使用 Google







设置 Google


212











使用 Google




iOS - SwiftNote



设置 Google




213








使用 Google




JavaScriptNote


设置 Google





214







使用 Google






Unity设置 Google






215













使用 Google




216


XamarinNote





Note












217












Note






218





















219















220



















Note


221













222


JavaScript


Unity


Xamarin




Note






223










224



















225


setToken(null)














226


end









227











228














229












230


















231














setToken(null)


232


















233










234















235














236





237














238













239















了解数据集

240



Android




iOS - Objective-C




iOS - Swift




JavaScript


Unity




241










JavaScript





242


Xamarin
















243
















244


return task)















245






bull onSuccess()

bull onFailure()

bull onConflict()




onSuccess



onFailure



onConflict





246




onDatasetDeleted



onDatasetMerged














247



















248


















249



















250












datasetsynchronize(




251




)

onSuccess()



onFailure()



onConflict()



var resolved = []







252


onDatasetDeleted()





onDatasetMerged()








OnSyncSuccess



OnSyncFailure


253



OnSyncConflict



OnDatasetDeleted



OnDatasetMerged



254









OnSyncSuccess



OnSyncFailure



255



OnSyncConflict



OnDatasetDeleted



OnDatasetMerged




256






Note









257















258






的







259


]













260















261


)












的


262





配置流


从控制台主页






流内容




263



批量发布
















264


从控制台主页











Lambda 函数示例

265










266












267



静态加密


传输中加密


Note









268














269















270
















271






ACL (p 275) 否

















272










cognito-identity






bull GetId

bull GetOpenIdToken


bull UnlinkIdentity


bull ChangePassword

bull ConfirmDevice


bull ConfirmSignUp

bull DeleteUser


bull ForgetDevice

273


bull ForgotPassword

bull GetDevice

bull GetUser


bull GlobalSignOut

bull InitiateAuth

bull ListDevices




bull SignUp










Resource








274






















支持 ACL 否

275



















276

















277








278








279











Important








280


















bull 资源


拒绝的操作

bull 操作sesList

bull 资源

281










bull 资源









282

















283




JavaScript





)

Android



iOS - Swift



iOS - Objective-C


284








Note



285







Note
















286
















287



Note



Note







Note







288









Note



Note


289



指标描述






单位计数





单位计数



290






单位计数






单位计数

291


指标描述





单位计数





单位计数

292


指标描述




单位计数




单位计数






单位计数

293


指标描述






单位计数


维度描述









294




Note







295







Note










296








常规查询


297






















298











Note





299













300













301






Note


Important





Note




关联 TOTP 令牌



302


Note




验证 TOTP 令牌










删除 TOTP 令牌



Note



303



Note
















304






305





Note







306





选项操作





Note


创建设备指纹








307




308


提供事件反馈



发送通知消息








309











RiskLevel高中低




RiskLevel高中低












310











Maven













311









Note




更改说明日期




2021 年 6 月 1 日


2021 年 3 月 1 日

312



标签可帮助您












313




















314























315



Important














316






操作配额



Note





317




Note



类别

name



可调整




120 是



30 是



25 是


码


30 否



25 是

318


类别

name



可调整






25 否


自动通知


50 是




25 否

319


类别

name



可调整



30 否



15 否



15 否





20 否

320


类别

name



可调整



15 否



15 否



15 否


120 否





321









Note










322



Note






资源配额








资源配额



50

同步资源配额

资源配额



323


资源配额




Token 配额





资源配额



















324


资源配额




资源配额





托管 UI 配额




资源配额







同步资源配额

资源配额



325













326



请求参数

response_type


必填项client_id

客户端 ID








必填项state







可选scope


327










授予授权代码

示例请求


示例响应


Note




示例请求


328



示例响应




示例请求


示例响应




示例请求


示例响应



329

















下所示




330







授权


Content-Type



grant_type

授予类型


必填项client_id

客户端 ID







刷新令牌

331


Note



证明密钥




示例请求


示例响应


Note



示例请求


示例响应

332




示例请求


示例响应


Note



示例请求


示例响应

HTTP11 200 OK

333



Note



错误响应示例


invalid_request


invalid_client


invalid_grant








334





必填项






invalid_request


令牌无效


335



invalid_token




请求参数

client_id






必填项state







可选

336







请求参数

client_id


必填项logout_uri


可选

示例请求








337






授权


Content-Type



t确定


必需



撤销错误响应


终端节点错误



338






339







变更描述日期


2021 年 6 月 10 日


2021 年 3 月 23 日


2021 年 3 月 4 日


2021 年 1 月 15 日



2020 年 11 月


2020 年 10 月 29 日


2020 年 10 月 29 日


2020 年 8 月 17 日

340


变更描述日期



2020 年 5 月 13 日



2020 年 5 月 13 日



2020 年 4 月 30 日



2020 年 4 月 7 日


2020 年 4 月 3 日


2020 年 2 月 11 日


2019 年 11 月 22 日


2019 年 10 月 4 日


2019 年 6 月 25 日


2019 年 6 月 17 日



2019 年 4 月 8 日

341


变更描述日期


2019 年 3 月 26 日


2018 年 12 月 19 日


2018 年 12 月 14 日


2018 年 12 月 11 日



2018 年 11 月 20 日


2018 年 11 月 13 日


2018 年 14 月 6 日



2018 年 4 月 6 日



2018 年 5 月 17 日



2018 年 4 月 6 日



2018 年 2 月 8 日

342


变更描述日期



2017 年 11 月 28 日


2017 年 9 月 26 日



2017 年 8 月 10 日



2017 年 6 月 7 日



2016 年 12 月 15 日


2016 年 11 月 18 日


2016 年 11 月 9 日


2016 年 10 月 6 日


2016 年 9 月 27 日

343


变更描述日期


2016 年 9 月 1 日


2016 年 7 月 28 日


2016 年 6 月 23 日


2016 年 2 月 18 日


2015 年 4 月 9 日


2015 年 3 月 4 日


2014 年 11 月 6 日


2014 年 10 月 23 日



2014 年 9 月 29 日


344



cccxlv

Amazon Cognito

Table of Contents




区域可用性





创建 IAM 用户












相关资源


相关资源











用户池入门


下一步


下一步


下一步









下一步


后续步骤













配置用户池域


Prerequisites







Prerequisites

















Prerequisites















Prerequisites












重要注意事项












注册教程



确认 Lambda 器








用户确认教程

确认后示例








身份验证教程









身份验证教程







































Resources






代码示例























策略Tab


Users 选项卡





组的限制



查看用户属性

搜索用户属性




恢复用户帐户

忘记密码行为














上传 csv 文件






查看结果

解析结果




















使用 ID 令牌

使用访问令牌

访问令牌标头

访问令牌负载

访问令牌签名

使用刷新令牌

撤销RefreshToken

RevokingTokens

启用令牌吊销

Revoke 令牌


Prerequisites















标准属性

编辑标准属性


别名概述




自定义属性



创建密码策略





消息模板









设置记忆设备















管理错误响应







获取凭证


用户 IAM 角色





删除身份池


管理数据集



批量发布数据

启用推送同步





IAM 角色

设置信任策略

访问策略

访问策略示例














获取凭证

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

访问Amazon服务

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin



设置 Facebook

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin


使用 Facebook

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin









Google (身份池)

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin











Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin






Android

iOS





Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift




Android

iOS - Objective-C

iOS - Swift

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript



Unity

Xamarin






同步数据


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

了解数据集

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

Android

iOS - Objective-C

iOS - Swift

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

处理回调

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

推送同步






Amazon Cognito 流




数据加密


Audience



IAM 用户和组

IAM 角色





其他策略类型

多个策略类型

















策略最佳实践














































Prerequisites

配置多重验证



关联 TOTP 令牌

验证 TOTP 令牌


删除 TOTP 令牌


Prerequisites





创建设备指纹


提供事件反馈

发送通知消息










标签限制


Amazon CLI 示例

分配标签

查看标签

删除标签






操作配额

配额分类

操作特殊处理

类别操作


确定配额要求

优化配额


资源配额







GET oauth2authorize

请求参数


授予授权代码





TOKEN 终端节点

POST oauth2token










GET oauth2userInfo


示例请求

示例正向响应

示例负向响应

无效的请求

令牌无效

LOGIN 终端节点

GET login

请求参数

LOGOUT 终端节点

GET logout

请求参数

示例请求

撤销终端节点

POST oauth2撤销




撤销错误响应



















iii










iv












v















vi
















vii







DynamoDB



主题

1





用户池提供




身份池








2











3


4









访问资源




5








Important




Note







Note



6




user



Note












7


相关主题


8











9







10





11



12





创建用户池





创建身份池




13







删除用户池


14







15



Note









工作量级别



16






工作量级别









17



用户池提供







18






注册Amazon账户





创建用户池



Note


19








Note






Note


Note


20




















21



中
















22



11 选择 Save












23


















24















httpswwwexamplecom






25



Note
















26


Note



作




Note












27











28



配置应用程序


Note






配置域








29








Note









Note


30


















31











回调 URL







Note





32


Note








求






Note






33



Prerequisites










配置用户池域








如需删除域






34








Prerequisites



Note


Note




35





















36



Note






c 选择创建

Note













37










Note

















38















39











Note


40













Note



概述


41



Note


Note




例如












42
















Note


43





Note








44



中

















11 选择 Save

45















择Save

46
















47













httpswwwexamplecom







Note


48




Note



Note











49











Note




50
















Note



51






Note






Note









52









Note









Note


53












删除 IdP





Note





54




Note









Note



55






向 OIDC IdP 注册


链接到 OIDC IdP











Note


56





httpswwwexamplecom













httpswwwexamplecom




57








Note



Note




httpswwwexamplecom




58














59



Note









60




Facebook id

Google sub









Note







61














Note






62



















身份验证事件







注册









63












64


JSON





区域









65


响应

























66

















67






JSON



68



userAttributes



clientMetadata



Note


autoConfirmUser




autoVerifyPhone




平台教程



69


平台教程



JavaScript




Nodejs



70




Python






JSON



Note


Nodejs


71






Python






JSON





72







JSON


73




userAttributes





平台教程





Nodejs





74







JSON



75


Note








JSON


76




userAttributes







平台教程





Nodejs



77



Python




JSON






78





JSON



newDeviceUsed


userAttributes





79



平台教程





Nodejs




Python





JSON


80












81


Note










82









JSON




userAttributes



83


session



Important


challengeResult






challengeName





Nodejs


84










85




JSON



userAttributes






challengeResult


86


challengeMetadata








challengeMetadata




Nodejs



87











JSON

request

88




userAttributes





challengeAnswer




answerCorrect



89


Nodejs















90


JSON




groupConfiguration


groupsToOverride





91





claimsToSuppress






Nodejs




JSON

request response


92


Nodejs




JSON

request response







93





JSON



userName




clientMetadata



userAttributes

此字段为必填

94



Note


Attributes 要求





Note


finalUserStatus



Note


messageAction




forceAliasCreation





95


Nodejs


var user






Note


96













JSON


97



userAttributes






smsMessage



emailSubject






98


Nodejs




JSON



99





Nodejs




JSON


100




Note






Amazon KMS


客户主密钥





Note


101





Important









使用以下命令






102









103












Note



Important






104












代码示例




105
















106







ap-northeast-1

ap-northeast-2

ap-south-1

ap-southeast-1

ap-southeast-2

ca-central-1

eu-central-1

eu-west-1

eu-west-2

us-east-1

us-east-2

us-west-2

us-east-1

us-east-1


us-east-1


us-east-1


us-east-1 eu-west-1

us-east-1

us-east-1

us-east-1


区域映射示例


Note


107





项目

Note



Note








108


Note








户 (p 115)



109








需要重置密码








110














配置用户池





电子邮件


111


电话号码





无














112




















113












114









Important







115






消息

Note






牌



策略Tab



116




Note






117




Note







118














119










120


bull 删除用户










121






Note







122














123











Important




124





Note


基本步骤如下





Note





125








126









示例响应





127



Note





Note









128















bull get-csv-header











129


示例响应





法启动

上传 csv 文件







示例响应


130







示例响应




131






示例响应





示例响应




132


查看结果










解析结果












Note


133

















134


Note



















135

















136





















137
















Note






138









Important





139


Important


ID 令牌标头



密钥 ID (kid）





ID 令牌负载



主题 (sub）


发布者 (iss）



140




受众 (aud）








Note


ID 令牌签名




Important




141


密钥 ID (kid）







主题 (sub）






发布者 (iss）



142








Note




Note



Note






143




Note








144




Note







1 标头

145


2 Payload3 签名

111111111112222222222233333333333




1 解码 ID 令牌





Note




密钥 ID (kid）


146


算法 (alg）








Nodejs








147









148






149





要配置身份池



150








JavaScript




Android



)

iOS - Objective-C


151



iOS - Swift





152











bull address

bull birthdate

bull email

bull family_name

bull gender

bull given_name

bull locale

bull middle_name

bull name

bull nickname

bull phone_number

bull picture


bull profile

bull updated_at

bull website

153


bull zoneinfo


Note



Note



email



phone




Important


preferred_username


编辑标准属性


Important


154











Note



Note





155



Note














Note





156





Note














Note




157














= + - ^ $ [ ] ( ) amp gt lt | _ ~ `


158





Note








Notes




Important



159















Note




160


模板占位符

描述 Token

验证代码

临时密码

用户名 username

Note






描述 Token


城市 city






事件 ID 事件 id



Important





161


Important





Important




Important







162



Note






Important






163








Note








164


Important









Note










165


Warning







Note




项目Note



Note



166









Note


OAuth 20 规范












167




















168

















169








Note





httpswwwexamplecom









170






Note



Note








Note


Note




171




Note













bull InitiateAuth






172



Note


ForgotPassword






ConfirmSignUp


SignUp


导入的用户






173












174




注册Amazon账户







Note





175











Note




176














177


Warning






Warning







178














179












180









181











API 摘要

GetId




182









GetOpenIdToken






关联登录名


合并身份




183



关联登录名


合并身份










Note



184
















AmazonAppSync

AmazonComprehend


AmazonSimpleDB

AmazonTranscribe

185



AmazonRekognition

AmazonSES

AmazonTranslate



AmazonKMS


AmazonSumerian

AmazonSNS



AmazonLambda

AmazonPinpoint

Amazon S3 AmazonSQS



Note









186









187


]









188


]















189















申请

190






权限策略



信任策略


191
















192












Note





193






Note








194







Note








bull cognitogroups

bull cognitoroles


Amazon



195


Facebook



Google


Apple


OpenID


SAML




Important





196


Note


Android








Note





Note


197








Note





Note


iOS - Swift

198





import AWSCore



Note





Note



199







)








200







Note












201


Note






Android








202



JavaScript



Unity



Xamarin






203





设置 Facebook


Android


iOS - Objective-C


iOS - Swift


JavaScript


Unity


Xamarin





204











Note


iOS - Objective-C





205




iOS - Swift






JavaScript







206





)


Note


Unity






207





Xamarin for iOS






208


Note













209











Xamarin for iOS


210










AndroidNote


设置 Google

211












使用 Google







设置 Google


212











使用 Google




iOS - SwiftNote



设置 Google




213








使用 Google




JavaScriptNote


设置 Google





214







使用 Google






Unity设置 Google






215













使用 Google




216


XamarinNote





Note












217












Note






218





















219















220



















Note


221













222


JavaScript


Unity


Xamarin




Note






223










224



















225


setToken(null)














226


end









227











228














229












230


















231














setToken(null)


232


















233










234















235














236





237














238













239















了解数据集

240



Android




iOS - Objective-C




iOS - Swift




JavaScript


Unity




241










JavaScript





242


Xamarin
















243
















244


return task)















245






bull onSuccess()

bull onFailure()

bull onConflict()




onSuccess



onFailure



onConflict





246




onDatasetDeleted



onDatasetMerged














247



















248


















249



















250












datasetsynchronize(




251




)

onSuccess()



onFailure()



onConflict()



var resolved = []







252


onDatasetDeleted()





onDatasetMerged()








OnSyncSuccess



OnSyncFailure


253



OnSyncConflict



OnDatasetDeleted



OnDatasetMerged



254









OnSyncSuccess



OnSyncFailure



255



OnSyncConflict



OnDatasetDeleted



OnDatasetMerged




256






Note









257















258






的







259


]













260















261


)












的


262





配置流


从控制台主页






流内容




263



批量发布
















264


从控制台主页











Lambda 函数示例

265










266












267



静态加密


传输中加密


Note









268














269















270
















271






ACL (p 275) 否

















272










cognito-identity






bull GetId

bull GetOpenIdToken


bull UnlinkIdentity


bull ChangePassword

bull ConfirmDevice


bull ConfirmSignUp

bull DeleteUser


bull ForgetDevice

273


bull ForgotPassword

bull GetDevice

bull GetUser


bull GlobalSignOut

bull InitiateAuth

bull ListDevices




bull SignUp










Resource








274






















支持 ACL 否

275



















276

















277








278








279











Important








280


















bull 资源


拒绝的操作

bull 操作sesList

bull 资源

281










bull 资源









282

















283




JavaScript





)

Android



iOS - Swift



iOS - Objective-C


284








Note



285







Note
















286
















287



Note



Note







Note







288









Note



Note


289



指标描述






单位计数





单位计数



290






单位计数






单位计数

291


指标描述





单位计数





单位计数

292


指标描述




单位计数




单位计数






单位计数

293


指标描述






单位计数


维度描述









294




Note







295







Note










296








常规查询


297






















298











Note





299













300













301






Note


Important





Note




关联 TOTP 令牌



302


Note




验证 TOTP 令牌










删除 TOTP 令牌



Note



303



Note
















304






305





Note







306





选项操作





Note


创建设备指纹








307




308


提供事件反馈



发送通知消息








309











RiskLevel高中低




RiskLevel高中低












310











Maven













311









Note




更改说明日期




2021 年 6 月 1 日


2021 年 3 月 1 日

312



标签可帮助您












313




















314























315



Important














316






操作配额



Note





317




Note



类别

name



可调整




120 是



30 是



25 是


码


30 否



25 是

318


类别

name



可调整






25 否


自动通知


50 是




25 否

319


类别

name



可调整



30 否



15 否



15 否





20 否

320


类别

name



可调整



15 否



15 否



15 否


120 否





321









Note










322



Note






资源配额








资源配额



50

同步资源配额

资源配额



323


资源配额




Token 配额





资源配额



















324


资源配额




资源配额





托管 UI 配额




资源配额







同步资源配额

资源配额



325













326



请求参数

response_type


必填项client_id

客户端 ID








必填项state







可选scope


327










授予授权代码

示例请求


示例响应


Note




示例请求


328



示例响应




示例请求


示例响应




示例请求


示例响应



329

















下所示




330







授权


Content-Type



grant_type

授予类型


必填项client_id

客户端 ID







刷新令牌

331


Note



证明密钥




示例请求


示例响应


Note



示例请求


示例响应

332




示例请求


示例响应


Note



示例请求


示例响应

HTTP11 200 OK

333



Note



错误响应示例


invalid_request


invalid_client


invalid_grant








334





必填项






invalid_request


令牌无效


335



invalid_token




请求参数

client_id






必填项state







可选

336







请求参数

client_id


必填项logout_uri


可选

示例请求








337






授权


Content-Type



t确定


必需



撤销错误响应


终端节点错误



338






339







变更描述日期


2021 年 6 月 10 日


2021 年 3 月 23 日


2021 年 3 月 4 日


2021 年 1 月 15 日



2020 年 11 月


2020 年 10 月 29 日


2020 年 10 月 29 日


2020 年 8 月 17 日

340


变更描述日期



2020 年 5 月 13 日



2020 年 5 月 13 日



2020 年 4 月 30 日



2020 年 4 月 7 日


2020 年 4 月 3 日


2020 年 2 月 11 日


2019 年 11 月 22 日


2019 年 10 月 4 日


2019 年 6 月 25 日


2019 年 6 月 17 日



2019 年 4 月 8 日

341


变更描述日期


2019 年 3 月 26 日


2018 年 12 月 19 日


2018 年 12 月 14 日


2018 年 12 月 11 日



2018 年 11 月 20 日


2018 年 11 月 13 日


2018 年 14 月 6 日



2018 年 4 月 6 日



2018 年 5 月 17 日



2018 年 4 月 6 日



2018 年 2 月 8 日

342


变更描述日期



2017 年 11 月 28 日


2017 年 9 月 26 日



2017 年 8 月 10 日



2017 年 6 月 7 日



2016 年 12 月 15 日


2016 年 11 月 18 日


2016 年 11 月 9 日


2016 年 10 月 6 日


2016 年 9 月 27 日

343


变更描述日期


2016 年 9 月 1 日


2016 年 7 月 28 日


2016 年 6 月 23 日


2016 年 2 月 18 日


2015 年 4 月 9 日


2015 年 3 月 4 日


2014 年 11 月 6 日


2014 年 10 月 23 日



2014 年 9 月 29 日


344



cccxlv

Amazon Cognito

Table of Contents




区域可用性





创建 IAM 用户












相关资源


相关资源











用户池入门


下一步


下一步


下一步









下一步


后续步骤













配置用户池域


Prerequisites







Prerequisites

















Prerequisites















Prerequisites












重要注意事项












注册教程



确认 Lambda 器








用户确认教程

确认后示例








身份验证教程









身份验证教程







































Resources






代码示例























策略Tab


Users 选项卡





组的限制



查看用户属性

搜索用户属性




恢复用户帐户

忘记密码行为














上传 csv 文件






查看结果

解析结果




















使用 ID 令牌

使用访问令牌

访问令牌标头

访问令牌负载

访问令牌签名

使用刷新令牌

撤销RefreshToken

RevokingTokens

启用令牌吊销

Revoke 令牌


Prerequisites















标准属性

编辑标准属性


别名概述




自定义属性



创建密码策略





消息模板









设置记忆设备















管理错误响应







获取凭证


用户 IAM 角色





删除身份池


管理数据集



批量发布数据

启用推送同步





IAM 角色

设置信任策略

访问策略

访问策略示例














获取凭证

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

访问Amazon服务

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin



设置 Facebook

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin


使用 Facebook

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin









Google (身份池)

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin











Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin






Android

iOS





Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift




Android

iOS - Objective-C

iOS - Swift

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript



Unity

Xamarin






同步数据


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

了解数据集

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

Android

iOS - Objective-C

iOS - Swift

Unity

Xamarin


Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

处理回调

Android

iOS - Objective-C

iOS - Swift

JavaScript

Unity

Xamarin

推送同步






Amazon Cognito 流




数据加密


Audience



IAM 用户和组

IAM 角色





其他策略类型

多个策略类型

















策略最佳实践














































Prerequisites

配置多重验证



关联 TOTP 令牌

验证 TOTP 令牌


删除 TOTP 令牌


Prerequisites





创建设备指纹


提供事件反馈

发送通知消息










标签限制


Amazon CLI 示例

分配标签

查看标签

删除标签






操作配额

配额分类

操作特殊处理

类别操作


确定配额要求

优化配额


资源配额







GET oauth2authorize

请求参数


授予授权代码





TOKEN 终端节点

POST oauth2token










GET oauth2userInfo


示例请求

示例正向响应

示例负向响应

无效的请求

令牌无效

LOGIN 终端节点

GET login

请求参数

LOGOUT 终端节点

GET logout

请求参数

示例请求

撤销终端节点

POST oauth2撤销




撤销错误响应




Amazon Cognito - 开发人员指南...Amazon Cognito 开发人员指南什么是 Amazon...

Documents

Transcript of Amazon Cognito - 开发人员指南...Amazon Cognito 开发人员指南什么是 Amazon...

Amazon Cognito - 开发人员指南...Amazon Cognito 开发人员指南 什么是 Amazon...

Documents

Transcript of Amazon Cognito - 开发人员指南...Amazon Cognito 开发人员指南 什么是 Amazon...

Amazon Cognito - 开发人员指南...Amazon Cognito 开发人员指南什么是 Amazon...

Transcript of Amazon Cognito - 开发人员指南...Amazon Cognito 开发人员指南什么是 Amazon...