AccessControl 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

存取權控管政策可讓您依據特定 IP 允許或拒絕對 API 的存取權 讓我們看看 DNS 解析 進一步探索內部和外部位址

雖然您可以在 API Proxy 流程的任何位置附加這項政策，不過建議您還是建議您 在流程一開始時檢查 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 位址範圍在家工作的開發人員 存取這些 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> 元素 是，這項政策會評估 X-Forwarded-For 標頭中的 IP 位址。

邊緣會自動填入 X-Forwarded-For 標頭 以及從上次外部 TCP 握手接收的 IP 位址 (例如用戶端 IP 或 或 Cloud Router 路由器如果標頭中有多個 IP 位址， 可能是處理要求的伺服器鏈。不過，位址清單 也可能包含假冒的 IP 位址那麼，政策如何判斷要把 要評估？

貴機構的設定和政策設定會決定 政策評估的 X-Forwarded-For 個位址。

首先，請檢查 feature.enableMultipleXForwardCheckForACL 屬性是否含有 是在貴機構中設定。您可以使用 取得機構 API 進行確認。然後執行下列步驟：

• 如果 feature.enableMultipleXForwardCheckForACL 組織的屬性清單，代表該屬性已設為 false (預設值)。將這個屬性設為 false 之後，政策會評估 最後一個地址 (顯示於 追蹤工具)，也就是 IP 位址 從上次外部 TCP 交握所接收的邊緣。
• 如果貴機構的feature.enableMultipleXForwardCheckForACL 設為 true，請設定 <ValidateBasedOn> 元素，判斷政策要評估的 IP 位址。

變更 feature.enableMultipleXForwardCheckForACL 屬性

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

以下 API 範例會在 Private Cloud 設定 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 for Private Cloud 中 feature.enableMultipleXForwardCheckForACL 資源， 您必須重新啟動訊息處理工具，如 啟動/停止/重新啟動個別元件。

X-Forwarded-For Apigee 數據分析中的維度

邊緣 Analytics 會將 X-Forwarded-For 標頭的值寫入 x_forwarded_for_ip維度。目的是找出產生的用戶端 IP 傳送要求給 Edge，請使用 ax_true_client_ip 中的值，或 ax_resolved_client_ip 個維度。詳情請見 Analytics 指標、維度 和篩選器參考資料。

關於以 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 中，您可以新增 /number (1-32) 附加至 IP 位址，如下所示：

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 屬性外，一併使用 管理 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 屬性可讓您定義如何處理 或是不在比對規則的涵蓋範圍內

<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 Proxy 流程。

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

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

透過變數設定遮罩和/或 IP 位址，可讓您靈活地變更 不必修改並重新部署 API Proxy。

屬性

<ValidateBasedOn>元素

X-Forwarded-For HTTP 標頭含有多個 IP 時 位址，請使用這個 ValidateBasedOn 元素控制 IP 位址 。

除非您確定 IP 位址有效性，否則使用這個方法才能評估 IP 位址 您要求評估的 IP 位址數量舉例來說，假設您選擇全面評估 使用 X-Forwarded-For 標頭中的 IP 位址，就必須能夠信任 以及/或是設定完整的 DENY 或 ALLOW 規則， IP 會呼叫您的 API Proxy。

標頭中最左側的 IP 位址屬於用戶端，最右側的 IP 位址為伺服器。 將要求轉送至目前服務。最右側的或最後一個 IP 位址 是指上次外部 TCP 交握所接收的位址邊緣。

您只要在這個元素中輸入值，就可以決定是否要檢查 Google 日曆中的所有 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>