AccessControl 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

存取控管政策可讓您根據特定 IP 位址，允許或拒絕存取 API。

雖然您可以在 API Proxy 流程中的任何位置附加這項政策，但最有可能是在流程開始時 ( Request / ProxyEndpoint / PreFlow) 檢查 IP 位址，甚至在驗證或配額檢查之前。

範例

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

使用須知

除了防範惡意 IP 存取 API，存取權控管政策也能讓您控管正當 IP 的存取權。舉例來說，如果您只允許企業控管的電腦存取測試環境中公開的 API，可以允許內部網路的 IP 位址範圍。在家工作的開發人員可以使用 VPN 存取這些 API。

設定及執行存取權控管政策時，需要完成下列步驟：

• 定義一組「比對規則」，並為每項規則指定「允許」或「拒絕」動作。
• 針對每條比對規則，指定 IP 位址 (SourceAddress 元素)。
  • 請參閱「政策如何選擇要評估的 IP 位址」，判斷您要設定規則來處理郵件中的哪些 IP 位址。
  • 為每個 IP 位址設定遮罩。您可以根據 IP 位址的遮罩值，允許或拒絕存取。請參閱「使用 CIDR 標記法遮蓋 IP 位址」。
• 指定規則的測試順序。
• 系統會依指定順序執行所有比對規則。如果規則相符，系統會執行相應動作，並略過後續相符規則。
  • 如果設定的規則同時包含「允許」和「拒絕」動作，系統會觸發先定義的規則，並略過後續規則 (包含其他動作)。

政策如何選擇要評估的 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 資源。您可以使用「取得機構」API 進行檢查。然後：

• 如果機構的資源清單中沒有 feature.enableMultipleXForwardCheckForACL，表示該資源已設為 false (預設值)。如果將這項屬性設為 false，政策會評估標頭中的最後一個地址 (顯示在追蹤工具中)，也就是 Edge 從最後一次外部 TCP 交握收到的 IP 位址。
• 如果貴機構的 feature.enableMultipleXForwardCheckForACL 設為 true，請設定 <ValidateBasedOn> 元素，決定政策評估的 IP 位址。

變更 feature.enableMultipleXForwardCheckForACL 屬性

Edge 機構管理員可以使用「更新機構屬性」API 設定 feature.enableMultipleXForwardCheckForACL 屬性。

下列 API 範例會在 Edge for Private Cloud 中設定屬性。 如果貴機構已設定其他屬性，請務必一併加入。 否則系統會移除這些別名。

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 for Private Cloud 中，變更 feature.enableMultipleXForwardCheckForACL 屬性的值後，您必須重新啟動訊息處理器，如「 啟動/停止/重新啟動個別元件」一文所述。

Apigee Analytics 中的 X-Forwarded-For 維度

Edge Analytics 會將 X-Forwarded-For 標頭的值寫入 x_forwarded_for_ip 維度。如要判斷向 Edge 發出要求的用戶端 IP，請使用 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

也就是 4 組 8 位元，總共 32 位元。使用 CIDR 時，您可以在 IP 位址中加入 /數字 (1 到 32)，藉此指出範圍，例如：

198.51.100.1/24

在本例中，24 是您要在這項政策中使用的 mask 屬性值。

這個標記表示「前 24 位元保持不變，其餘位元可以是 0 到 255 之間的任何值」。例如：

請注意，遮罩會在第三個群組的結尾出現。這樣一來，一切都會井然有序，本質上是建立類似 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"> 

下表說明所有政策父項元素的共同屬性：

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>

<IgnoreTrueClientIPHeader> 元素

如果將這項政策設為 true，政策會忽略 True-Client-IP 標頭，並評估 X-Forwarded-For 標頭中的 IP 位址，遵循您設定的 X-Forwarded-For 評估行為。

<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 (es)，系統應採取的動作(允許或拒絕存取)。

<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 Proxy 流程中目前可用的變數設定值。

舉例來說，您可以在鍵/值對應 (KVM) 中儲存 IP 位址，並使用 KeyValueMapOperations 政策擷取 IP 位址，然後指派給變數 (例如 kvm.ip.value)。接著，您就可以將該變數用於 IP 位址：

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

使用變數設定遮罩和/或 IP 位址，可讓您在執行階段彈性變更值，不必修改及重新部署 API 代理。

屬性

<ValidateBasedOn> 元素

如果 X-Forwarded-For HTTP 標頭包含多個 IP 位址，請使用這個 ValidateBasedOn 元素控管要評估的 IP 位址。

只有在確定要評估的 IP 位址有效時，才使用這個方法。舉例來說，如果您選擇評估 X-Forwarded-For 標頭中的所有 IP 位址，就必須能夠信任這些位址的有效性，及/或設定全面的「拒絕」或「允許」規則，只允許受信任的 IP 呼叫 API Proxy。

標頭最左側的 IP 位址屬於用戶端，最右側則是將要求轉送至目前服務的伺服器。最右側或最後一個 IP 位址是 Edge 從最後一次外部 TCP 交握收到的位址。

您可以在這個元素中輸入值，決定要檢查標頭中的所有 IP 位址 (預設)、只有第一個 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>