如何在 API Gateway REST API 上将 Amazon Cognito 用户群体设置为授权方？

简短描述

有两种方法可以在 API Gateway REST API 上将 Amazon Cognito 用户池设置为授权方：

• 创建 COGNITO_USER_POOLS 授权方。
• 创建 AWS Lambda Authorizer。

您可以使用 ID 令牌或访问令牌进行授权。访问令牌可以在 Amazon Cognito 中使用自定义范围授予对 API Gateway API 的访问权限。Lambda 授权方可以验证 Amazon Cognito 颁发的 ID 令牌和访问令牌中的声明。

有关更多信息，请参阅以下主题：

• Using tokens with user pools
• About resource servers
• 为 REST API 创建 Amazon Cognito 授权用户池

解决方法

先决条件：

• 具有应用程序客户端的 Amazon Cognito 用户池。
• API Gateway REST API 资源。

创建 COGNITO_USER_POOLS 授权方

有关详细信息，请参阅将 REST API 与 Amazon Cognito 用户群体集成。按照使用 API Gateway 控制台创建 COGNITO_USER_POOLS 授权方部分的说明操作。

测试新的 COGNITO_USER_POOLS 授权方

完成以下步骤：

1. 打开 API Gateway 控制台。
2. 在“新授权者”下，选择测试按钮。
3. 在测试窗口中，对于授权，输入新 Amazon Cognito 用户池中的 ID 令牌。
4. 选择测试。
   **注意：**如果 ID 令牌正确，测试将返回 200 响应代码。错误的 ID 令牌返回 401 响应代码。

在 API 方法上配置 COGNITO_USER_POOLS 授权方

有关详细信息，请参阅将 REST API 与 Amazon Cognito 用户群体集成。按照在方法上配置 COGNITO_USER_POOLS 授权方部分的说明进行操作。

获取授权令牌

获取授权令牌的方法有四种：

• 为 Amazon Cognito 配置托管 UI。
• 使用 AWS 命令行界面（AWS CLI）。
• 使用其中一个 AWS SDK。
• 使用 Postman 应用程序。

**注意：**使用授权代码授予设置 Amazon Cognito 托管 UI，这样您的应用程序就可以将代码交换为令牌端点。

如果您使用的是隐式授予类型，则可以从回调 URL 获得授权。回调 URL 附加了隐式流的访问令牌和 ID 令牌参数。确保使用正确的令牌类型。

使用 Amazon Cognito 的托管 UI 获取授权令牌

注意：使用“授权代码授予”流程时，响应类型参数必须为"code"。

要使用授权码授予流程，请完成以下步骤：

1. 发送用于授权代码授予的 GET 请求：

   https://example_domain/oauth2/authorize?response_type=code&client_id=example_app_client_id&redirect_uri=example_callback_url

   **注意：**请将 example_domain 替换为您的用户池的域名。请将 example_app_client_id 替换为您的用户群体的应用程序客户端 ID。请将 example_callback_url 替换为您的回调 URL。请包括 identity_provider 参数，以便端点重定向到联合身份提供者。如果仅为 Amazon Cognito 用户池配置了应用程序客户端，则以下端点将重定向到 /login 端点：

   https://example_domain/login?response_type=code&client_id=example_app_client_id&redirect_uri=example_callback_url

2. 登录您的用户池或联合身份提供商。用户界面将重定向到应用程序客户端的回调中指定的 URL。
   **重要事项：**重定向 URL 包括授权代码，需要将授权代码与令牌端点进行交换才能获取有效令牌。

3. 向 /oauth2/token 端点发送 POST 请求，用授权代码交换令牌。有关详细信息，请参阅 Token endpoint。

用授权代码交换令牌的 POST 请求示例

**注意：**示例 POST 请求使用以下 /oauth2/token 端点：https://example_domain.auth.us-east-1.amazoncognito.com/oauth2/token&

Content-Type='application/x-www-form-urlencoded'&Authorization=Basic ZXhhbXBsZTEyMzQ1Njc4OTA6enl4OTh3N3l2dHNycTY1NHBvMzIx
grant_type=authorization_code&
client_id=example1234567890&
code=AUTHORIZATION_CODE&
redirect_uri=com.myclientapp://myclient/redirect

POST 请求响应示例

HTTP/1.1 200 OK Content-Type: application/json

{
  "access_token":"abCde1example",
  "id_token":"abCde2example",
  "refresh_token":"abCde3example",
  "token_type":"Bearer",
  "expires_in":3600
}

注意：使用隐式授权流程时，响应类型参数必须为"token"。

要使用隐式授权流程，请完成以下步骤：

1. 发送用于隐式授予的 GET 请求：

   https://example_domain/oauth2/authorize?response_type=token&client_id=example_app_client_id&redirect_uri=example_callback_url

   **注意：**请将 example_domain 替换为您的用户池的域名。请将 example_app_client_id 替换为您的用户群体的应用程序客户端 ID。请将 example_callback_url 替换为您的回调 URL。请包括 identity_provider 参数，以便端点重定向到联合身份提供者。如果仅为 Amazon Cognito 用户池配置了应用程序客户端，则以下端点将重定向到 /login 端点：

   https://example_domain/login?response_type=token&client_id=example_app_client_id&redirect_uri=example_callback_url

2. 使用现有用户的用户名和密码登录您的用户池，或创建新用户用于登录。用户界面将重定向到应用程序客户端的回调中指定的 URL。
   注意：重定向 URL 包括 ID 令牌和访问令牌。
   重定向 URL 示例

   https://www.example.com/#id_token=123456789idtoken123456789&access_token=123456789accesstoken123456789expires_in=3600&token_type=Bearer

使用 AWS CLI 获取授权令牌

注意： 如果在运行 AWS CLI 命令时收到错误，请参与 Troubleshoot AWS CLI errors.此外，确保您使用的是最新版本的 AWS CLI。

运行以下 initiate-auth AWS CLI 命令获取授权令牌：

aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=example_user,PASSWORD=example_password --client-id example_app_client_id

**重要事项：**请将 example_user 替换为您的用户名，将 example_password 替换为您的密码，并将 example_app_client_id 替换为您的应用程序客户端 ID。

initiate-auth AWS CLI 命令响应示例

{
  "AuthenticationResult": {
    "AccessToken": "abCde1example",
    "IdToken": "abCde2example",
    "RefreshToken": "abCde3example",
    "TokenType": "Bearer",
    "ExpiresIn": 3600
  },
  "ChallengeParameters": {}
}

使用其中一个 AWS SDK 获取授权令牌

有关更多信息，请参阅 Integrating Amazon Cognito authentication and authorization with web and mobile apps。

使用 Postman 获取授权令牌

使用 Postman 网站的 OAuth 2.0 授权模式获取授权令牌。有关详细信息，请参阅为什么我在创建 Lambda 授权方后收到 API Gateway 401 未经授权错误？

在 Amazon Cognito 用户群体中配置 OAuth 2.0 自定义范围，并在 API Gateway 中验证范围

范围规定了应用程序可以请求资源的访问级别。Amazon Cognito 内置了 OAuth 范围，可以将其配置为允许与用户池关联的应用程序客户端。有关 Amazon Cognito 内置范围的详细信息，请参阅 App client terms。

自定义范围可以与 OAuth 2.0 资源服务器相关联。有关资源服务器的更多信息，请参阅 OAuth 2.0 scopes and API authorization with resource servers。

当您将 Amazon Cognito 与 API Gateway 一起使用时，Amazon Cognito 授权方会对请求进行身份验证并保护资源。将自定义范围与 Amazon Cognito 和 API Gateway 一起使用，可以帮助您提供对 API 资源的不同级别访问。当您公开资源以获取访问令牌范围时，您还有更多控制权。

在用户池中配置资源服务器和 OAuth 2.0 自定义范围

1. 为您的用户池定义资源服务器和自定义范围。
2. 对于资源服务器标识符，请提供您的资源所在的 API Gateway 的 HTTPS 端点。
3. 如有必要，配置用户池应用程序客户端，然后在应用程序客户端设置中添加自定义范围。
   **注意：**自定义范围名称的格式为 resourceServerIdentifier/scopeName

当客户端应用程序在 OAuth 2.0 流中请求自定义范围时，该客户端应用程序必须请求范围的完整标识符。例如，如果资源服务器标识符为 https://myresourceserver.example.com，范围名称为 resources.read，则客户端应用程序必须在运行时系统处请求 https://myresourceserver.example.com/resources.read。

验证 API Gateway 中的 OAuth 2.0 自定义范围

1. 将 REST API 与 Amazon Cognito 用户池集成。
2. 在 API Gateway 控制台中，选择 REST API。
3. 在资源窗格中，选择方法名称。
4. 选择方法请求配置。
5. 从授权下拉列表中，选择 Cognito 授权方。这会自动添加一个名为 OAuth 范围的新字段。
6. 在 OAuth 范围字段中，按照前面提到的格式输入自定义范围的完整标识符。例如，https://myresourceserver.example.com/resources.read。
7. 保存并部署 API。

使用 Postman 或 CURL 测试设置

1. 使用为客户端定义的其中一个 OAuth 2.0 流，从 Amazon Cognito 授权服务器获取访问令牌。
2. 将收到的访问令牌作为请求中的授权标头发送到 API Gateway。

如果一切顺利，而且 API Gateway 确认并验证了访问令牌和自定义范围，那么您将获得 200 OK 响应。

相关信息

使用 Amazon Cognito 联合身份、Amazon Cognito 用户群体和 Amazon API Gateway 保护 API 访问

如何才能解码和验证 Amazon Cognito JSON Web 令牌的签名？

以授权方身份使用 Amazon Cognito 用户群体控制对 REST API 的访问