Version: Next

HMAC Authentication

用途說明#

可於服務或路由加上HMAC簽署驗證。此插件會確認標頭 Proxy-Authorization 或 Authorization 中的數位簽署是有效的。

欄位配置說明#

變數	類型	預設值	說明	必填
hide_credentials	boolean	false	此欄位決定將請求往後送至服務時是否帶上原本的驗證標頭內容。開啟時插件會把驗證內容自請求移除。
clock_skew	number	300	可設定時鐘偏移值(秒)來預防重送攻擊
anonymous	string		可設定"anonymous"使用者在驗證失敗時會使用此身份驗證。如此欄位為空，則請求之標頭沒帶上Authorization時會收到authentication failure 4xx的回應。要注意的是，此欄位需填入的是consumer本身之id，而不是custom_id。
validate_request_body	boolean	false	開啟此項設定，插件會對請求主體做驗證	V
enforce_headers	array of string		設定在建立簽署時必須代入之標頭列表
algorithms	array of string	hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512	支援之HMAC摘要演算法列表。允許的內容有 `hmac-sha1`, `hmac-sha256`, `hmac-sha384`, 及 `hmac-sha512`

用法示例#

在全局啟用插件#

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

全局啟用畫面

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

在服務端上啟用插件#

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

服務啟用畫面1

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

服務啟用畫面2

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

在路由端上啟用插件#

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

方式一：路由列表#

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

路由啟用畫面1

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

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

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

路由啟用畫面2

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

路由啟用畫面3

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

建立使用者及憑證#

從網站左邊Menu中 訂閱用戶 > 用戶列表 頁面中選擇右上方 新增 按鈕，新增用戶。
選擇剛建立的使用者，進入編輯頁面，選擇上方 HMAC Authentication 頁籤，再選擇左上方的 新增 按鈕。

hmac auth

填入用戶名稱及密鑰，密鑰可填可不填，如留空則會自動生成密鑰。在這裡用 Test 及 testing 做為範例。

hmac auth2

憑證格式#

驗證簽署結構#

credentials := "hmac" params
params := keyId "," algorithm ", " headers ", " signature
keyId := "username" "=" plain-string
algorithm := "algorithm" "=" DQUOTE (hmac-sha1|hmac-sha256|hmac-sha384|hmac-sha512) DQUOTE
headers := "headers" "=" plain-string
signature := "signature" "=" plain-string
plain-string   = DQUOTE *( %x20-21 / %x23-5B / %x5D-7E ) DQUOTE

簽署參數#

參數	描述
username	憑證的 `username`
algorithm	產生簽署內容的演算法
headers	HTTP標頭名，使用空白分開，代表此請求
signature	使用 `Base64` 編碼產生的簽署內容

時鐘偏移(Clock Skew)#

預設為最少延遲300秒。伺服器端及客戶端需要與NTP同步並且把有效時間(GMT格式)帶入標頭 X-Date 或是 Date

主體驗證(Body Validation)#

使用者可開啟 validate_request_body 來驗證請求主體。如開啟此選項，則插件會將主體內容用 SHA-256 演算法加密，並且看是否符合標頭 Digest 之內容。標頭 Digest 格式如下：

Digest: SHA-256=base64(sha256(<body>))

如果沒有請求主體，則 Digest 必須設置長度為0。

強制標頭名(Enforcing Headers)#

enforce_headers 參數可強制標頭必須為簽署內容的一部分。預設上是沒有任何規定標頭必須被使用在生成簽署內容中。建議可以加上 request-line 、 host 以及 date，如果希望建立一個強力的簽署則可再加上 digest。

驗證#

選擇一路由開啟此插件服務，在此示範全部欄位使用預設值。
此時在console上送出以下指令

$ curl -H 'x-api-host: google' http://localhost:8000/index -i

會收到以下回應

HTTP/1.1 401 Unauthorized
Date: Wed, 31 Mar 2021 06:00:01 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Content-Length: 26
X-Kong-Response-Latency: 2
Server: kong/2.0.4

{"message":"Unauthorized"}%

建立signature來通過驗證

範例中使用 date 以及 request-line 經過 hmac-sha256 來拼湊出以下摘要：

signing_string="date: Wed, 31 Mar 2021 06:24:20 GMT\nGET /index HTTP/1.1"
digest=HMAC-SHA256(<signing_string>, "testing")
base64_digest=base64(<digest>)

最終 Authorization 的內容如下：

Authorization: hmac username="Test", algorithm="hmac-sha256", headers="date request-line", signature=<base64_digest>"

而將上面的 signing_string 經過加密及編碼的內容為 +CHEQ6lBsvAh+I1hrbHsSwvFt1L6ziAPBgw7U/07UnY= ，並將其代入signature

試著送出以下指令

$ curl -H 'x-api-host: google' -H 'date: Wed, 31 Mar 2021 06:24:20 GMT' -H 'Authorization: hmac username="Test", algorithm="hmac-sha256", headers="date request-line", signature="+CHEQ6lBsvAh+I1hrbHsSwvFt1L6ziAPBgw7U/07UnY="' localhost:8000/index -i

即可得到正常的回應。