控制 API Gateway API 访问权限 - Amazon Serverless Application Model
选择控制访问的机制自定义错误响应示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

控制 API Gateway API 访问权限

要控制谁可以访问您的 Amazon API Gateway API，您可以在 Amazon SAM 模板中启用授权。

Amazon SAM 支持多种控制您的 API Gateway API 访问权限的机制。AWS::Serverless::HttpApi 和 AWS::Serverless::Api 资源类型所支持的机制集有所不同。

下表总结了每种资源类型支持的机制。

控制访问的机制 AWS::Serverless::HttpApi AWS::Serverless::Api
Lambda 授权方 ✓ ✓
IAM 权限 ✓
Amazon Cognito 用户群体 ✓ * ✓
API 密钥 ✓
资源策略 ✓
OAuth 2.0/JWT 授权方 ✓

* 您可以使用 Amazon Cognito 作为 AWS::Serverless::HttpApi 资源类型的 JSON Web Token (JWT) 颁发者。

  • Lambda 授权方 – Lambda 授权方（以前称为自定义授权方）是您为控制对 API 的访问而提供的 Lambda 函数。调用 API 时，将使用客户端应用程序提供的请求上下文或授权令牌调用此 Lambda 函数。Lambda 函数会响应调用者是否有权执行所请求的操作。

    AWS::Serverless::HttpApi 和 AWS::Serverless::Api 资源类型均支持 Lambda 授权方。

    有关 AWS::Serverless::HttpApi 的 Lambda 授权方的更多信息，请参阅《API Gateway 开发人员指南》中的将 Amazon Lambda 授权方用于 HTTP API。有关 Lambda 授权方与 AWS::Serverless::Api 的更多信息，请参阅《API Gateway 开发人员指南》中的使用 API Gateway Lambda 授权方。

    有关任一资源类型的 Lambda 授权方的示例，请参阅 Lambda 授权方示例。

  • IAM 权限 – 您可以使用 Amazon Identity and Access Management (IAM) 权限控制谁可以调用您的 API。调用 API 的用户必须使用 IAM 凭证进行身份验证。只有存在与代表 API 调用方的 IAM 用户、包含该用户的 IAM 群组或该用户担任的 IAM 角色关联的 IAM policy 时，对 API 的调用才会成功。

    仅 AWS::Serverless::Api 资源类型支持 IAM 权限。

    有关更多信息，请参阅《API Gateway 开发人员指南》中的使用 IAM 权限控制对 API 的访问。有关示例，请参阅IAM 权限示例。

  • Amazon Cognito 用户群体 – Amazon Cognito 用户群体是 Amazon Cognito 中的用户目录。API 的客户端必须先将用户登录到用户群体，然后为该用户获取身份或访问令牌。然后，客户端使用其中返回的令牌调用 API。只有在所需的令牌有效时，API 调用才会成功。

    AWS::Serverless::Api 资源类型支持 Amazon Cognito 用户群体。AWS::Serverless::HttpApi 资源类型支持使用 Amazon Cognito 作为 JWT 颁发者。

    有关更多信息，请参阅《API Gateway 开发人员指南》中的使用 Amazon Cognito 用户群体作为授权方控制对 REST API 的访问。有关示例，请参阅Amazon Cognito 用户群体示例。

  • API 密钥 – API 密钥是字母数字字符串值，可将它分发给应用程序开发人员（要向其授予对您的 API 的访问权的客户）。

    仅 AWS::Serverless::Api 资源类型支持 API 密钥。

    有关 API 密钥的更多信息，请参阅《API Gateway 开发人员指南》中的创建和使用带 API 密钥的使用计划。有关 API 密钥的示例，请参阅 API 密钥示例。

  • 资源策略 – 资源策略是您可以附加到 API Gateway API 的 JSON 策略文档。使用资源策略控制指定的主体（通常是 IAM 用户或角色）能否调用 API。

    仅 AWS::Serverless::Api 资源类型支持资源策略作为控制 API Gateway API 访问权限的机制。

    有关资源策略的更多信息，请参阅《API Gateway 开发人员指南》中的使用 API Gateway 资源策略控制 API 的访问权限。有关资源策略的示例，请参阅 资源策略示例。

  • OAuth 2.0/JWT 授权方 – 您可以使用 JWT 作为 OpenID Connect (OIDC) 和 OAuth 2.0 框架的一部分来控制对 API 的访问。API Gateway 验证客户端通过 API 请求提交的 JWT，并根据令牌中的令牌验证和（可选）作用域来允许或拒绝请求。

    仅 AWS::Serverless::HttpApi 资源类型支持 OAuth 2.0/JWT 授权方。

    有关更多信息，请参阅《API Gateway 开发人员指南》中的使用 JWT 授权方控制对 HTTP API 的访问。有关示例，请参阅OAuth 2.0/JWT 授权方示例。

选择控制访问的机制

您选择用于控制 API Gateway API 访问权限的机制取决于几个因素。例如，如果您有一个未设置授权或访问控制的全新项目，那么 Amazon Cognito 用户群体可能是您的最佳选择。这是因为在设置用户群体时，还会自动设置身份验证和访问控制。

但是，如果应用程序已经设置了身份验证，那么使用 Lambda 授权方可能是您的最佳选择。这是因为您可以调用现有的身份验证服务并根据响应返回策略文档。此外，如果您的应用程序需要用户群体不支持的自定义身份验证或访问控制逻辑，那么 Lambda 授权方可能是您的最佳选择。

选择使用哪种机制后，请参阅中的示例相应部分，了解如何使用该机制 Amazon SAM 来配置您的应用程序。

自定义错误响应

您可以使用 Amazon SAM 自定义某些 API Gateway 错误响应的内容。仅 AWS::Serverless::Api 资源类型支持自定义 API Gateway 响应。

有关 API Gateway 响应的更多信息，请参阅《API Gateway 开发人员指南》中的 API Gateway 中的网关响应。有关自定义响应的示例，请参阅 自定义响应示例。

示例