将 REST API 与 Amazon Cognito 用户池集成

在 API Gateway 中创建新的 API 或选择现有 API。

在主导航窗格中，选择授权方。

选择创建授权方。

要配置新的授权方来使用用户池，请执行以下操作：

1. 在授权方名称中，输入名称。

2. 对于授权方类型，请选择 Cognito。

3. 对于 Cognito 用户群体，请选择您创建 Amazon Cognito 的 AWS 区域并选择可用的用户群体。

   您可以使用阶段变量来定义用户池。对用户池使用以下格式：arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}。

4. 对于令牌来源，输入 Authorization 作为标头名称，以在用户成功登录时传递 Amazon Cognito 所返回的身份令牌或访问令牌。

5. （可选）在令牌验证字段中输入一个正则表达式，以在使用 Amazon Cognito 对请求进行授权之前，验证身份令牌的 aud（受众）字段。请注意，在使用访问令牌时，由于访问令牌不包含 aud 字段，此验证将拒绝请求。

6. 选择创建授权方。

创建了 COGNITO_USER_POOLS 授权方之后，您可以通过提供从用户池预置的身份验证令牌来对其进行测试调用。您可以通过调用 Amazon Cognito 身份开发工具包来获取此身份令牌以执行用户登录。您也可以使用 InitiateAuth 操作。如果您未配置任何授权范围，API Gateway 会将提供的令牌视为身份令牌。

选择资源。选择新方法或选择现有方法。如有必要，请创建资源。

在方法请求选项卡上的方法请求设置下，选择编辑。

对于授权方，从下拉菜单中选择您刚刚创建的 Amazon Cognito 用户群体授权方。

要使用身份令牌，请执行以下操作：

1. 将授权范围保留为空。

2. 如果需要，在集成请求中，在正文映射模板中添加 $context.authorizer.claims['property-name'] 或 $context.authorizer.claims.property-name 表达式，从而将指定的身份声明属性从用户群体传递到后端。对于简单的属性名称，例如 sub 或 custom-sub，两种表示法相同。对于复杂的属性名称，例如 custom:role，不能使用点表示法。例如，以下映射表达式会将声明的 sub 和 email 的标准字段传递到后端：

   {
   	"context" : {
   		"sub" : "$context.authorizer.claims.sub",
   		"email" : "$context.authorizer.claims.email"
   	}
   }

   如果您在配置用户池时声明了自定义声明字段，那么您可以用同样的方式来访问自定义字段。以下示例获取的是声明的自定义 role 字段：

   {
   	"context" : {
   		"role" : "$context.authorizer.claims.role"
       }
   }

   如果自定义声明字段被声明为 custom:role，可以使用以下示例来获取声明的属性：

   {
   	"context" : {
   		"role" : "$context.authorizer.claims['custom:role']"
       }
   }

要使用访问令牌，请执行以下操作：

1. 对于授权范围，输入某个范围的一个或多个全名，该范围在创建 Amazon Cognito 用户池时已配置。例如，根据 为 REST API 创建 Amazon Cognito 授权用户池 中给出的示例，其中一个范围是 https://my-petstore-api.example.com/cats.read。

   在运行时，如果在此步骤的方法上指定的任何范围与在传入令牌中声明的范围匹配，则方法调用成功。否则，调用失败并出现 401 Unauthorized 响应。

2. 选择保存。

对您选择的其他方法重复这些步骤。

为您的 API 创建（或导出）一个 OpenAPI 定义文件。

作为 OpenAPI 3.0 中的 securitySchemes 部分或 Open API 2.0 中的 securityDefinitions 部分，指定 COGNITO_USER_POOLS 授权方 (MyUserPool) JSON 定义，如下所示：

要将身份令牌用于方法授权，请将 { "MyUserPool": [] } 添加到方法的 security 定义，如根资源上的以下 GET 方法所示。

  "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": []
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

要为方法授权使用访问令牌，请将以上安全定义更改为 { "MyUserPool": [resource-server/scope, ...] }：

  "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"]
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

如果需要，您可以使用合适的 OpenAPI 定义或扩展来设置其他 API 配置设置。有关更多信息，请参阅 适用于 API Gateway 的 OpenAPI 扩展。