跳至主要內容

簽章金鑰 (Signing keys)

Logto OIDC 簽章金鑰（又稱「OIDC 私鑰」與「OIDC Cookie 金鑰」）是用於簽署 JWT（存取權杖 (Access tokens) 與 ID 權杖 (ID tokens)）以及 Logto 登入階段 (Sign-in sessions) 中的瀏覽器 Cookie 的簽章金鑰。這些簽章金鑰會在初始化 Logto 資料庫（開源版）或建立新租戶（雲端版）時產生，並可透過 CLI（開源版）、Management API 或 Console UI 進行管理。

預設情況下，Logto 使用橢圓曲線（EC）演算法產生數位簽章。然而，考量到使用者經常需要驗證 JWT 簽章，且許多舊有工具不支援 EC 演算法（僅支援 RSA），我們實作了私鑰輪替功能，並允許使用者選擇簽章演算法（包含 RSA 與 EC）。這確保了與使用舊版簽章驗證工具的服務相容。

備註:

理論上，簽章金鑰不應外洩且沒有過期時間，因此無需輪替。不過，定期在一段時間後輪替簽章金鑰可提升安全性。

運作原理？​

  • OIDC 私鑰 (OIDC private key) 當初始化 Logto 實例時，會自動產生一對公鑰與私鑰，並註冊於底層 OIDC 提供者。當 Logto 發行新的 JWT（存取權杖或 ID 權杖）時，權杖會以私鑰簽署。同時，任何收到 JWT 的用戶端應用程式都可使用對應的公鑰驗證權杖簽章，以確保權杖未被第三方竄改。私鑰會在 Logto 伺服器上受到保護，而公鑰則如其名對所有人公開，可透過 OIDC 端點的 /oidc/jwks 介面存取。產生私鑰時可指定簽章金鑰演算法，Logto 預設使用 EC（橢圓曲線）演算法。管理員可透過輪替私鑰將預設演算法改為 RSA（Rivest-Shamir-Adleman）。
  • OIDC Cookie 金鑰 (OIDC cookie key) 當使用者啟動登入或註冊流程時，伺服器會建立一個「OIDC 階段 (session)」以及一組瀏覽器 Cookie。藉由這些 Cookie，瀏覽器可代表使用者向 Logto 使用體驗 (Experience) API 發起一系列互動，例如登入、註冊與重設密碼。然而，與 JWT 不同，Cookie 僅由 Logto OIDC 服務本身簽署與驗證，無需非對稱加密。因此，Cookie 簽章金鑰沒有對應的公鑰，也不採用非對稱加密演算法。

透過 Console UI 輪替簽章金鑰​

Logto 提供「簽章金鑰輪替 (Signing Keys Rotation)」功能，讓你能在租戶中建立新的 OIDC 私鑰與 Cookie 金鑰。

  1. 前往 Console > 簽章金鑰 (Signing keys)，即可管理 OIDC 私鑰與 OIDC Cookie 金鑰。

  2. 若要輪替簽章金鑰，請點擊「輪替私鑰 (Rotate private keys)」或「輪替 Cookie 金鑰 (Rotate cookie keys)」按鈕。輪替私鑰時，你可以選擇更換簽章演算法。

  3. 你會看到一個表格，列出所有正在使用的簽章金鑰。注意：你可以刪除前一組金鑰，但無法刪除目前使用中的金鑰。

    狀態說明
    目前 (Current)表示此金鑰目前正於你的應用程式與 API 中啟用。
    前一組 (Previous)指的是先前使用過但已被輪替的金鑰。以此金鑰簽署的現有權杖仍然有效。

請記得，輪替包含以下三個動作：

  1. 建立新簽章金鑰：這將要求所有應用程式與API採用新簽章金鑰。
  2. 輪替目前金鑰：輪替後，現有金鑰會標記為「前一組 (previous)」，不再用於新建立的應用程式與 API。但以此金鑰簽署的權杖仍然有效。
  3. 移除前一組金鑰：標記為「前一組 (previous)」的金鑰將被撤銷並從表格中移除。
注意:

切勿連續（兩次或以上）輪替簽章金鑰，否則可能導致所有已發行的權杖失效。

  • 對於 OSS 使用者，輪替簽章金鑰後需重新啟動 Logto 實例，新金鑰才會生效。
  • 對於雲端使用者，輪替後新簽章金鑰立即生效，但請務必避免連續多次輪替。

JWT 中 EC 與 RSA 簽章演算法介紹 (Introduction to EC and RSA signing algorithms in JWT)