客户端 IP 解析

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

准确识别 API 请求中的客户端 IP 地址对 Apigee 中的某些功能至关重要，包括 Analytics 和 Advanced API Security 功能（例如滥用行为检测和安全操作）。

在采用代理和负载平衡器的现代网络架构中，客户端 IP 识别过程具有挑战性，因为这些中介可能会掩盖真实的来源 IP 地址。

为了克服这一挑战，Apigee 支持环境级设置，用于指定如何从 X-Forwarded-For (XFF) 标头解析客户端 IP 地址，从而确定与您的网络拓扑和安全要求匹配的 IP 地址对应的标头索引。使用此设置可让您了解环境中所有请求的客户端 IP 地址的确定方式，并实现一致性和控制，从而确保环境中的 Advanced API Security、流程变量和分析变量中客户端 IP 地址的识别一致。

如果未按本页所述配置环境级客户端 IP 解析，系统会使用默认客户端 IP 解析行为填充客户端 IP 地址变量。

默认客户端 IP 地址解析

如果未在环境级别配置客户端 IP 解析，则 ax_resolved_client_ip 维度的默认值将按 Google Analytics 维度中所述的计算方式计算得出。

如果为环境配置了客户端 IP 解析，系统会根据客户端 IP 解析配置设置数据流和 Google Analytics 变量。请参阅为环境设置客户端 IP 解析。

何时为环境设置客户端 IP 解析

虽然无需设置客户端 IP 地址解析，但如果默认客户端 IP 地址解析不符合您的需求，并且您希望替换它以为 Google Analytics、Advanced API Security 或执行任何其他需要一致且可靠的客户端 IP 地址信息的函数提供指定的客户端 IP 地址解析，则可能需要设置客户端 IP 地址解析。

了解客户端 IP 解析配置语法

客户端 IP 解析设置的格式如下：

"clientIpResolutionConfig": {
  "headerIndexAlgorithm": {
     "ipHeaderName" : "X-Forwarded-For",
     "ipHeaderIndex": 2
  }
}
 其中
  • ipHeaderName 是用于客户端 IP 的标头。目前，X-Forwarded-For 是支持的标头值。
  • ipHeaderIndex 是 ipHeaderName 中的索引值。

    正数用于选择从左侧开始的地址（添加到标题中的第一个地址），其中左侧第一个位置为 0，每个后续地址的编号都会增加 1（例如 0, 1, 2）。例如，如果列表为 192.0.2.1, 192.0.2.2, 192.0.2.3，则索引 1 会解析为 192.0.2.2。

    负数用于从右侧（添加到标头中的最后一个地址）选择地址，其中右侧第一个位置为 -1，每个后续地址都会递减 1（例如 -3, -2, -1）。例如，如果列表为 192.0.2.1, 192.0.2.2, 192.0.2.3, 192.0.2.4，则索引 -1 会解析为 192.0.2.4，索引 -2 会解析为 192.0.2.3。

如需详细了解此设置，请参阅 organizations.environment API。

查看客户端 IP 解析配置

您可以使用 Apigee 界面或管理 API 查看环境的当前客户端 IP 解析配置。

使用界面查看客户端 IP 解析配置

如需使用 Cloud 控制台的 Apigee 界面查看客户端 IP 解析设置，请依次选择管理 > 环境，选择相应环境，然后在关于标签页中查看客户端 IP 配置。

Apigee 界面中的客户端 IP 解析

使用 API 查看客户端 IP 解析配置

如需使用 Apigee Management API 查看客户端 IP 解析配置，请向 organizations.environments.get API 发送请求。

为环境设置客户端 IP 解析

为环境设置客户端 IP 解析配置后，系统会使用指定的算法填充 client.resolved.ip 流程变量。Resolved Client IP Google Analytics 维度也是如此。

为环境设置客户端 IP 解析配置后，所做更改可能会影响安全措施规则的现有 Advanced API Security 配置。查看现有规则，并根据需要重新生成这些规则，以便使用新变量和设置。

选择客户端 IP 解析索引时，请注意以下影响：

  • Apigee 到 Apigee 调用不会被视为特殊情况。请务必注意并相应地跳过 IP 数量。
  • 由于 X-Forwarded-For 标头可能会被伪造，因此最好根据客户端和 Apigee 负载均衡器之间的预期跃点数使用正确的索引。恶意用户可以发送预先填充的 X-Forwarded-For 标头。 虽然 XFF 中的第一个 IP 与实际客户端 IP 最接近，但鉴于负载均衡器知道与其连接的 TCP 客户端，XFF 中的最后一个 IP 是最可信的。

如需在环境中设置客户端 IP 解析，请使用 Apigee API Management API 之一在 client_ip_resolution_config 中为环境设置客户端 IP 解析。针对新环境使用 organizations.environments.create。对于现有环境，请使用 updateEnvironment 或 modifyEnvironment。

测试客户端 IP 地址解析

保存新的客户端 IP 配置后，您可以按照以下说明对其进行测试：

  1. 保存新的配置设置后，请至少等待 5 分钟。
  2. 启动调试会话。启用显示所有 FlowInfo 设置。
  3. 在 Proxy Request Flow Started 之前检查 FlowInfo。您应该会在该部分看到捕获的已配置客户端 IP 地址。

在 FlowInfo 中查找以下变量：

  • client_ip_resolution.resolved.ip：解析后的客户端 IP 地址。
  • client_ip_resolution.used.fallback：布尔值。除非 Apigee 因无法使用已配置的客户端 IP 解析而回退到默认客户端 IP 解析，否则此值为 false。例如，如果配置的分辨率指定了标头中不存在的索引。
  • client_ip_resolution.algorithm：用于确定客户端 IP 地址的算法。如果已配置，则为 "HeaderIndexAlgorithm{IpHeaderName:header_name, IpHeaderIndex: $header_index}"。 否则，系统会显示 default。

限制

以下限制适用于环境级客户端 IP 解析：

  • 客户端 IP 解析配置的更新最长可能需要 5 分钟才能生效。
  • 避免频繁（例如每 5 分钟）更改客户端 IP 解析配置，因为这可能会导致性能下降。
  • Apigee Hybrid 目前不支持为环境设置客户端 IP 解析配置。
  • 您可以通过 Apigee 控制台或 API 查看此配置，但只能通过 API 进行设置。
  • 即使没有恶意用户，X-Forwarded-For 列表也依赖于每个代理将正确的信息添加到列表中。该完整列表不在 Apigee 的监督和控制之下，因此设置客户端 IP 解析配置并不能保证能够识别正确的请求 IP 地址。