API如何配置黑白名單 - API Gateway

IP存取控制外掛程式是API Gateway提供的 API 安全防護組件之一，負責控制 API 的調用來源 IP （支援IP段）。您可以通過配置某個 API 的 IP 白名單/黑名單來允許/拒絕某個來源的API請求。

1. 概述

支援白名單或黑名單方式：

白名單：支援配置 IP 或者 AppID + IP 的白名單訪問，不在白名單列表的請求將會被拒絕。
- IP 白名單，只允許設定的調用來源 IP 的請求被允許。
- AppID + IP ，如果配置了AppId，則該條目僅對該AppId生效，此AppId只能在設定的 IP 下訪問，不限制其他已授權App的調用IP。
黑名單：您可以配置 IP 黑名單，黑名單中 IP 的訪問將被 API 網關拒絕。

重要

IP存取控制外掛程式僅支援IPv4地址，不支援IPv6地址。

2. 外掛程式配置

可以選擇JSON或者YAML格式的來配置您的外掛程式，兩種格式的schema相同，可以搜尋yaml to json轉換工具來進行配置格式的轉換，yaml格式的模板見下表。

---
type: ALLOW           # 控制模式，支援白名單模式'ALLOW'和黑名單模式'REFUSE'
resource: "XFF:-1"   # 可選欄位，如果設定本欄位，取X-Forwarded-For頭中的IP作為判斷依據，本樣本取XFF頭的倒數第一個IP作為用戶端源IP判斷，
items: 
- blocks:         # IP位址區段
  - 61.3.XX.XX/24   # 使用CIDR方式配置
  appId: 219810   # （可選）如果配置了appId則該條目僅對該AppId生效
- blocks:         # IP地址
  - 79.11.XX.XX    # 使用IP地址方式配置
- blocks:         # 使用者VPC
  - 192.168.XX.XX/32    # 專享執行個體情境，從使用者VPC內訪問API Gateway的請求，API Gateway看到的來源地址處於這個位址區段

需要特別注意最後一點，專享執行個體情境，API Gateway允許從使用者VPC內發送請求到API Gateway，此時API Gateway可以直接讀取來源VPC內的地址，比如192.168.XX.XX，使用者佈建黑白名單時可以直接使用VPC內地址作為配置值。

3. 穿透WAF配置

如果API Gateway前面有WAF等中介軟體，業務需要實現API層級IP黑白名單能力時，就需要用到resource欄位，resource欄位為可選欄位，如果不填寫，取和網關直接連接前一跳的IP作為判斷依據。如果填寫本欄位，允許設定X-Forwarded-For頭中的值作為IP判斷依據。

說明

WAF會將它收到的請求的源IP加入到X-Forwarded-For頭的最後發送給API Gateway，API Gateway去判斷X-Forwarded-For頭中的這個值就可以。這種情況建議使用者使用"XFF:-1"來判斷WAF前一跳的IP地址。

resource欄位填寫格式為“XFF:index”，index的值為X-Forwarded-For頭中IP排序序號，從0開始算，允許負數，比如X-Forwarded-For的值為IP1,IP2,IP3，那麼如果index值為0，取IP1，如果index的值為-1，取IP3，也就是倒數第一個IP。

4. 跨VPC訪問

在跨VPC訪問的情況，API Gateway可以直接從請求中讀取來源VPC內的IP地址，您可以放心編寫針對VPC內IP的IP存取控制外掛程式。API Gateway還可以讀取到來源VPC的VPCID，您可以通過設定參數存取控制外掛程式來設定只允許某些指定的VPC訪問您的API。

5. 接入WAF的同時跨VPC訪問

有一種情境，使用者的API需要同時對公網和內網提供服務，而在公網提供服務的時候，在API Gateway前接入了WAF中介軟體，需要API Gateway對WAF前的用戶端做IP存取控制，同時需要對內網來源做IP存取控制。網關為了這種情境做了適配，使用者可以用resource欄位和allowResourceMissing欄位配合使用來實現同時控制內網和使用WAF等中介軟體的公網的來源IP。使用者通過設定resource欄位來指定API Gateway從X-Forwarded-For頭中擷取透過WAF中介軟體過來的用戶端的IP，通過allowResourceMissing欄位來配置API Gateway遇到用戶端沒有傳X-Forwarded-For頭時的內網訪問情境，從前一跳擷取用戶端的IP作為判斷依據。下面是例子：

---
type: ALLOW           # 控制模式，支援白名單模式'ALLOW'和黑名單模式'REFUSE'
resource: "XFF:-1"   # 可選欄位，如果設定本欄位，取X-Forwarded-For頭中的IP作為判斷依據，本樣本取XFF頭的倒數第一個IP作為用戶端源IP判斷
allowResourceMissing: "true"  #允許Resource缺失，缺失時取API Gateway的前一跳的IP作為判斷條件
items: 
- blocks:         # IP位址區段
  - 61.3.XX.XX/24   # 使用CIDR方式配置
  appId: 219810   # （可選）如果配置了appId則該條目僅對該AppId生效
- blocks:         # IP地址
  - 79.11.XX.XX    # 使用IP地址方式配置
- blocks:         # 使用者VPC
  - 192.168.XX.XX/32    # 專享執行個體情境，從使用者VPC內訪問API Gateway的請求，API Gateway看到的來源地址處於這個位址區段

6. IP存取控制外掛程式支援外掛程式資料集

IP存取控制外掛程式的配置和詳細說明參考IP存取控制外掛程式。

6.1. 建立外掛程式資料集

登入API Gateway控制台，選擇地區並在左側導覽列選擇API管理 > 外掛程式管理。
在外掛程式列表頁面選擇自訂資料集欄，單擊頁面右上方建立資料集，在建立資料集彈框中填寫資料集的名稱，類型選擇IP_WHITELIST_CIDR。
單擊目標資料集ID，進入資料集頁面單擊建立資料集條目，在建立資料集條目彈框中填寫資料值（IP地址或IP位址區段）和到期時間（資料集中的資料條目在到達其到期時間後將自動失效。）。

重要

外掛程式資料集只在專享執行個體生效，如果您配置了資料集的外掛程式所綁定的API不是配置在專享執行個體上，那麼外掛程式中配置的資料集將不生效。

6.2. IP存取控制外掛程式配置外掛程式資料集

IP存取控制外掛程式中配置外掛程式資料集是在IP存取控制外掛程式中配置的基礎上，在items集合元素中增加blocksDatasetId欄位，該欄位的值就是上述建立的IP_ACCESS_CIDR類型的資料集ID。blocksDatasetId和blocks是相互相容的，每個item中可以同時配置blocksDatasetId和blocks，也可以單獨配置其中一個。

---
type: ALLOW 
items: 
- blocksDatasetId: 87b65008e92541938537b1a4a236eda5
  appId: 219810
- blocksDatasetId: 87b65008e92541938537b1a4a236eda3
  blocks:
  - 127.0.XX.XX
  - 192.168.XX.XX/24