AccessControl 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

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

影片:請觀看短片,進一步瞭解如何允許或拒絕透過特定 IP 位址存取 API。

雖然您可以將這項政策附加到 API Proxy 流程中的任何位置,但還是可能會在流程開始時 ( 要求 / ProxyEndpoint / PreFlow) 檢查 IP 位址,即使是在驗證或配額檢查前也要檢查。

範例

以下 IPv4 範例中的遮罩值可識別允許或拒絕存取時,由四個八個位元 (8、16、24、32 位元) 視為比對規則所考量的。預設值為 32。詳情請參閱元素參考資料中的 mask 屬性。

拒絕 198.51.100.1

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

拒絕所有來自用戶端位址的要求:198.51.100.1

允許來自其他用戶端位址的要求。

使用變數拒絕

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

假設您使用鍵/值對應 (KVM) 儲存遮蓋和 IP 的值。這是在執行階段變更 IP 和遮蓋的便利方法,而不必更新及重新部署 API Proxy。您可以使用 KeyValueMapOperations 政策擷取含有 kvm.mask.valuekvm.ip.value 值的變數 (假設這是您 KVM 政策中的變數命名,其中包含遮罩的值和 KVM 中的 IP 值)。如果您擷取的值是 24 供遮罩使用,而值是 198.51.100.1 的 IP 位址,則 AccessControl 政策會拒絕來自 198.51.100 的所有要求。*

其他用戶端位址皆可使用。

拒絕 198.51.100。*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

拒絕所有來自用戶端位址的要求:198.51.100。*

允許來自其他用戶端位址的要求。

198.51.*.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
       <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

拒絕所有來自用戶端位址的要求:198.51.*。*

允許來自其他用戶端位址的要求。

Deny 198.51.100.*,允許 192.0.2.1

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

拒絕所有來自用戶端位址的要求:198.51.100.*,但允許 192.0.2.1。

允許來自其他用戶端位址的要求。

允許 198.51.*。

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

允許所有來自以下地址的要求:198.51.*。*

拒絕來自其他用戶端位址的要求。

允許多個 IP

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

允許來自用戶端位址的要求:198.51.100。*192.0.2.* 203.0.113.*

拒絕所有其他地址。

拒絕多個 IP

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

拒絕來自用戶端位址的要求:198.51.100。*192.0.2.* 203.0.113.*

允許所有其他地址。

允許多個 IP,拒絕多個 IP

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

允許:198.51.*.* 192.0.*.* 203.0.*.*

拒絕部分許可清單:198.51.100。*192.0.2.* 203.0.113.*


使用須知

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

存取權控管政策的設定與執行包括下列項目:

  • 定義一組比對規則,並加入兩項相關聯動作的其中之一 (「允許」或「拒絕」)。
  • 請針對每項比對規則指定 IP 位址 (SourceAddress 元素)。
  • 指定規則測試順序。
  • 所有比對規則都會依照指定順序執行。如果規則相符,系統就會執行對應的動作,並略過下列比對規則。
    • 如果將同一項規則同時設定「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 位址。

邊緣會自動填入 X-Forwarded-For 標頭,填入最近一次外部 TCP 握手所接收的 IP 位址 (例如用戶端 IP 或路由器)。如果標頭中有多個 IP 位址,這些位址可能是處理要求的伺服器鏈結。但是,位址清單也可能包含假冒的 IP 位址。那麼政策如何得知要評估哪些位址呢?

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

首先,請確認貴機構是否已設定 feature.enableMultipleXForwardCheckForACL 屬性。您可以使用 取得機構 API 進行檢查。接著:

  • 如果機構的屬性清單中沒有 feature.enableMultipleXForwardCheckForACL,表示該屬性已設為 false (預設值)。將此屬性設為 false 後,政策會評估標頭中的「最後一個」位址 (顯示在追蹤記錄工具中),也就是上次外部 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 數據分析中的 X 向前的維度

Edge Analytics 會將 X-Forwarded-For 標頭的值寫入 x_forwarded_for_ip 維度。如要判斷向 Edge 發出要求的用戶端 IP,請使用 ax_true_client_ipax_resolved_client_ip 尺寸中的值。詳情請參閱「Analytics (分析) 指標、維度和篩選器參考資料」一文。

關於使用 CIDR 標記法進行 IP 遮蓋

CIDR 標記法 (無類別跨網域轉送) 是一種透過遮罩表示 IP 位址範圍的方式。此設定適用於 IPv4 和 IPv6。以下聊聊如何使用為簡單起見,我們的範例將使用 IPv4。

IP 位址是一組以半形句號分隔的數字群組,以二進位術語來說,每個群組都是特定數量的位元 (IPv4 為 8,IP 為 16)。IPv4 位址 198.51.100.1 以二進位檔為例:

11000110.00110011.01100100.00000001

即 4 組 8 位元,即總位元數為 32。使用 CIDR 時,只要在 IP 位址中加入 /number (1-32) 即可表示範圍,如下所示:

198.51.100.1/24

在這種情況下,24 是您在這項政策中要用於 mask 屬性值的數字。

這項標記代表「將前 24 位元完全依照原樣保留,其餘位元可以是 0 到 255 的任何值。」例如:

保持這些要求不變 最後一個群組可能的值
198.51.100. 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:

保持這些要求不變 可能的值
11000110.00110011.01100100.000000 (前 30 位元) 00000000、00000001、00000010 或 00000011
198.51.100. 0、1、2 或 3

在這個範例中,如果設定設為 <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"> 

下表說明所有政策父項元素的通用屬性:

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

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

預設 false
存在必要性 選用
類型 布林值

<IPRules> 元素

父項元素包含允許或拒絕 IP 位址的規則。noRuleMatchAction 屬性可讓您定義如何處理比對規則未涵蓋的任何 IP 位址。

<IPRules noRuleMatchAction = "ALLOW">
預設 不適用
存在必要性 選用
類型 不適用

屬性

屬性 說明 類型 預設 存在必要性
noRuleMatchAction
如果指定的比對規則未解決 (不相符) 時,要採取的動作 (允許或拒絕存取)。
有效值:ALLOW 或 DENY
字串 允許 需要

<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>
預設 不適用
存在必要性 選用
類型 不適用

屬性

屬性 說明 類型 預設 存在必要性
動作

如果指定的比對規則未解決 (不相符) 時,要採取的動作 (允許或拒絕存取)。

有效值:ALLOW 或 DENY

字串 允許 需要

<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。

預設 不適用
存在必要性 選用
類型 字串 (僅限單一 IP 位址)

屬性

屬性 說明 類型 預設 存在必要性
戴口罩的臉

mask 屬性是用來指出允許或拒絕的 IP 位址範圍。遮罩功能相當於使用 CIDR 標記法 (無類別跨網域轉送)。例如:

<SourceAddress mask="24">198.51.100.1</SourceAddress>

相當於下列 CIDR 標記法:

198.51.100.1/24

有效值:

IPv4:1 至 32

IPv6:1-128

如果值為零 (0),只有 IP 0.0.0.0 才有效,因此不實際。

使用變數設定遮罩

mask 屬性也支援訊息範本,這表示您可以使用 API Proxy 流程中可用的變數來設定值。舉例來說,您可以將遮罩值儲存在 KVM 中,並使用 KeyValueMapOperations 政策擷取遮罩,並將其指派給變數。如要使用變數設定 IP 遮罩,請使用下列格式,並假設變數名稱為 kvm.mask.value

mask="{kvm.mask.value}"

整數 不適用 需要

<VerifyBasedOn> 元素

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

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

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

您在此元素中輸入的值可決定要檢查標頭中的所有 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>
預設 X_FORWARDED_FOR_ALL_IP
存在必要性 選用
有效值

X_FORWARDED_FOR_ALL_IP (預設)

X_FORWARDED_FOR_FIRST_IP

X_FORWARDED_FOR_LAST_IP

結構定義

每個政策類型是由 XML 架構 (.xsd) 定義。歡迎參考 GitHub 的 政策結構定義

錯誤參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼 HTTP 狀態 原因 修正
accesscontrol.IPDeniedAccess 403 用戶端 IP 位址或 API 要求中傳遞的 IP 位址,與存取權控管政策的 <MatchRule> 元素中指定的 IP 位址相符,且 <MatchRule> 元素的 action 屬性設為 DENY<SourceAddress>

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤特有的變數」。

Variables 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name 是擲回錯誤的政策使用者指定的名稱。 acl.AC-AllowAccess.failed = true

錯誤回應示例

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