使用资源服务器的 OAuth 2.0 范围和 API 授权 - Amazon Cognito
关于范围关于资源服务器
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用资源服务器的 OAuth 2.0 范围和 API 授权

在为用户群体配置域后，Amazon Cognito 会自动预置一个 OAuth 2.0 授权服务器和托管 Web UI，其中包含您的应用程序可提供给用户的注册页和登录页。有关更多信息，请参阅添加应用程序客户端并设置托管 UI。您可以选择希望授权服务器添加到访问令牌中的范围。范围授权访问资源服务器和用户数据。

资源服务器 是 OAuth 2.0 API 服务器。为了保护受访问权限保护的资源，它会验证用户群体中的访问令牌所包含的范围是否授权所请求的方法和它所保护的 API 中的路径。它根据令牌签名验证发放者，根据令牌到期时间验证有效性，并根据令牌声明中的范围验证访问级别。用户群体在访问令牌 claim 范围中显示范围。有关 Amazon Cognito 访问令牌中的声明的更多信息，请参阅使用访问令牌。

无论您的用户是本地用户群体还是第三方用户，也无论他们是通过托管 UI 还是 Amazon Cognito 用户群体 API 进行身份验证，您的用户个人资料都可以生成访问令牌，其范围可授权您的应用程序使用用户属性。

关于范围

范围是应用程序可请求的对资源的访问权限的级别。在 Amazon Cognito 访问令牌中，范围由您与用户群体建立的信任提供支持：一个具有已知数字签名的可信访问令牌发放者。用户群体可以生成访问令牌，其范围可以证明您的客户可以管理自己的部分或全部用户个人资料，或者可以从后端 API 检索数据。Amazon Cognito 用户群体使用用户群体预留 API 范围、自定义范围和标准范围来发放访问令牌。

用户群体预留 API 范围

aws.cognito.signin.user.admin 范围将授权 Amazon Cognito 用户群体 API。它授权访问令牌持有者使用 GetUser 和 UpdateUserAttributes API 等操作来查询和更新用户群体用户的所有信息。当您使用 Amazon Cognito 用户群体 API 对用户进行身份验证时，这是您在访问令牌中收到的唯一范围。这也是您读写已授权应用程序客户端读写的用户属性所需的唯一范围。您也可以在发往 对端点授权 的请求中请求此范围。仅此范围不足以向 UserInfo 端点 请求用户属性。对于同时授权用户群体 API 和 用户 userInfo 请求的访问令牌，您必须在一个 /oauth2/authorize 请求中同时请求 openid 和 aws.cognito.signin.user.admin 这两个范围。

自定义范围

自定义范围授权对资源服务器所保护的外部 API 的请求。您可以使用其他类型的范围请求自定义范围。您可以在此页面中找到有关自定义范围的更多信息。

标准范围

使用用户群体 OAuth 2.0 授权服务器（包括托管 UI）验证用户时，必须请求范围。您可以在 Amazon Cognito 授权服务器中对用户群体本地用户和第三方联合用户进行身份验证。标准 OAuth 2.0 范围授权您的应用从您的用户群体的UserInfo 端点中读取用户信息。在 OAuth 模型中，您可以从 userInfo 端点查询用户属性，从而优化您的应用程序，使其能够处理大量的用户属性请求。userInfo 端点返回权限级别的属性，该级别由访问令牌中的范围决定。您可以授权您的应用程序客户端颁发具有以下标准 OAuth 2.0 范围的访问令牌。

openid

OpenID Connect (OIDC) 查询的最小范围。授权 ID 令牌、唯一标识符声明 sub 以及请求其他范围的能力。

注意

当您请求 openid 范围而不请求其他范围时，您的用户群体 ID 令牌和 userInfo 响应将包括您的应用程序客户端可以读取的所有用户属性的声明。当您同时请求 openid 和其他标准范围（例如 profile、email 和 phone）时，ID 令牌和 userInfo 响应的内容将受到其他范围的限制。

例如，如果发送到 对端点授权 的请求带有参数 scope=openid+email，则将返回带有 sub、email 和 email_verified 的 ID 令牌。来自此请求的访问令牌也将从 UserInfo 端点 返回这些属性。带有参数 scope=openid 的请求将在 ID 令牌中返回所有客户端可以读取的属性，userInfo 响应也是如此。

profile

授权应用程序客户端可以读取的所有用户属性。

email

授权用户属性 email 和 email_verified。如果有已明确设置的值，Amazon Cognito 将返回 email_verified。

phone

授权用户属性 phone_number 和 phone_number_verified。

关于资源服务器

资源服务器 API 可能会授予对数据库中信息的访问权限，或者控制您的 IT 资源。Amazon Cognito 访问令牌可以授权访问支持 OAuth 2.0 的 API。Amazon API Gateway REST API 具有对使用 Amazon Cognito 访问令牌进行授权的内置支持。应用程序会将 API 调用中的访问令牌传递到资源服务器。资源服务器将检查访问令牌以确定是否应授予访问权限。

Amazon Cognito 将来可能会更新用户群体访问令牌的架构。如果您的应用程序在将访问令牌传递给 API 之前分析其内容，则您必须对代码进行设计以接受架构的更新。

自定义范围由您定义，它会扩展用户群体的授权功能，以包括与查询和修改用户及其属性无关的目的。例如，如果您有一个照片资源服务器，它可能会定义两个范围：photos.read 用于对照片的读取访问，photos.write 用于写入/删除访问。您可以配置 API 以接受用于授权的访问令牌，并授予 HTTP GET 请求使用 scope 声明中的 photos.read 访问令牌，以及授予 HTTP POST 请求使用 photos.write 访问令牌。这些是自定义范围。

注意

您的资源服务器在处理访问令牌内的任何声明之前必须验证访问令牌的签名和到期日期。有关验证令牌的更多信息，请参阅验证 JSON Web 令牌。有关在 Amazon API Gateway 中验证和使用用户群体令牌的更多信息，请参阅博客将 Amazon Cognito 用户群体与 API Gateway 集成。API Gateway 是用于检查访问令牌和保护您的资源的一个很好的选择。有关 API Gateway Lambda 授权方的更多信息，请参阅使用 API Gateway Lambda 授权方。

概述

利用 Amazon Cognito，您可以创建 OAuth2.0 资源服务器并将自定义范围与它们相关联。访问令牌中的自定义范围可向 API 中的特定操作授权。您可以授权用户群体中的任何应用程序客户端从您的任何资源服务器发布自定义范围。将自定义范围与应用程序客户端相关联，并在来自令牌端点的 OAuth2.0 授权代码授予、隐式授予和客户端凭证授予中请求这些范围。Amazon Cognito 在访问令牌中将自定义范围添加到 scope 声明中。客户端可对其资源服务器使用访问令牌，然后服务器基于令牌中给出的范围做出授权决定。有关访问令牌范围的更多信息，请参阅将令牌与用户池结合使用。

资源服务器流程概述。客户端请求具有自定义范围的授予，用户群体返回具有自定义范围的访问令牌，然后客户端向 API 提供访问令牌。

要获得具有自定义范围的访问令牌，您的应用程序必须向 令牌端点 发出请求以兑换授权代码或请求客户端凭证授予。在托管 UI 中，您还可以通过隐式授予在访问令牌中请求自定义范围。

注意

因为它们是为以用户群体作为 IdP 的人机交互式身份验证而设计的，所以，InitiateAuth 和 AdminInitiateAuth 请求在访问令牌中只使用单个值 aws.cognito.signin.user.admin 生成 scope 声明。

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

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

  • 资源服务器名称：资源服务器的易记名称，如 Solar system object tracker 或 Photo API。

  • 资源服务器标识符：资源服务器的唯一标识符。标识符是您希望与 API 关联的任何名称，例如 solar-system-data。您可以配置更长的标识符，例如 https://solar-system-data-api.example.com，作为对 API URI 路径的更直接引用，但较长的字符串会增加访问令牌的大小。

  • 范围名称：scope 声明中需要的值。例如，sunproximity.read。

  • 描述：范围的友好描述。例如，Check current proximity to sun。

Amazon Cognito 可以在任何用户的访问令牌中包含自定义范围，无论这些用户是用户群体的本地用户还是与第三方身份提供者的联合身份验证用户。在使用包含托管 UI 的 OAuth 2.0 授权服务器进行身份验证时，您可以为用户的访问令牌选择范围。您的用户的身份验证必须从以 scope 作为请求参数之一的对端点授权开始。以下是推荐的资源服务器格式。对于标识符，请使用 API 友好名称。对于自定义范围，请使用它们授权的操作。

resourceServerIdentifier/scopeName

例如，您在柯伊伯带发现了一颗新的小行星，您想通过 solar-system-data API 对其进行注册。授权对小行星数据库进行写操作的范围是 asteroids.add。当您请求授权您注册发现的小行星的访问令牌时，请将 scope HTTPS 请求参数格式设置为 scope=solar-system-data/asteroids.add。

从资源服务器中删除一个范围不会删除其与所有客户端的关联。而是范围标记为非活动。Amazon Cognito 不会为访问令牌添加非活动的范围，但如果您的应用程序请求访问令牌，则会正常进行。如果您稍后再次将范围添加到资源服务器，则 Amazon Cognito 会再次将其写入访问令牌。如果您请求的范围尚未与应用程序客户端关联，则无论您是否将其从用户群体资源服务器中删除，身份验证都会失败。

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

为您的用户池定义资源服务器（Amazon Web Services Management Console）

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

定义资源服务器

  1. 登录 Amazon Cognito 控制台。

  2. 在导航窗格中，选择 User Pools（用户池），然后选择要编辑的用户池。

  3. 选择 App integration（应用程序集成）选项卡，然后查找 Resource servers（资源服务器）。

  4. 选择 Create a resource server（创建资源服务器）。

  5. 输入 Resource server name（资源服务器名称）。例如，Photo Server。

  6. 输入 Resource server identifier（资源服务器识符）。例如，com.example.photos。

  7. 输入您的资源的 Custom scopes（自定义范围），例如 read 和 write。

  8. 对于每个 Scope name（范围名称），输入一个 Description（描述），如 view your photos 和 update your photos。

  9. 选择创建。

您的自定义范围可以在 App integration（应用程序集成）选项卡中进行审查，该选项卡位于 Custom scopes（自定义范围）列中的 Resource servers（资源服务）下。可以使用 App integration（应用程序集成）选项卡为应用程序客户端启用自定义范围，该选项卡位于 App clients（应用程序客户端）下。选择应用程序客户端，查找 Hosted UI settings（托管 UI 设置），然后选择 Edit（编辑）。添加 Custom scopes（自定义范围），然后选择 Save changes（保存更改）。

为您的用户池定义资源服务器（Amazon CLI 和 Amazon API）

使用以下命令可为您的用户池指定资源服务器设置。

创建资源服务器
获取有关您的资源服务器设置的信息
列出用户池的所有资源服务器的相关信息
删除资源服务器
更新资源服务器的设置