您正在查看 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.value
和 kvm.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 元素)。
- 請參閱政策如何選擇要評估的 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> 元素設為 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_ip
或 ax_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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<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 位址) |
屬性
屬性 | 說明 | 類型 | 預設 | 存在必要性 |
---|---|---|---|---|
戴口罩的臉 |
相當於下列 CIDR 標記法: 198.51.100.1/24 有效值: IPv4:1 至 32 IPv6:1-128 如果值為零 (0),只有 IP 0.0.0.0 才有效,因此不實際。 使用變數設定遮罩
|
整數 | 不適用 | 需要 |
<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 |
---|---|
存在必要性 | 選用 |
有效值 |
|
結構定義
每個政策類型是由 XML 架構 (.xsd) 定義。歡迎參考 GitHub 的 政策結構定義。
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
accesscontrol.IPDeniedAccess |
403 | 用戶端 IP 位址或 API 要求中傳遞的 IP 位址,與存取權控管政策的 <MatchRule> 元素中指定的 IP 位址相符,且 <MatchRule> 元素的 action 屬性設為 DENY 。<SourceAddress> |
build |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤特有的變數」。
錯誤回應示例
{ "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>