如何在 Amazon Cognito 中使用自定义范围授予对 API Gateway API 的访问权限？

上次更新日期：2021 年 10 月 12 日

在您的 Amazon Cognito 用户池中使用自定义范围定义资源服务器。然后，为您的 API Gateway API 创建和配置 Amazon Cognito 授权方，以对您的 API 资源请求进行身份验证。

如果您有不同的应用程序客户端，它们需要对您的 API 资源拥有不同级别的访问权限，您可以根据您定义的自定义范围提供不同的访问权限。请考虑不同的应用程序客户端可能需要的粒度访问权限级别，然后据此进行设计。

如果您尚未执行以上操作，请创建这些先决条件：

• Amazon Cognito 用户池，包含用户、应用程序客户端和域名
• API Gateway REST API，包含资源和方法

1. 打开 Amazon Cognito 控制台。
2. 定义资源服务器和自定义范围。
3. 保存您的更改之后，在资源服务器选项卡上，选择配置应用程序客户端设置。
4. 在应用程序客户端设置选项卡上的 OAuth 2.0 下，执行以下操作：
   在允许的 OAuth 流程下，选中隐式授予复选框。
   在允许的自定义范围下，选中您定义的自定义范围所对应的复选框。
   注意：观察自定义范围的格式是否为 resourceServerIdentifier/scopeName。当客户端在 OAuth 2.0 流中请求自定义范围时，该请求必须包含此格式的完整范围标识符。
5. 选择 Save changes (保存更改)。

如果您的移动应用程序具有服务器端组件，则使用授权代码授权流程和 Proof Key for Code Exchange (PKCE)。使用授权代码授权流程，令牌绝不会直接暴露给最终用户，并且也遭到暴露的可能性也较低。

如果您的设置不包含任何服务器端逻辑，则可以使用隐式授权流程。隐式授予不会生成刷新令牌，这可防止刷新令牌暴露给客户端。刷新令牌的有效性较长，用于检索较新的 ID 和访问令牌。
重要提示： 请勿将刷新令牌存储在客户端环境中。

有关更多信息，请参阅应用程序客户端设置术语。有关 Amazon Cognito 用户池 OAuth 2.0 授权的更多信息，请参阅了解 Amazon Cognito 用户池 OAuth 2.0 授权。

要完成这些步骤，请遵循将 REST API 与 Amazon Cognito 用户池集成中的说明。

1. 要创建授权方，请按照使用 API Gateway 控制台创建 COGNITO_USER_POOLS 授权方下面的说明操作。
   注意：创建之后，控制台中会出现一个用于测试您的授权方的选项。此测试需要身份令牌。要在控制台之外使用访问令牌测试您的设置，请参阅本文的稍后部分获取用于测试的用户池访问令牌。
2. 要将授权方与您的 API 集成，请按照在方法上配置 COGNITO_USER_POOLS 授权方下面的说明操作。
   注意：对于 OAuth 范围，请按以下格式输入自定义范围的完整标识符：resourceServerIdentifier/scopeName。
3. 部署您的 API。

使用您的用户池的托管 Web UI 登录 Amazon Cognito 授权服务器并从中检索访问令牌。或者，使用移动和 Web 版 AWS 开发工具包提供的 OAuth 2.0 终端节点实现来检索访问令牌。

注意：当应用程序客户端通过托管 Web UI 请求身份验证时，请求可以包括系统预留范围或您在资源服务器中定义的自定义范围的任意组合。如果客户端不返回任何范围，则身份验证服务器将返回访问令牌，其中包括与客户端关联的所有范围。设计您的应用程序客户端时，请确保客户端将预期范围包含在请求中，以避免授予不必要的权限。

1. 在 Web 浏览器中输入如下 URL：
   https://yourDomainPrefix.auth.region.amazoncognito.com/login?response_type=token&client_id=yourClientId&redirect_uri=redirectUrl
   注意：请将 yourDomainPrefix 和 region 替换为您的用户池的值。在 Amazon Cognito 控制台中的域名选项卡上，您可以找到您的用户池的这些值。
   将 yourClientId 替换为您的应用程序客户端的 ID，并将 redirectUrl 替换为您的应用程序客户端的回调 URL。在控制台中的应用程序客户端设置选项卡上，您可以找到您的用户池的这些值。有关更多信息，请参阅 LOGIN 终端节点。
2. 以您创建的用户的身份登录您的用户池。
3. 从地址栏中的 URL 中复制访问令牌。令牌是一个由字符组成的长字符串，位于 access_token= 之后。

将访问令牌用作授权标头的值来调用您的 API，以进行测试。您可以使用 Postman 应用程序或命令行界面中的 curl。如需关于 curl 的更多信息，请参见 curl 项目网站。

要使用 curl，请运行以下命令：

注意：将 restApiId 替换为 API ID。将 region 替换为您的 API 的 AWS 区域。将 stageName 替换为您的 API 的部署阶段名称。将 resourceName 替换为 API 资源的名称。将 accessToken 替换为您复制的令牌。有关更多信息，请参阅在 Amazon API Gateway 中调用 REST API。

如果一切配置正确，您会收到 200 OK 响应代码。