basic-auth插件實現了基于HTTP Basic Auth標準進行認證鑒權的功能。本文介紹如何配置basic-auth插件。
插件類型
認證鑒權。
配置字段
認證配置
名稱 | 數據類型 | 填寫要求 | 默認值 | 描述 |
consumers | array of object | 必填。 | - | 配置服務的調用者,用于對請求進行認證。 |
global_auth | array of string | 選填(**僅實例級別配置**) | - | 只能在實例級別配置,若配置為true,則全局生效認證機制; 若配置為false,則只對做了配置的域名和路由生效認證機制,若不配置則僅當沒有域名和路由配置時全局生效(兼容老用戶使用習慣)。 |
子項consumers
中每一項的配置字段說明如下。
名稱 | 數據類型 | 填寫要求 | 默認值 | 描述 |
credential | string | 必填。 | - | 配置該consumer的訪問憑證。 |
name | string | 必填。 | - | 配置該consumer的名稱。 |
鑒權配置(非必需)
名稱 | 數據類型 | 填寫要求 | 默認值 | 描述 |
allow | array of string | 選填(**非實例級別配置**)。 | - | 只能在路由或域名等細粒度規則上配置,對于符合匹配條件的請求,配置允許訪問的 consumer,從而實現細粒度的權限控制。 |
在一個規則里,鑒權配置和認證配置不可同時存在。
對于通過認證鑒權的請求,請求的Header會被添加一個
X-Mse-Consumer
字段,用以標識調用者的名稱。
配置示例
全局配置認證和路由粒度進行鑒權
以下配置將對網關特定路由或域名開啟Basic Auth認證和鑒權。
憑證信息中的用戶名和密碼之間使用":"分隔。
credential
字段不能重復。
在實例級別做如下插件配置:
global_auth: false
consumers:
- credential: 'admin:123456'
name: consumer1
- credential: 'guest:abc'
name: consumer2
在route-a
和route-b
兩個路由做如下插件配置:
allow:
- consumer1
在*.example.com
和test.com
兩個域名做如下插件配置:
allow:
- consumer2
此例指定的
route-a
和route-b
即在創建網關路由時填寫的路由名稱,當匹配到這兩個路由時,將允許name
為consumer1
的調用者訪問,其他調用者不允許訪問。此例指定的
*.example.com
和test.com
用于匹配請求的域名,當發現域名匹配時,將允許name
為consumer2
的調用者訪問,其他調用者不被允許訪問。
根據該配置,下列請求可以允許訪問。
請求指定用戶名密碼。
# 假設以下請求將會匹配到route-a路由
# 使用 curl 的 -u 參數指定
curl -u admin:123456 http://xxx.hello.com/test
# 或者直接指定 Authorization 請求頭,用戶名密碼使用 base64 編碼
curl -H 'Authorization: Basic YWRtaW46MTIzNDU2' http://xxx.hello.com/test
認證鑒權通過后,請求的Header中會被添加一個X-Mse-Consumer
字段,在此例中其值為consumer1
,用以標識調用方的名稱。
下列請求將拒絕訪問。
請求未提供用戶名密碼,返回401。
curl http://xxx.hello.com/test
請求提供的用戶名密碼錯誤,返回401。
curl -u admin:abc http://xxx.hello.com/test
根據請求的用戶名和密碼匹配到的調用者無訪問權限,返回403。
# consumer2不在route-a的allow列表里 curl -u guest:abc http://xxx.hello.com/test
網關實例級別開啟
以下配置將對網關實例級別開啟 Basic Auth 認證,所有請求均需要經過認證后才能訪問。
global_auth: true
consumers:
- credential: 'admin:123456'
name: consumer1
- credential: 'guest:abc'
name: consumer2
相關錯誤碼
HTTP狀態碼 | 出錯信息 | 原因說明 |
401 | Request denied by Basic Auth check. No Basic Authentication information found. | 請求未提供憑證。 |
401 | Request denied by Basic Auth check. Invalid username and/or password. | 請求憑證無效。 |
403 | Request denied by Basic Auth check. Unauthorized consumer. | 請求的調用方無訪問權限。 |