AccessControl 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

政策图标

内容

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

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

视频：观看一段简短视频，详细了解如何允许或拒绝通过特定 IP 地址访问 API。

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

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

示例

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

拒绝 198.51.100.1

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

拒绝来自以下客户端地址的所有请求：198.51.100.1

允许来自任何其他客户端地址的请求。

使用变量拒绝

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

假设您使用键值对映射 (KVM) 存储掩码和 IP 的值。这是在运行时更改 IP 和掩码的便捷方法，无需更新和重新部署 API 代理。您可以使用 KeyValueMapOperations 政策检索包含 kvm.mask.value 和 kvm.ip.value 值的变量（假设您为 KVM 政策中的变量指定的名称包含 KVM 中的掩码和 IP 值）。如果您检索的值是掩码为 24，而 IP 地址为 198.51.100.1，则 AccessControl 政策将拒绝来自 198.51.100 的所有请求。*

允许使用所有其他客户端地址。

拒绝 198.51.100.*

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

拒绝来自以下客户端地址的所有请求：198.51.100.*

允许来自任何其他客户端地址的请求。

198.51..

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

拒绝来自以下客户端地址的所有请求：198.51.*.*

允许来自任何其他客户端地址的请求。

拒绝 198.51.100.*，允许 192.0.2.1

<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>

拒绝来自以下客户端地址的所有请求：198.51.100.*，但允许 192.0.2.1。

允许来自任何其他客户端地址的请求。

允许 198.51..

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

允许来自以下地址的所有请求：198.51.*.*

拒绝来自任何其他客户端地址的请求。

允许多个 IP

<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>

允许来自以下客户端地址的请求：198.51.100.* 192.0.2.* 203.0.113.*

拒绝所有其他地址。

拒绝多个 IP

<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>

拒绝来自以下客户端地址的请求：198.51.100.* 192.0.2.* 203.0.113.*

允许所有其他地址。

允许多个 IP，拒绝多个 IP

<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>

允许：198.51.*.* 192.0.*.* 203.0.*.*

拒绝允许列表的子集：198.51.100.*192.0.2.* 203.0.113.*

使用说明

除了保护您的 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 地址。

对于 Apigee Hybrid，我们建议您在 Kubernetes 集群前面设置负载均衡器。负载均衡器可能是 L7（HTTP 感知）或 L4（TCP 感知）。L7 负载均衡器可以将客户端来源 IP 地址添加到 X-Forwarded-For (XFF) 标头。L4 负载均衡器应配置为使用 PROXY 协议。如需了解如何启用 PROXY 协议支持，请参阅负载均衡器的手册。如需在 Ingress 上启用 PROXY 协议，请参阅 Istio 文档中的原始客户端的来源 IP 地址。

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

1. True-Client-IP 标头

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

警告：如果您要使用 True-Client-IP 标头，请确保完全信任该地址的来源。如果您不能确保标头包含可信地址，请设置 <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader>，以便政策忽略 True-Client-IP 并改为评估 X-Forwarded-For 标头中的 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 之间的任何值。”例如：

请保持原样不变	最后一个组的可能值
198.51.100.	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：

请保持原样不变	可能的值
11000110.00110011.01100100.000000（前 30 位）	00000000、00000001、00000010 或 00000011
198.51.100.	0、1、2 或 3

在此示例中，将配置设置为 <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>

默认	不适用
Presence	可选
类型	流变量

<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>

默认	false
Presence	可选
类型	布尔值

<IPRules> 元素

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

<IPRules noRuleMatchAction = "ALLOW">

默认	不适用
Presence	可选
类型	不适用

属性

属性	说明	类型	默认	Presence
noRuleMatchAction	未解析指定的匹配规则（不匹配）时将执行的操作（允许或拒绝访问权限）。有效值：ALLOW 或 DENY	字符串	允许	必需

<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>

默认	不适用
Presence	可选
类型	不适用

属性

属性	说明	类型	默认	Presence
action	未解析指定的匹配规则（不匹配）时将执行的操作（允许或拒绝访问权限）。有效值：ALLOW 或 DENY	字符串	允许	必需

说明

类型

默认

Presence

action

未解析指定的匹配规则（不匹配）时将执行的操作（允许或拒绝访问权限）。

有效值：ALLOW 或 DENY

字符串

允许

必需

<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 代理。

默认	不适用
Presence	可选
类型	字符串（仅限单个 IP 地址）

属性

属性说明类型默认 Presence

掩码

属性	说明	类型	默认	Presence
掩码	`mask` 属性是一种用于指明允许或拒绝的 IP 地址范围的方法。掩码等同于使用 CIDR 表示法（无类别域间路由）。例如： `<SourceAddress mask="24">198.51.100.1</SourceAddress>` 它相当于以下 CIDR 表示法： 198.51.100.1/24 有效值： IPv4：1-32 IPv6：1-128 零 (0) 值仅对 IP 0.0.0.0 有效，因此不实用。使用变量设置掩码 `mask` 属性还支持消息模板，这意味着您可以使用 API 代理流中当前可用的变量来设置值。例如，您可以将掩码值存储在 KVM 中，然后使用 KeyValueMapOperations 政策检索掩码并将其分配给变量。如需使用变量设置 IP 掩码，请使用以下格式（假设变量名为 `kvm.mask.value`）： `mask="{kvm.mask.value}"`	整数	不适用	必需

mask 属性是一种用于指明允许或拒绝的 IP 地址范围的方法。掩码等同于使用 CIDR 表示法（无类别域间路由）。例如：

<SourceAddress mask="24">198.51.100.1</SourceAddress>

它相当于以下 CIDR 表示法：

198.51.100.1/24

有效值：

IPv4：1-32

IPv6：1-128

零 (0) 值仅对 IP 0.0.0.0 有效，因此不实用。

使用变量设置掩码

mask 属性还支持消息模板，这意味着您可以使用 API 代理流中当前可用的变量来设置值。例如，您可以将掩码值存储在 KVM 中，然后使用 KeyValueMapOperations 政策检索掩码并将其分配给变量。如需使用变量设置 IP 掩码，请使用以下格式（假设变量名为 kvm.mask.value）：

mask="{kvm.mask.value}"

整数

不适用

必需

<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>

默认 X_FORWARDED_FOR_ALL_IP

Presence 可选

有效值

默认	`X_FORWARDED_FOR_ALL_IP`
Presence	可选
有效值	`X_FORWARDED_FOR_ALL_IP`（默认） `X_FORWARDED_FOR_FIRST_IP` `X_FORWARDED_FOR_LAST_IP`

X_FORWARDED_FOR_ALL_IP（默认）

X_FORWARDED_FOR_FIRST_IP

X_FORWARDED_FOR_LAST_IP

架构

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

错误参考信息

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

运行时错误

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

故障代码	HTTP 状态	原因	修复
`accesscontrol.IPDeniedAccess`	`403`	客户端 IP 地址或 API 请求中传递的 IP 地址与在访问权限控制政策的 `<MatchRule>` 元素内的 `<SourceAddress>` 元素中指定的 IP 地址匹配，并且 `<MatchRule>` 元素的 `action` 属性设置为 `DENY`。
`accesscontrol.InvalidIPAddressInVariable`	`500`	`<ClientIPVariable>` 中的流变量包含无效的 IP 地址。

故障变量

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

变量	位置	示例
`fault.name="fault_name"`	`fault_name` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name Matches "IPDeniedAccess"`
`acl.policy_name.failed`	`policy_name` 是抛出故障的政策的用户指定名称。	`acl.AC-AllowAccess.failed = true`

故障响应示例

注意：进行故障处理时，最佳做法是捕获故障响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

{
   "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>

AccessControl 政策

内容

示例

拒绝 198.51.100.1

使用变量拒绝

拒绝 198.51.100.*

198.51.*.*

拒绝 198.51.100.*，允许 192.0.2.1

允许 198.51.*.*

允许多个 IP

拒绝多个 IP

允许多个 IP，拒绝多个 IP

使用说明

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

1. True-Client-IP 标头

2. X-Forwarded-For 标头

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

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

元素参考

<AccessControl> 属性

<ClientIPVariable> 元素

<IgnoreTrueClientIPHeader> 元素

<IPRules> 元素

属性

<IPRules>/<MatchRule> 元素

属性

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

属性

<ValidateBasedOn> 元素

架构

错误参考信息

运行时错误

故障变量

故障响应示例

故障规则示例

198.51..

允许 198.51..