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 上的 政策結構定義。

錯誤參考資料

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤

執行階段錯誤

執行政策時，可能會發生這些錯誤。

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱「政策錯誤專用變數」。

錯誤回應範例

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