跳至主要內容

簽章金鑰 (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 > 租戶設定 > OIDC 設定，即可管理 OIDC 私鑰與 OIDC Cookie 金鑰。

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

  3. 你會看到一個表格，列出所有正在使用的簽章金鑰。對於 OIDC 私鑰，你可以刪除前一個金鑰，但無法刪除目前或下一個金鑰。對於 OIDC Cookie 金鑰，你可以刪除前一個金鑰，但無法刪除目前金鑰。

    狀態說明
    下一個用於分階段 OIDC 私鑰輪替。金鑰已建立，但 Logto 會等到寬限期結束、金鑰生效後才用它簽署新的 JWT。
    目前表示 Logto 目前用此金鑰簽署新發行的 JWT 或 Cookie。
    前一個指先前使用過但已被輪替的金鑰。用該金鑰簽署的現有 JWT 或 Cookie 仍然有效，直到過期或金鑰被刪除為止。

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

  1. 建立新簽章金鑰：對於 OIDC 私鑰，Logto 可先將新金鑰設為「下一個 (Next)」，讓你的應用程式與 API 有時間從 /oidc/jwks 端點刷新公鑰，之後才用新金鑰簽署。
  2. 輪替目前金鑰：當輪替生效時，「下一個 (Next)」金鑰會變成「目前 (Current)」，而現有「目前」金鑰則變為「前一個 (Previous)」。用前一個金鑰簽署的權杖仍然有效。
  3. 移除最舊的前一個金鑰：Logto 最多僅保留一組「前一個 (Previous)」私鑰。若在新金鑰生效時已存在前一個私鑰，舊的前一個金鑰會被移除。

在 Logto Cloud 中，OIDC 私鑰輪替會在 4 小時寬限期後生效。這段期間內，新金鑰會先準備好並透過 JWKS 公開，Logto 會等到寬限期結束才用它簽署新發行的 JWT。在 Console 表格中，生效時間 (Effective at) 欄位會顯示分階段「下一個 (Next)」金鑰何時會變成「目前 (Current)」。

對於自架 OSS 部署，預設私鑰輪替寬限期為 0 秒，即輪替立即生效。若要使用分階段輪替，請在 Logto 服務設定 PRIVATE_KEY_ROTATION_GRACE_PERIOD 環境變數，或在呼叫 Management API 端點 POST /api/configs/oidc/private-keys/rotate 時於 request body 傳入明確的 rotationGracePeriod 值。

注意:

除非你有意更換分階段「下一個 (Next)」金鑰，否則請避免在待生效輪替尚未生效前重複輪替簽章金鑰。

過早刪除唯一的「前一個 (Previous)」金鑰，可能導致用該金鑰簽署的現有 JWT 或 Cookie 失效。

JWT 中 EC 與 RSA 簽章演算法介紹