AccessControl 政策

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

内容

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

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

示例

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

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

• 定义一组匹配规则，其中包含各自关联的两项操作之一（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 地址。

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 之间的任何值。”例如：

请注意，掩码会在组 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

元素参考

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

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

<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 地址 是 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>

架构

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

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault variables

These variables are set when a runtime error occurs. For more information, see Variables specific to policy errors.

Example fault response

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

Example fault rule

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