如何配置key-auth外掛程式 - Microservices Engine

key-auth外掛程式實現了基於API Key進行認證鑒權的功能，支援從HTTP請求的URL參數或者要求標頭解析API Key，同時驗證該API Key是否有許可權訪問。本文介紹如何配置key-auth外掛程式。

外掛程式類型

認證鑒權。

配置欄位

認證配置

名稱	資料類型	填寫要求	預設值	描述
consumers	array of object	必填。	-	佈建服務的調用者，用於對請求進行認證。
keys	array of string	必填。	-	API Key的來源欄位名稱，可以是URL參數或者HTTP要求標頭名稱。
in_query	bool	`in_query`和`in_header`至少有一個為 true。	true	配置為`true`時，網關會嘗試從URL參數中解析API Key。
in_header	bool	`in_query`和`in_header`至少有一個為 true。	true	配置為`true`時，網關會嘗試從HTTP要求標頭中解析API Key。
global_auth	array of string	選填（僅執行個體層級配置）	-	只能在執行個體層級配置，若配置為true，則全域生效認證機制; 若配置為false，則只對做了配置的網域名稱和路由生效認證機制，若不配置則僅當沒有網域名稱和路由配置時全域生效（相容老使用者使用習慣）。

子項consumers中每一項的配置欄位說明如下。

名稱	資料類型	填寫要求	預設值	描述
credential	string	必填。	-	配置該consumer的訪問憑證。
name	string	必填。	-	配置該consumer的名稱。

鑒權配置（非必需）

名稱	資料類型	填寫要求	預設值	描述
allow	array of string	選填（非執行個體層級配置）。	-	只能在路由或網域名稱等細粒度規則上配置，對於符合匹配條件的請求，配置允許訪問的 consumer，從而實現細粒度的許可權控制。

重要

在一個規則裡，鑒權配置和認證配置不可同時存在。
對於通過認證鑒權的請求，請求的Header會被添加一個X-Mse-Consumer欄位，用以標識調用者的名稱。

配置樣本

全域配置認證和路由粒度進行鑒權

以下配置將對網關特定路由或網域名稱開啟Key Auth認證和鑒權。credential欄位不能重複。

在執行個體層級做如下外掛程式配置：

global_auth: false
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
  name: consumer2
keys:
- apikey
- x-api-key

在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這條路由。

將API Key設定在URL參數中。

curl  http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1250b5

將API Key設定在HTTP要求標頭中。

curl  http://xxx.hello.com/test -H 'x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5'

認證鑒權通過後，請求的Header中會被添加一個X-Mse-Consumer欄位，在此例中其值為consumer1，用以標識調用方的名稱。

下列請求將拒絕訪問。

請求未提供API Key，返回401。
```
curl  http://xxx.hello.com/test
```

請求提供的API Key無權訪問，返回401。

curl  http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1250b5

根據請求提供的API Key匹配到的調用者無存取權限，返回403。

# consumer2不在route-a的allow列表裡
curl  http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc40e35

網關執行個體層級開啟

以下配置將對網關執行個體層級開啟 Basic Auth 認證，所有請求均需要經過認證後才能訪問。

global_auth: true
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
  name: consumer2
keys:
- apikey
- x-api-key

HTTP狀態代碼	出錯資訊	原因說明
401	No API key found in request.	請求未提供API Key。
401	Request denied by Key Auth check. Invalid API key.	不允許當前API Key訪問。
403	Request denied by Basic Auth check. Unauthorized consumer.	請求的調用方無存取權限。

Microservices Engine：key-auth外掛程式