如何排查 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) 文件格式保存消息。