AccessControl 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

内容

通过访问权限控制政策,您可以允许或拒绝通过特定 IP 地址访问 API。

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

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

示例

以下 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.valuekvm.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 的攻击外,访问权限控制政策还让您可控制合法 IP 访问权限。例如,如果您只希望企业控制的计算机访问测试环境中公开的 API,则可以允许内部网络的 IP 地址范围。在家办公的开发者可以使用 VPN 访问这些 API。

访问权限控制政策的配置和执行涉及以下各项:

  • 定义一组匹配规则,其中包含各自关联的两项操作之一(ALLOW 或 DENY)。
  • 对于每个匹配规则,指定 IP 地址(SourceAddress 元素)。
  • 指定规则测试顺序。
  • 所有匹配规则都按指定顺序执行。规则匹配时,系统会执行相应的操作并跳过以下匹配规则。
    • 如果同一个规则同时配置有 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 地址。

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

您的组织配置和政策配置决定了政策将评估哪些 X-Forwarded-For 地址。

首先,检查了解是否在您的组织设置了 feature.enableMultipleXForwardCheckForACL 属性。您可以使用 Get organization API 进行检查。然后,执行以下操作:

  • 如果您在组织的属性列表中未看到 feature.enableMultipleXForwardCheckForACL,则表示该属性设置为 false(默认值)。如果将此属性设为 false,政策会评估 标头中的最后一个地址(在 跟踪工具),也就是 IP 地址 上次外部 TCP 握手收到的边缘。
  • 如果您组织的 feature.enableMultipleXForwardCheckForACL 设置为 true,请配置 <ValidateBasedOn> 元素以确定政策评估的 IP 地址。

更改 feature.enableMultipleXForwardCheckForACL 属性

Edge Organization Administrator 可以在 <ph type="x-smartling-placeholder"></ph> 更新组织属性 API 以设置 feature.enableMultipleXForwardCheckForACL 属性。

以下 API 示例在 Edge 中为私有云设置属性。 如果贵组织设置了其他属性,请务必也添加这些属性。 否则,系统会将其移除

curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Properties>
        <Property name="feature.enableMultipleXForwardCheckForACL">true</Property>
        <!-- Include other existing properties as well. -->
    </Properties>
</Organization>"

在用于私有云的 Edge 中,更改 feature.enableMultipleXForwardCheckForACL 属性; 您必须重启消息处理器,具体说明请参见 <ph type="x-smartling-placeholder"></ph> 启动/停止/重启各个组件

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

Edge Analytics 会将 X-Forwarded-For 标头的值写入 “x_forwarded_for_ip”维度。要确定是哪个客户端 IP 地址 向 Edge 发出请求,请使用 ax_true_client_ip 中的值或 ax_resolved_client_ip 个维度。如需了解详情,请参阅 分析指标、维度和过滤器参考

关于采用 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

元素参考

元素参考说明了访问权限控制政策的元素和属性。

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

下表介绍了所有政策父元素通用的特性:

属性 说明 默认 状态
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

(可选)使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

不适用 必填
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true,即使在政策失败后,仍可以继续执行流。

false 可选
enabled

设置为 true 可强制执行政策。

设为 false关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。

可选
async

此特性已弃用。

false 已弃用

<DisplayName> 元素

除了用于 name 属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素,则会使用政策的 name 属性的值。

状态 可选
类型 字符串

<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
状态 可选
类型 布尔值

<IPRules> 元素

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

<IPRules noRuleMatchAction = "ALLOW">
默认 不适用
状态 可选
类型 不适用

特性

属性 说明 类型 默认 状态
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>
默认 不适用
状态 可选
类型 不适用

特性

属性 说明 类型 默认 状态
行动

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

有效值: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 代理。

默认 不适用
状态 可选
类型 字符串(仅限单个 IP 地址)

属性

属性 说明 类型 默认 状态
遮盖

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 地址 是 Edge 从上次外部 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
状态 可选
有效值

X_FORWARDED_FOR_ALL_IP(默认)

X_FORWARDED_FOR_FIRST_IP

X_FORWARDED_FOR_LAST_IP

架构

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

错误参考信息

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

运行时错误

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

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

故障变量

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

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

故障响应示例

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

故障规则示例

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