如何排查 API Gateway 中的 HTTP 403 错误？
上次更新日期：2022 年 11 月 21 日
当我调用 Amazon API Gateway API 时，遇到 403 错误。如何排查 API Gateway 中的 403 错误？
简短描述
HTTP 403 响应代码意味着禁止客户端访问有效的 URL。服务器获知请求，但由于客户端问题，无法满足请求。
API Gateway API 可能会出于以下原因返回 403 响应：
| 问题 | 响应标头 | 错误消息 | 根本原因 |
| 访问遭拒 | "x-amzn-errortype" = "AccessDeniedException" | "User is not authorized to access this resource with an explicit deny" | 调用方无权访问使用 API 网关 Lambda 授权方的 API。 |
| 访问遭拒 | "x-amzn-errortype" = "AccessDeniedException" | "User: <user-arn> is not authorized to perform: execute-api:Invoke on resource: <api-resource-arn> with an explicit deny" | 调用方无权访问使用 AWS Identity and Access Management (IAM) 授权的 API。或者，API 附上的资源策略显式拒绝了调用方的访问。 有关更多信息，请参阅 IAM 身份验证和资源策略。 |
| 访问遭拒 | "x-amzn-errortype" = "AccessDeniedException" | "User: anonymous is not authorized to perform: execute-api:Invoke on resource:<api-resource-arn>"（用户：匿名用户无权对资源 <api-resource-arn> 执行 execute-api:Invoke） | 调用方无权访问使用 IAM 授权的 API。或者，API 附上的资源策略未显式允许调用方调用 API。 有关更多信息，请参阅 IAM 身份验证和资源策略。 |
| 访问遭拒 | "x-amzn-errortype" = "AccessDeniedException" | "The security token included in the request is invalid." | 调用方使用无效的 IAM 密钥访问使用 IAM 授权的 API。 |
| 缺少身份验证令牌 | "x-amzn-errortype" = "MissingAuthenticationTokenException" | "Missing Authentication Token" | 在请求中没有找到身份验证令牌。 |
| 身份验证令牌已过期 | "x-amzn-errortype" = "InvalidSignatureException" | "Signature expired" | 请求中的身份验证令牌已过期。 |
| API 密钥无效 | "x-amzn-errortype" = "ForbiddenException" | "Invalid API Key identifier specified" | 调用方对需要 API 密钥的方法使用了无效的 API 密钥。 |
| 签名无效 | "x-amzn-errortype" = "InvalidSignatureException" | "The request signature we calculated does not match the signature you provided.Check your AWS Secret Access Key and signing method." | 当访问使用 IAM 授权的 API 时，请求中的签名与服务器上的签名不匹配。 |
| 已筛选 AWS WAF | "x-amzn-errortype" = "ForbiddenException" | "Forbidden" | 当在 API 中激活 AWS WAF 时，请求被 Web 应用程序防火墙筛选阻止。 |
| 资源路径不存在 | "x-amzn-errortype" = "MissingAuthenticationTokenException" | "Missing Authentication Token" | 没有“授权”标头的请求发送到了不存在的 API 资源路径。 |
| 资源路径不存在 | "x-amzn-errortype" = "IncompleteSignatureException" | "Authorization header requires 'Credential' parameter.Authorization header requires 'Signature' parameter.Authorization header requires 'SignedHeaders' parameter.Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header.Authorization=allow" | 包含“Authorization”标头的请求发送到了不存在的 API 资源路径。 |
| 使用公有 DNS 名称错误调用私有 API | "x-amzn-errortype" = "ForbiddenException" | "Forbidden" | 使用公有 DNS 名称调用 Amazon Virtual Private Cloud (Amazon VPC) 中的私有 API 出错。例如：请求中会缺少 "Host" 或 "x-apigw-api-id" 标头。 有关更多信息，请参阅使用特定于端点的公有 DNS 主机名调用您的私有 API。 |
使用原定设置 execute-api 端点调用具有自定义域名的 REST API |
"x-amzn-errortype" = "ForbiddenException" | "Forbidden" | 在停用默认端点之后，调用者使用默认的 execute-api 端点来调用 REST API。 有关更多信息，请参阅禁用默认 REST API 端点。 |
| 使用无效的客户端证书调用需要双向传输层安全性协议（TLS）的 API Gateway 自定义域名。 | "x-amzn-errortype" = "ForbiddenException" | "Forbidden" | API 请求中提供的客户端证书不是由自定义域名的信任库发布，或者无效。 有关更多信息，请参阅如何排查来自需要双向 TLS 的 API Gateway 自定义域名的 HTTP 403 禁止访问错误？ |
| 调用没有基本路径映射的自定义域名 | "x-amzn-errortype" = "ForbiddenException" |
"Forbidden" | 调用方调用未将基本路径映射到 API 的自定义域。
有关更多信息，请参阅为 REST API 设置自定义域名。 |
当域 URL 包含阶段时，调用启用自定义域的 API |
"x-amzn-errortype" = "MissingAuthenticationTokenException" |
"Missing Authentication Token" |
API 映射指定 API、阶段以及用于映射的路径（可选）。因此，当 API 的阶段映射到自定义域时，您不再需要在 URL 中包含该阶段。 有关更多信息，请参阅使用 REST API 的 API 映射。 |
| 请求 URL 中的阶段无效 |
"x-amzn-errortype" = "ForbiddenException" |
"Forbidden"（禁止访问） | 调用方的请求 URL 包含一个不存在的阶段。验证阶段是否存在以及请求 URL 的拼写是否正确。 有关更多信息，请参阅在 Amazon API Gateway 中调用 REST API。 |
解决方法
考虑错误的根源
如果其他资源报告了 403 错误，说明可能存在导致该错误的其他原因。例如：
- 如果在 Web 浏览器中报告了错误，则该错误可能是由于代理设置不正确所致。如果不允许 HTTP 访问，代理服务器会返回 403 错误。
- 如果 API 前面有其他 AWS 服务，则该服务可能会拒绝请求并在响应中包含 403 错误。例如：Amazon CloudFront。
确定导致错误的原因
如果尚未完成此操作，请为您的 API 设置 Amazon CloudWatch 访问日志记录。然后，在 CloudWatch 中查看 API 的执行日志，以确定请求是否到达 API。
注意：HTTP API 不支持执行日志记录。要排查需要双向 TLS 并调用 HTTP API 的自定义域名返回的 403 错误，您必须执行以下操作：
1. 为自定义域名新建一个 API 映射，仅调用用于测试的 REST API。
2. 查看 CloudWatch 中 REST API 的执行日志，确定导致错误的原因。
3. 识别并解决错误后，将自定义域名的 API 映射重新路由回 HTTP API。
确认请求的资源存在于 API 定义中
注意：如果您在运行 AWS 命令行界面（AWS CLI）命令时遇到错误，请确保您使用的是最新版本的 AWS CLI。
使用 API Gateway 控制台或 AWS CLI 验证以下各项：
- 部署 API 时使用最新的 API 定义。
- 请求的资源存在于 API 定义中。
使用 curl 获取请求和响应详细信息
如果可以重现此错误，可使用 curl -v 命令获取客户端与 API 之间的更多详细信息，如下所示：
curl -X HTTP_VERB -v https://{api_id}.execute-api.{region}.amazonaws.com/{stage_name}/{resource_name}注意：有关更多信息，请参阅 curl 项目网站。
验证请求标头是否正确
如果错误是由无效的 API 密钥导致，则验证是否在请求中发送了“x-api-key”标头。
验证任何接口 Amazon VPC 端点上的 DNS 设置是否正确设置
注意：对于从仅具有接口 VPC 端点的 Amazon VPC 调用的 API，请确认以下内容。
验证是否根据所使用的 API 类型正确设置了接口端点的 DNS 设置。
请记住以下内容：
- 要从 Amazon VPC 内部调用区域 API，必须在接口端点上停用私有 DNS 名称。然后，端点的主机名可以通过公有 DNS 解析。有关更多信息，请参阅在 Amazon API Gateway 中创建私有 API。
- 要使用 API 的私有 DNS 名称从 Amazon VPC 内部调用私有 API，必须在接口端点上激活私有 DNS 名称。然后，接口端点的主机名可以解析为 Amazon VPC 的本地子网资源。有关更多信息，请参阅如何调用私有 API。
注意：如果使用以下任一方法调用私有 API，则不需要设置私有 DNS：
私有 API 的公有 DNS 名称。
-或者-
Amazon Route 53 别名。
查看 API 资源策略
查看 API 的资源策略以验证以下内容：
- （对于从具有接口 VPC 终端节点的 Amazon VPC 中调用的 API）API 的资源策略将 Amazon VPC 或接口端点访问权限授予 API。
- 资源策略的资源规范和格式是否正确。
注意：在保存资源策略时，不验证资源规范。有关示例，请参阅 API Gateway 资源策略示例。 - 允许调用方根据您为 API 定义的身份验证类型调用 API 端点。有关更多信息，请参阅 API Gateway 资源策略如何影响授权工作流程。
查看 HTTP 请求和响应消息
如果可能，请在 Web 浏览器中重现错误。然后，使用浏览器的网络工具捕获 HTTP 请求和响应消息，并对其进行分析以确定错误发生的位置。
注意：要进行离线分析，请以 HTTP 归档 (HAR) 文件格式保存消息。