Day 25 : Kong 的 Routes 共用與 HMAC Auth 實踐 - 1

17th鐵人賽 devops kong hmac

山姆大叔

團隊邦邦不邦邦

2025-10-08 05:45:48

158 瀏覽

分享至

HMAC 認證

還記得 Day20 的時候，提到了新的API要提供給金融客戶來使用嗎？但因為金融客戶有更高強度的認證授權要求(註：為確保本行資訊安全，所提供之服務須經安全性連線外，認證授權機制之機敏資訊需可供定期輪替，並確保逾時後授權失效之機制....)，因此準備透過kong來使用更高強度認證的設定。

當然，為了不要重工為前提，當然要將同樣的 API服務重用為前提進行設計。這樣不但能夠讓開發團隊更專注在單一產品的開發，也讓維運團隊不需維護兩個線上的服務，成功的降低了團隊的整體認知負荷。

HMAC plug in kong

傳統上HMAC 的步驟大致是：

準備一個 shared secret（對稱金鑰，雙方都知道，但外人不知道）。
傳訊息時，用 hash 函數（像 SHA256）+ secret 來計算一段固定長度的「簽章」。
接收方用同樣的 secret 和 hash 算一次，比對結果是否一致。

這種作法其實類似apikey的作法，因為都是在header中傳送同樣的驗證資訊(即使被hash過)來表示請求端的身分，因此如果是透過中間人攻擊的方式取得，那就有機會被用來重放(replay)。

而Kong 的 HMAC Plugin 在基本 HMAC 基礎上，加了 時間戳記（timestamp） 來防止重放攻擊：

時間戳記（Date header 或 x-date header）：會帶上 UTC 時間，並將它一起放入 HMAC 簽章計算。這代表同一個 request，只在某個短時間範圍內有效。
clock_skew（允許時間誤差區間）：因為客戶端和伺服器的時間可能不同步，所以 Kong 允許設定一個「容差時間」（例如 ±60 秒）。如果時間超過這個範圍，request 會被拒絕。

補充：中間人攻擊與重放攻擊
重放攻擊(replay)通常是指攻擊者「重送」一個已經合法通過驗證的請求，讓系統重複執行某個動作（例如轉帳、登入等）。攻擊者不一定要能解密內容，只要能取得並重送封包即可。

中間人攻擊則是攻擊者「攔截」並可能「竄改」雙方的通訊內容。攻擊者可以取得敏感資訊，也可以修改資料，甚至可以發動重放攻擊。

在這裡筆者舉例的情境中，中間人攻擊算是一種「取得資料」的手段，攻擊者可以藉由中間人攻擊來攔截合法請求，然後再利用這些請求發動重放攻擊。因此，重放攻擊常常是中間人攻擊的「後續利用方式」之一。

而kong在HMAC plugin說明中，有明確的指出可以緩解重放攻擊的敘述： The HMAC Authentication plugin also implements a clock skew check as described in the specification to prevent replay attacks. By default, a minimum lag of 300s in either direction (past/future) is allowed.

圖25-1 中間人攻擊

筆者曾經也為了組織中遇到懷疑是重放攻擊的狀況，將HMAC認證授權方式建議團隊實作在APP中以達到緩解的效果([個案學習] API Server 未經授權連線透過Kong API Gateway 的HMAC-Auth快速排除手段)。

Route 設定說明

開頭有說到希望可以共用service為前提進行設計，這時候就必須要說到 用不同的route來共用同一個service 的設計方式了。請注意到下方設定範例：

- name: case_ELK_JPG_AuthZN_weather
  url: http://case_ELK_JPG_AuthZN_weather:8080
  routes:
  - name: case_ELK_JPG_AuthZN_weather
    paths:
    - /case_ELK_JPG_AuthZN_weather/
    ...原有route 內容省略...
  - name: TestCase_HMAC
    paths:
    - /FinancalHMAC/
    plugins:
    - config:
    enabled: true
    name: hmac-auth
    ....hmac-auth 細節設定省略，下方說明...
    tags:
    - FinancalHMAC
    - name: acl
    config:
        allow:
        - FinancalHMAC
        deny: null
        hide_groups_header: false
    enabled: true
  ...下略...

圖25-2 共用service的管理方式

筆者用圖25-2來說明設定內容，圖中可以看到筆者使用不同的route(case_ELK_JPG_AuthZN_weather、TestCase_HMAC) 設定在同一個service(case_ELK_JPG_AuthZN_weather)上。這種是利用path的不同來做請求進入點的分辨方式，也是最常見的管理方式。

這種做法的優點是，可以根據不同route設定不同的認證、快取、log、trace以及monitor的方式設計route的組合，進而滿足企業中各式各樣的需求。

或許有讀者會詢問，真的有這麼多種情境需要切割成這麼多種組合嗎？這顯然是肯定的。例如筆者所屬的公司在購買kong enterprise edition版本時，是採取hybrid mode進行管理，因此就會發現到同一座control plane中，存在三種不同的log保存策略。有子公司存成file導入efk，也有直接用http log直接與elasticsearch存入，甚至也有用http log存入splunk中的方式。

因此，透過這種不同組合的方式，只要透過恰當的管理設計，就能夠最大化的共用api服務。

Plugin HMAC 的設定說明

  - name: TestCase_HMAC
    paths:
    - /FinancalHMAC/
    plugins:
    - config:
        algorithms:
        - hmac-sha1
        - hmac-sha256
        - hmac-sha384
        - hmac-sha512
        anonymous: null
        clock_skew: 60
        enforce_headers:
        - x-date
        hide_credentials: false
        validate_request_body: false
    enabled: true
    name: hmac-auth
    protocols:
    - grpc
    - grpcs
    - http
    - https
    - ws
    - wss

HMAC的設定其實非常多，這次簡單將各項目敘述如下：

設定說明：

algorithms: 支援的 HMAC 演算法，可根據安全需求選擇(這邊筆者使用hmac-sha256做為示範)。
anonymous: 若設為 null，未通過驗證的請求會被拒絕。
clock_skew: 允許的時間誤差（秒），避免因伺服器與客戶端時間不同步導致驗證失敗，這邊設定60秒。
enforce_headers: 強制要求 header（如 x-date），用於防止重放攻擊(這邊示範也會使用到)。
hide_credentials: 設為 false 時，HMAC 認證資訊會保留在 header，設為 true 則會移除。
validate_request_body: 是否驗證 request body，預設 false(這個設定可以做到整個請求的不可偽造性，包含body，但要注意非常吃效能)。
protocols: 支援的協定類型，包含 HTTP、HTTPS、gRPC、WebSocket 等。

Consumer 的設定說明

- acls:
  - group: FinancalHMAC
  username: customer-user1@financal.com
  custom_id: customer-user1
  hmacauth_credentials:
  - secret: 4MfcLIDVuxfH67gwuANeFiUTineOHHVs
    username: 2025_customer-user1

consumer的部分，僅有認證的方式不同於原本使用apikey設定方式，其他則是相同。不過有一個位置可以特別注意，那就是在hmacauth_credentials中，可以注意到是一個list。

這表示一個consumer有多組的hmacauth_credentials？在這裡請容許筆者賣一個關子，這與需求有關係，明天筆者將解惑。

今天就先到這裡，明天將接續著說明，HMAC Client端要如何進行呼叫，明天見~