跳至主要內容

旋轉簽章金鑰（OSS）

備註:

如果你使用 Logto Cloud，可以在 Console UI 旋轉簽章金鑰，請參考本教學。

Logto OSS 自 v1.8 起支援旋轉簽章金鑰。

Logto OIDC 簽章金鑰，也稱為「OIDC 私鑰」與「OIDC Cookie 金鑰」，是用於簽署 JWT（存取權杖 (Access tokens) 與 ID 權杖 (ID tokens)）以及 Logto 登入階段的瀏覽器 Cookie 的簽章金鑰。

定期旋轉你的簽章金鑰可以降低金鑰洩漏的風險。Logto 建議你至少每年旋轉一次簽章金鑰。

旋轉 OIDC 私有簽章金鑰​

使用下方 CLI 指令產生新的 OIDC 私有簽章金鑰。預設情況下，新金鑰會立即生效。若要分階段旋轉並讓用戶端有時間刷新 JWKS，可設定寬限期。

可用選項：

--type          （選填）JWT 的簽章金鑰演算法。
                可選值為 "rsa" 或 "ec"。預設為 "ec"。
--gracePeriod   （選填）分階段私鑰旋轉的寬限期（秒）。
                預設為 PRIVATE_KEY_ROTATION_GRACE_PERIOD 環境變數，若未設定則為 0。
logto db config rotate oidc.privateKeys --type rsa

例如，若要讓新私鑰在 4 小時後才生效，可這樣設定：

logto db config rotate oidc.privateKeys --type rsa --gracePeriod 14400

你也可以透過環境變數設定私鑰旋轉的預設寬限期：

PRIVATE_KEY_ROTATION_GRACE_PERIOD=14400

當你透過 Admin Console 或 Management API 旋轉時，請在 Logto 服務上設定此環境變數；若透過 CLI 旋轉，請在執行 CLI 指令的 shell 設定此變數。

使用下方 CLI 指令產生新的 OIDC Cookie 金鑰。Cookie 金鑰旋轉不支援寬限期。

logto db config rotate oidc.cookieKeys

之前的金鑰會怎樣？​

對於 OIDC 私鑰，Logto 在分階段旋轉期間最多保留三把金鑰：

  • Next：等待寬限期結束的新金鑰。
  • Current：目前用於簽署新發行 JWT 的金鑰。
  • Previous：最近剛被替換掉的金鑰，保留以確保現有 JWT 仍然有效。

寬限期結束後，Next 金鑰會變成 Current，舊的 Current 變成 Previous，最舊的 Previous 會被移除。

對於 Cookie 金鑰，Logto 會保留目前與上一把金鑰。刪除上一把金鑰時請特別小心，否則可能導致非預期問題。建議在確定所有用該金鑰簽署的現有階段或權杖都已過期後再移除。

疑難排解​

在 Cloudflare Zero Trust 中作為 OIDC Provider 使用 Logto​

如果你打算在 Cloudflare Zero Trust 中將 Logto 作為 OIDC provider，請注意其不支援使用 ECDSA 演算法的 OIDC provider。旋轉 OIDC 私有簽章金鑰時，請務必在旋轉指令中指定 --type rsa 以使用 RSA 演算法：

logto db config rotate oidc.privateKeys --type rsa