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 找到政策結構定義。

錯誤參考資料

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 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>