Key Authentication

用途說明

可於服務或路由加上金鑰驗證。在傳送請求時，將金鑰帶入 body、header 或 query string 做驗證。

欄位配置說明

變數	類型	預設值	說明	必填
key_names	array of string	apikey	代表這把金鑰的名字，可有多個代表名字。使用者在傳送請求時，帶入其中一個名字即可。	V
key_in_header	boolean	true	開啟此項設定 (設為 true)，插件會從請求的標頭 (header) 中尋找金鑰。	V
key_in_body	boolean	false	開啟此項設定 (設為 true)，插件會從請求的 body 中尋找金鑰。支援的MIME格式如下：application/www-form-urlencoded, application/json, 及 multipart/form-data。	V
key_in_query	boolean	true	開啟此項設定 (設為 true)，插件會從請求的查詢參數 (query parameter) 中尋找金鑰。	V
hide_credentials	boolean	false	此欄位決定將請求往後送至服務時是否帶上原本的驗證標頭內容。 設定為 true 時，插件會把驗證 key（i.e. 包含 key 的 header, query string or request body）自請求移除。	V
anonymous	string		可設定 anonymous 使用者在驗證失敗時會使用此身份當作匿名用戶。 若此欄位為空，則當執行請求的身份認證時失敗時，會收到身份驗證失敗 4xx 的回應。 ＊要注意的是，此欄位需填入的是 consumer 本身之 id，而不是 custom_id 。
run_on_preflight	boolean	true	開啟此項設定 (設為 true) 會在 OPTIONS 預檢請求上運行（並嘗試進行身份驗證）；關閉此項設定 (設為 false) 則會讓所有 OPTIONS 預檢請求通過。	V

用法示例

在全局啟用插件

1. 從網站左邊 Menu 中 外掛插件 頁面中，點選右上角的 新增外掛插件 ：

2. 點選後，選擇 認證 頁籤，並啟用 Key Auth，填寫內容參考欄位配置說明，設定成功後，任何請求(不分服務、路由、用戶)皆需經過認證才能通過。

在服務端上啟用插件

1. 從網站左邊Menu中 服務 > 服務列表 頁面中，選擇要啟用此插件的服務，假設為 google，點選對應的編輯按鈕：

2. 在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

點選後，選擇 認證 頁籤，並啟用 Key Auth，填寫內容參考欄位配置說明，設定成功後，僅有此服務(範例為google)請求需經過認證才能通過。

在路由端上啟用插件

可以由兩種方式來選擇路由，並啟用插件：

方式一：路由列表

1. 從網站左邊 Menu 中 服務 > 路由列表 頁面中，選擇要啟用此插件的路由，假設為 google，點選對應的編輯按鈕：

方式二：服務 > 服務列表 > 路由列表

1. 從網站左邊 Menu 中 服務 > 服務列表 頁面中，選擇要啟用此插件的路由 所屬之服務(假設為 google)，點選對應的編輯按鈕。

在編輯畫面中，點選上方的 路由 頁籤，選擇要啟用此插件的路由(假設為 google)，點選對應的編輯按鈕：

---

2. 承第1步，點擊上述兩種方式之一的編輯按鈕後，在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

點選新增外掛插件 按鈕後，選擇 認證 頁籤，並啟用Key Auth，填寫內容參考欄位配置說明，設定成功後，僅有此路由(範例為google)請求需經過認證才能通過。

建立使用者及金鑰

1. 從網站左邊 Menu 中 訂閱用戶 > 用戶列表 頁面中選擇右上方 新增 按鈕，新增用戶。

2. 選擇剛建立的使用者，進入編輯頁面，選擇上方 憑證 頁籤，然後選擇左邊 Key Authentication 頁籤，再選擇列表左上方的 新增 按鈕。

3. 金鑰欄位可填可不填。可填入一組獨特的金鑰或是留空自動生成。圖為自動生成的一把金鑰。

驗證

1. 選擇一路由開啟此插件服務 (將 key_name 設為 testing )，並建立好使用者及金鑰 (範例將路由之域名 (hosts) 設定為 google，路徑 (paths) 設定為 /index，並開啟 拆分路徑 (strip path))。

2. 此時在console上送出以下指令：

$ curl -H 'x-api-host: google' <GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/index -i

會得到以下回應

HTTP/1.1 401 Unauthorized

Date: Thu, 25 Mar 2021 09:54:08 GMT

Content-Type: application/json; charset=utf-8

Connection: keep-alive

WWW-Authenticate: Key realm="kong"

Content-Length: 41

X-Kong-Response-Latency: 3

Server: kong/2.0.4

{"message":"No API key found in request"}

代表插件正常運作，並阻擋未通過驗證之請求。

3. 以下有 3 種方式可帶入金鑰：

方法一：將金鑰帶入 header

在 console 上送出以下指令 (帶入 header為 key_name: key )

$ curl -H 'x-api-host: google' -H 'testing: BqldWS2C1YHtCoGaDfc0wtXpjqXqq2kt' <GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/index -i

即可得到正常的回應。

方法二：將金鑰帶入 query string

在 console 上送出以下指令：

$ curl -H 'x-api-host: google' '<GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/index?testing=BqldWS2C1YHtCoGaDfc0wtXpjqXqq2kt' -i

即可得到正常的回應

方法三：將金鑰帶入 body

此方法需在插件打開 key_in_body 這項設定(設為 true)。 (注意：打開此設定後，插件將只檢查 body，就算將金鑰帶入 header 或是 query string 也不會通過)

在 console 上送出以下指令：

$ curl -XPOST -H 'x-api-host: google' '<GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/index' -d 'testing=BqldWS2C1YHtCoGaDfc0wtXpjqXqq2kt' -i

即可得到正常的回應。