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

3 分钟阅读

我想在我的 Amazon API Gateway REST API 上设置一个 Amazon Cognito 用户群体作为授权方。

简短描述

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

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

有关详细信息，请参阅这些主题：

解决方法

以下过程说明如何创建 COGNITO_USER_POOLS 授权方。此示例假设您已创建以下两项：

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

创建 COGNITO_USER_POOLS 授权方

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

测试新的 COGNITO_USER_POOLS 授权方

创建 COGNITO_USER_POOLS 授权方后，请执行以下操作：

1. 在 API Gateway 控制台中，选择新授权方下方的测试按钮。

2. 在测试窗口中，对于授权，输入新 Amazon Cognito 用户群体中的 ID 令牌。

3. 选择测试。

**注意：**如果 ID 令牌正确，测试将返回 200 响应代码。错误的 ID 令牌返回 401 响应代码。

在 API 方法上配置 COGNITO_USER_POOLS 授权方

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

获取授权令牌

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

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

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

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

要使用授权代码授予流程，请执行以下操作：

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

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

**重要事项：**请将 example_domain 替换为您的用户群体的域名。请将 example_app_client_id 替换为您的用户群体的应用程序客户端 ID。请将 example_callback_url 替换为您的回调 URL。

https://example_domain/oauth2/authorize?response_type=code&client_id=example_app_client_id&redirect_uri=example_callback_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 请求，用授权代码交换令牌。有关详细信息，请参阅令牌端点。

用授权代码交换令牌的 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

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 命令时收到错误，请确保您使用的是最新的 AWS CLI 版本。

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

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

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

initiate-auth AWS CLI 命令响应示例

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

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

有关详细信息，请参阅将 Amazon Cognito 与 Web 和移动应用程序集成。

使用 Postman 获取授权令牌

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

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

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

自定义范围可以与 OAuth 2.0 资源服务器相关联。有关资源服务器的详细信息，请参阅为您的用户群体定义资源服务器。

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

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

1. 为您的用户群体定义资源服务器和自定义范围。
对于资源服务器标识符，请提供您的资源所在的 API Gateway 的 HTTPS 端点。

2. 如有必要，配置用户群体应用程序客户端，然后在应用程序客户端设置中添加自定义范围。

**注意：**自定义范围名称的格式为 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。

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