跳至主要內容

簽署金鑰

Logto 的 OIDC 簽署金鑰，也稱為「OIDC 私密金鑰」和「OIDC cookie 金鑰」，是用於簽署 JWT 權杖（存取權杖 (Access tokens) 和 ID 權杖 (ID tokens)）以及 Logto 登入會話中的瀏覽器 cookie 的簽署金鑰。這些簽署金鑰在初始化 Logto 資料庫時（開源）或創建新租戶時（Cloud）生成，並可透過 CLI（開源）、Management API 或 Console UI 進行管理。

預設情況下，Logto 使用橢圓曲線 (EC) 演算法生成數位簽章。然而，考慮到使用者經常需要驗證 JWT 簽章，且許多舊工具不支援 EC 演算法（僅支援 RSA），我們實現了旋轉私密金鑰的功能，並允許使用者選擇簽署演算法（包括 RSA 和 EC）。這確保了與使用過時簽章驗證工具的服務相容。

備註:

理論上，簽署金鑰不應洩漏且沒有過期時間，這意味著不需要旋轉它們。然而，定期在一定時間後旋轉簽署金鑰可以增強安全性。

如何運作？​

  • OIDC 私密金鑰 當初始化 Logto 實例時，會自動生成一對公鑰和私密金鑰，並在底層 OIDC 提供者中註冊。因此，當 Logto 發行新的 JWT 權杖（存取權杖或 ID 權杖）時，權杖會使用私密金鑰簽署。同時，任何接收到 JWT 權杖的客戶端應用程式都可以使用配對的公鑰驗證權杖簽章，以確保權杖未被任何第三方篡改。私密金鑰在 Logto 伺服器上受到保護。然而，正如其名稱所示，公鑰是公開的，可以透過 OIDC 端點的 /oidc/jwks 介面訪問。生成私密金鑰時可以指定簽署金鑰演算法，Logto 預設使用 EC（橢圓曲線）演算法。管理員使用者可以透過旋轉私密金鑰將預設演算法更改為 RSA（Rivest-Shamir-Adleman）。
  • OIDC cookie 金鑰 當使用者啟動登入或註冊流程時，伺服器上會創建一個「OIDC 會話」，以及一組瀏覽器 cookie。透過這些 cookie，瀏覽器可以請求 Logto 使用體驗 API 代表使用者執行一系列互動，例如登入、註冊和重設密碼。然而，與 JWT 權杖不同，cookie 僅由 Logto OIDC 服務本身簽署和驗證，不需要非對稱加密措施。因此，我們沒有用於 cookie 簽署金鑰的配對公鑰，也沒有非對稱加密演算法。

從 Console UI 旋轉簽署金鑰​

Logto 引入了「簽署金鑰旋轉」功能，允許你在租戶中創建新的 OIDC 私密金鑰和 cookie 金鑰。

  1. 前往 Console > 簽署金鑰。在這裡，你可以管理 OIDC 私密金鑰和 OIDC cookie 金鑰。

  2. 要旋轉簽署金鑰，點擊「旋轉私密金鑰」或「旋轉 cookie 金鑰」按鈕。旋轉私密金鑰時，你可以選擇更改簽署演算法。

  3. 你會看到一個表格列出所有正在使用的簽署金鑰。注意：你可以刪除先前的金鑰，但不能刪除當前的金鑰。

    狀態描述
    當前表示此金鑰目前在你的應用程式和 API 中處於活躍使用狀態。
    先前指的是先前使用過但已被旋轉的金鑰。使用此簽署金鑰的現有權杖仍然有效。

請記住，旋轉涉及以下三個動作：

  1. 創建新簽署金鑰：這將要求所有 應用程式 和 API 採用新的簽署金鑰。
  2. 旋轉當前金鑰：現有金鑰在旋轉後將被指定為「先前」，不會被新創建的應用程式和 API 使用。然而，使用此金鑰簽署的權杖仍然有效。
  3. 移除先前的金鑰：標記為「先前」的金鑰將被撤銷並從表格中移除。
注意:

切勿連續旋轉簽署金鑰（兩次或多次），因為這可能使所有已發行的權杖失效。

  • 對於 OSS 使用者，旋轉簽署金鑰後，需要重新啟動 Logto 實例以使新簽署金鑰生效。
  • 對於 Cloud 使用者，新簽署金鑰在旋轉後立即生效，但請確保不要連續多次旋轉簽署金鑰。

JWT 中 EC 和 RSA 簽署演算法介紹