作用域、M2M APIs 和资源服务器 - Amazon Cognito

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

作用域、M2M APIs 和资源服务器

为用户池配置域后,Amazon Cognito 会自动配置 OAuth 2.0 授权服务器和托管 Web UI,其中包含您的应用程序可以向用户展示的注册和登录页面。有关更多信息,请参阅添加带有托管 UI 的应用程序客户端。您可以选择希望授权服务器添加到访问令牌中的范围。范围授权访问资源服务器和用户数据。

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

借助 Amazon Cognito,访问令牌中的作用域可以授权访问外部属性APIs或用户属性。您可以向本地用户、联合用户或计算机身份颁发访问令牌。

API授权

以下是您可以使用亚马逊 Cognito 令牌APIs授权请求的一些方法:

访问令牌

将 Amazon Cognito 授权方添加到RESTAPI方法请求配置时,请将授权范围添加到授权方配置中。使用此配置,您将在Authorization标题中API接受访问令牌,并查看它们是否存在可接受的范围。

ID 令牌

当您将有效的身份令牌传递给中的 Amazon Cognito 授权机构时 RESTAPI,APIGateway 会接受请求并将身份令牌内容传递到后端。API

Amazon Verified Permissions

在已验证的权限中,您可以选择创建API链接策略存储库。已验证权限创建并分配一个 Lambda 授权方,该授权方处理您的请求标头中的 ID 或访问令牌。Authorization此 Lambda 授权机构将您的令牌传递到您的策略存储,在那里经过验证的权限将其与策略进行比较,并将允许或拒绝的决定返回给授权者。

M achine-to-machine (M2M) 授权

Amazon Cognito 支持使用机器API身份访问数据的应用程序。用户池中的计算机身份是在应用程序服务器上运行并连接到远程的机密客户端APIs。它们的操作无需用户交互:计划任务、数据流或资产更新。当这些客户端使用访问令牌授权其请求时,它们会执行机器对机器或 M2M 授权。在 M2M 授权中,共享密钥取代访问控制中的用户凭证。

通过 M2M 授权访问API的应用程序必须具有客户端 ID 和客户端密钥。在您的用户池中,您必须构建支持客户端凭据授予的应用程序客户端。要支持客户端凭据,您的应用程序客户端必须具有客户端密钥,并且必须具有用户池域。在此流程中,您的计算机身份直接从中请求访问令牌令牌端点。您只能在访问令牌中授权来自资源服务器的自定义范围,以获得客户端凭据授权。有关设置应用程序客户端的更多信息,请参阅使用应用程序客户端进行特定于应用程序的设置

来自客户端凭证授予的访问令牌是您希望允许您的计算机身份从中请求的操作的可验证声明API。要详细了解访问令牌如何授权API请求,请继续阅读。有关示例应用程序,请参阅使用 Amazon Cognito 和基于 API Gateway 的机器对机器授权。 AWS CDK

M2M 授权的计费模式不同于每月活跃用户 (MAUs) 的计费方式。用户身份验证会产生每位活跃用户的费用,而 M2M 计费则反映了活跃的客户凭证、应用程序客户端和令牌请求总量。有关更多信息,请参阅 Amazon Cognito 定价。要控制 M2M 授权的成本,请优化访问令牌的持续时间和应用程序发出的令牌请求数量。管理用户池令牌到期和缓存有关在 M2M 授权中使用API网关缓存减少对新令牌的请求的方法,请参阅。

有关优化会增加 AWS 账单成本的 Amazon Cognito 操作的信息,请参阅。管理 成本

关于范围

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

用户池的保留API范围

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

自定义范围

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

标准范围

当您使用用户池 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和其他标准范围(例如profileemailphone、和)时,ID 令牌和userInfo响应的内容仅限于其他作用域的限制。

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

配置文件

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

email

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

phone

授权用户属性 phone_numberphone_number_verified

关于资源服务器

资源服务器API可以授予对数据库中信息的访问权限,或者控制您的 IT 资源。亚马逊 Cognito 访问令牌可以授权访问APIs该支持 OAuth 2.0。Amazon API Gateway 内置RESTAPIs了对使用亚马逊 Cognito 访问令牌进行授权的支持。您的应用程序将API调用中的访问令牌传递给资源服务器。资源服务器将检查访问令牌以确定是否应授予访问权限。

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

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

注意

您的资源服务器在处理访问令牌内的任何声明之前必须验证访问令牌的签名和到期日期。有关验证令牌的更多信息,请参阅验证JSON网络令牌。有关在 Amazon Gateway 中验证和使用用户池令牌的更多信息,请参阅博客将 Amazon Cognito 用户池与APIAPI网关集成。APIGateway 是检查访问令牌和保护资源的理想选择。有关API网关 Lambda 授权方的更多信息,请参阅使用网关 L API ambda 授权方。

概述

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

资源服务器流程概述。客户端请求具有自定义范围的授权,用户池返回具有自定义范围的访问令牌,客户端将访问令牌提供给API。

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

注意

因为它们是为以用户池作为 IdP 的人机交互身份验证而设计的 InitiateAuthAdminInitiateAuth并且请求仅在访问令牌中生成具有单scope一值的声明。aws.cognito.signin.user.admin

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

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

  • 资源服务器名称:资源服务器的易记名称,如 Solar system object trackerPhoto API

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

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

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

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

resourceServerIdentifier/scopeName

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

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

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

为您的用户池定义资源服务器(AWS Management Console)

您可以使用为您的用户池定义资源服务器。 AWS 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(自定义范围),例如 readwrite

  8. 对于每个 Scope name(范围名称),输入一个 Description(描述),如 view your photosupdate your photos

  9. 选择创建

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

为用户池定义资源服务器(AWS CLI 和 AWS API)

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

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