AccessControl 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

通过 AccessControl 政策，您可以允许或拒绝通过特定 IP 地址访问 API。

此政策为标准政策，可部署到任何环境类型。如需了解政策类型以及在每种环境类型中的可用性，请参阅政策类型。

虽然您可以将此政策附加到 API 代理流中的任意位置，但您最可能希望在流开始时检查 IP 地址（请求/ProxyEndpoint/PreFlow），即使在身份验证或配额检查之前也是如此。

您还应该考虑将 Google Cloud Armor 与 Apigee 结合使用，作为保护 API 的替代方式。

示例

以下 IPv4 示例中的掩码值标识匹配规则在允许或拒绝访问时要考虑的四个八位字节（8、16、24、32 位）之一。默认值为 32。如需了解详情，请参阅元素参考中的 mask 属性。

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
       <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="32">192.0.2.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
     </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
      <SourceAddress mask="16">192.0.2.1</SourceAddress>
      <SourceAddress mask="16">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

使用说明

除了保护您的 API 免受来自恶意 IP 地址的攻击外，AccessControl 政策还让您可控制来自合法 IP 地址的访问。例如，如果您只希望企业控制的计算机访问测试环境中公开的 API，则可以允许内部网络的 IP 地址范围。在家办公的开发者可以使用 VPN 访问这些 API。

AccessControl 政策的配置和执行涉及以下各项：

• 定义一组匹配规则，其中包含各自关联的两项操作之一（ALLOW 或 DENY）。
• 对于每个匹配规则，指定 IP 地址（SourceAddress 元素）。
  • 请参阅此政策如何选择要评估的 IP 地址，以确定您要配置规则来处理的消息中的 IP 地址。
  • 为每个 IP 地址配置掩码。您可以根据 IP 地址的掩码值允许或拒绝访问权限。请参阅关于采用 CIDR 表示法的 IP 掩码。
• 指定规则测试顺序。
• 所有匹配规则都按指定顺序执行。规则匹配时，系统会执行相应的操作并跳过以下匹配规则。
  • 如果同一个规则同时配置有 ALLOW 和 DENY 操作，系统会首先触发在顺序中第一个定义的规则，并跳过后续规则（含其他操作）。

此政策如何选择要评估的 IP 地址

IP 地址可以来自请求中的各种来源。例如，True-Client-IP 消息标头可能包含一个 IP 地址，X-Forwarded-For 标头可能包含一个或多个 IP 地址。本部分介绍如何配置 AccessControl 政策，以评估您希望其评估的确切 IP 地址。

AccessControl 政策使用以下逻辑来决定评估哪个 IP 地址：

1. True-Client-IP 标头

政策会首先检查 True-Client-IP 标头中的 IP 地址。如果标头包含有效的 IP 地址，则政策将评估该地址。

2. X-Forwarded-For 标头

如果没有 True-Client-IP 标头，或将 <IgnoreTrueClientIPHeader> 元素设置为 true，则此政策会评估 X-Forwarded-For 标头中的 IP 地址。

Apigee 会使用从上次外部 TCP 握手收到的 IP 地址（例如客户端 IP 或路由器）填充 X-Forwarded-For 标头。如果标头中有多个 IP 地址，则这些地址可能是处理请求的服务器链。但是，地址列表也可能包含一个仿冒 IP 地址。那么，此政策如何知道要评估哪些地址？

Apigee 分析中的 X-Forwarded-For 维度

Apigee Analytics 将 X-Forwarded-For 标头的值写入 x_forwarded_for_ip 维度。如需确定向 Apigee 发出请求的客户端 IP，请使用 ax_resolved_client_ip 维度中的值，但排除 ax_true_client_ip，AccessControl 政策不支持此维度。请参阅分析指标、维度和过滤条件参考文档。

关于采用 CIDR 表示法的 IP 掩码

CIDR 表示法（无类别域间路由）是一种通过掩码来指示一个 IP 地址范围的方法。它同时适用于 IPv4 和 IPv6。下面我们来了解下它的运作原理 为简单起见，我们将在示例中使用 IPv4。

IP 地址是用句点分隔的数字组。在二进制文件中，每个组都是特定位数（对于 IPv4，为 8；对于 IPv6，为 16）。IPv4 地址 198.51.100.1 在二进制文件中如下所示：

11000110.00110011.01100100.00000001

也就是 8 位 4 组，也就是总共 32 位。对于 CIDR，您可以通过向 IP 地址添加 /数字 (1-32) 来指示范围，如下所示：

198.51.100.1/24

在这种情况下，24 是要用于此政策的 mask 属性值的数字。

此表示法表示“保留前 24 位不变，其余位可以是 0 到 255 之间的任何值。”例如：

请注意，掩码会在组 3 末尾处出现。从某种意义上来说，这会使内容变得清晰明快，从而创建这样的掩码：198.51.100.*. 在大多数情况下，使用 8 (IPv4) 和 16 (IPv6) 的倍数将为您提供所需的掩码级别：

IPv4：8、16、24、32

IPv6：16、32、48、64、80、96、112、128

但是，您可以使用其他数字进行更精细的控制，这涉及一些二进制计算。以下示例使用掩码 30，如 198.51.100.1/30 所示，其中最后一个 1 为二进制文件中的 00000001：

在此示例中，将配置设置为 <SourceAddress mask="30">198.51.100.1</SourceAddress> 时，系统将允许（或拒绝）以下 IP 地址，具体取决于您的规则：

• 198.51.100.0
• 198.51.100.1
• 198.51.100.2
• 198.51.100.3

元素参考

元素引用部分描述了 AccessControl 政策的元素和特性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "ALLOW">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
        <MatchRule action = "DENY">
            <SourceAddress mask="24">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

<AccessControl> 属性

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">

<ClientIPVariable> 元素

指定一个流变量，其中包含政策根据 IPRule 进行政策的 IP 地址。如果流变量不包含有效的 IP 地址（ipv4 或 ipv6），则政策将会抛出错误。

假设将流变量设置为 12.31.34.52。在以下示例中，访问被拒绝。如果将该变量设置为 10.11.12.13，则授予访问权限。

<AccessControl name='ACL'>
   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>
   <IPRules noRuleMatchAction = 'DENY'>
     <MatchRule action = 'ALLOW'>
       <SourceAddress mask='32'>10.11.12.13</SourceAddress>
     </MatchRule>
   </IPRules>
</AccessControl>

<IgnoreTrueClientIPHeader> 元素

将此项设置为 true 时，该政策会忽略 True-Client-IP 标头，并根据配置 X-Forwarded-For 评估行为评估 X-Forwarded-For 标头中的 IP 地址。

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control-1</DisplayName>
    <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader>
    ...
</AccessControl>

<IPRules> 元素

包含允许或拒绝 IP 地址的规则的父元素。通过 noRuleMatchAction 属性，您可以定义如何处理匹配规则未涵盖的任何 IP 地址。

<IPRules noRuleMatchAction = "ALLOW">

属性

<IPRules>/<MatchRule> 元素

IP 地址与您定义的 SourceAddress 匹配时要执行的操作（允许或拒绝访问权限）。

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
</IPRules>

属性

<IPRules>/<MatchRule>/<SourceAddress> 元素

客户端的 IP 地址范围。

有效值：有效的 IP 地址（点分十进制表示法）。对于通配符行为，请使用 mask 属性。

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="{variable}">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">{variable}</SourceAddress>
    </MatchRule>
</IPRules>

如上例所示，SourceAddress 元素还支持mask 属性或 IP 地址的消息模板，这意味着您可以使用 API 代理流中当前可用的变量设置值。

例如，您可以将 IP 地址存储在键值对映射 (KVM) 中，然后使用 KeyValueMapOperations 政策检索 IP 地址，并将其分配给变量（例如 kvm.ip.value）。然后，您可以将该变量用于 IP 地址：

<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>

通过变量设置掩码和/或 IP 地址，您可以在运行时灵活地更改值，而无需修改并重新部署 API 代理。

属性

<ValidateBasedOn> 元素

当 X-Forwarded-For HTTP 标头包含多个 IP 地址时，可以使用此 ValidateBasedOn 元素控制评估哪些 IP 地址。

仅当您确定要评估的 IP 地址的有效性时，才使用此方法评估 IP 地址。例如，如果您选择评估 X-Forwarded-For 标头中的所有 IP 地址，则必须能够信任这些地址的有效性，和/或设置全面的 DENY 或 ALLOW 规则，以便仅可信 IP 才会调用您的 API 代理。

标头中最左侧的 IP 地址属于客户端，最右侧是将请求转发到当前服务的服务器。最右边或最后一个 IP 地址是 Apigee 从上次外部 TCP 握手收到的地址。

在此元素中输入的值让您可确定是检查标头中的所有地址（默认）、仅第一个 IP 地址，还是检查最后一个 IP 地址。

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "DENY">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅特定于政策错误的变量。

故障响应示例

{
   "fault":{
     "faultstring":"Access Denied for client ip : 52.211.243.3"
      "detail":{
         "errorcode":"steps.accesscontrol.IPDeniedAccess"
      }
   }
}

故障规则示例

<FaultRule name="IPDeniedAccess">
    <Step>
        <Name>AM-IPDeniedAccess</Name>
        <Condition>(fault.name Matches "IPDeniedAccess") </Condition>
    </Step>
    <Condition>(acl.failed = true) </Condition>
</FaultRule>