メインコンテンツまでスキップ

署名鍵

Logto の OIDC 署名鍵（「OIDC プライベート鍵」や「OIDC クッキー鍵」とも呼ばれます）は、Logto の サインインセッション で JWT（アクセス トークン や ID トークン）およびブラウザクッキーに署名するために使用される鍵です。これらの署名鍵は、Logto データベースの初期化時（オープンソース）や新しいテナント作成時（Cloud）に生成され、CLI（オープンソース）、Management API、またはコンソール UI から管理できます。

デフォルトでは、Logto は楕円曲線（EC）アルゴリズムを使用してデジタル署名を生成します。しかし、ユーザーが JWT 署名を検証する必要がある場合や、多くの古いツールが EC アルゴリズムをサポートしておらず（RSA のみサポート）、RSA 署名が必要なケースも多いため、プライベート鍵のローテーション機能と署名アルゴリズム（RSA および EC の両方を含む）の選択機能を実装しています。これにより、古い署名検証ツールを使用するサービスとの互換性が確保されます。

注記:

理論的には、署名鍵は漏洩してはならず、有効期限もありません。つまり、ローテーションの必要はありません。しかし、一定期間ごとに署名鍵をローテーションすることでセキュリティを強化できます。

仕組み​

  • OIDC プライベート鍵
    Logto インスタンスの初期化時に、公開鍵とプライベート鍵のペアが自動的に生成され、基盤となる OIDC プロバイダーに登録されます。これにより、Logto が新しい JWT（アクセス トークンや ID トークン）を発行する際、そのトークンはプライベート鍵で署名されます。同時に、JWT を受け取ったクライアントアプリケーションは、ペアとなる公開鍵を使ってトークン署名を検証し、トークンが第三者によって改ざんされていないことを確認できます。プライベート鍵は Logto サーバー上で保護されますが、公開鍵はその名の通り誰でもアクセス可能であり、OIDC エンドポイントの /oidc/jwks インターフェースから取得できます。署名鍵のアルゴリズムはプライベート鍵生成時に指定でき、Logto はデフォルトで EC（楕円曲線）アルゴリズムを使用します。管理者ユーザーは、プライベート鍵のローテーションによってデフォルトのアルゴリズムを RSA（Rivest-Shamir-Adleman）に変更できます。
  • OIDC クッキー鍵
    ユーザーがサインインまたはサインアップフローを開始すると、サーバー上で「OIDC セッション」が作成され、同時に一連のブラウザクッキーも生成されます。これらのクッキーにより、ブラウザは Logto Experience API を使ってサインイン、サインアップ、パスワードリセットなどの一連の操作をユーザーの代わりに実行できます。ただし、JWT とは異なり、クッキーは Logto OIDC サービス自身のみが署名・検証を行い、非対称暗号化は必要ありません。そのため、クッキー署名鍵にはペアとなる公開鍵や非対称暗号化アルゴリズムはありません。

コンソール UI から署名鍵をローテーションする​

Logto には「署名鍵ローテーション」機能があり、テナント内で新しい OIDC プライベート鍵およびクッキー鍵を作成できます。

  1. コンソール > テナント設定 > OIDC 設定 に移動します。ここで OIDC プライベート鍵と OIDC クッキー鍵の両方を管理できます。

  2. 署名鍵をローテーションするには、「プライベート鍵をローテーション」または「クッキー鍵をローテーション」ボタンをクリックします。プライベート鍵をローテーションする際、署名アルゴリズムを変更することも可能です。

  3. 使用中のすべての署名鍵が一覧表示されたテーブルが表示されます。OIDC プライベート鍵の場合、前の鍵は削除できますが、現在の鍵や次の鍵は削除できません。OIDC クッキー鍵の場合、前の鍵は削除できますが、現在の鍵は削除できません。

    ステータス説明
    Next段階的な OIDC プライベート鍵ローテーション用のステータスです。鍵は作成されていますが、猶予期間が終了して有効になるまで Logto は新しい JWT の署名にこの鍵を使用しません。
    Current現在 Logto が新しく発行する JWT やクッキーの署名に使用している鍵です。
    Previous以前使用されていたがローテーションされた鍵です。この鍵で署名された既存の JWT やクッキーは、有効期限が切れるか鍵が削除されるまで有効です。

ローテーションには以下の 3 つのアクションが含まれることを覚えておいてください：

  1. 新しい署名鍵の作成：OIDC プライベート鍵の場合、Logto は新しい鍵をまず「Next」として段階的に登録できるため、アプリケーションや API が新しい鍵で署名される前に /oidc/jwks エンドポイントから公開鍵を更新する時間を確保できます。
  2. 現在の鍵のローテーション：ローテーションが有効になると、「Next」鍵が「Current」となり、既存の「Current」鍵は「Previous」となります。前の鍵で署名されたトークンは引き続き有効です。
  3. 最も古い Previous 鍵の削除：Logto は「Previous」プライベート鍵を最大 1 つまで保持します。段階的な鍵が「Current」になる際、すでに「Previous」鍵が存在する場合は、より古い「Previous」鍵が削除されます。

Logto Cloud では、OIDC プライベート鍵のローテーションは 4 時間の猶予期間後に有効となります。この期間中、新しい鍵は JWKS で公開され、Logto が新しい JWT の署名に使用し始める前に準備されます。コンソールのテーブルでは、有効日時 列に「Next」鍵が「Current」になる時刻が表示されます。

セルフホスト OSS デプロイメントの場合、デフォルトのプライベート鍵ローテーション猶予期間は 0 秒であり、ローテーションは即時に行われます。段階的なローテーションを利用するには、Logto サービスの PRIVATE_KEY_ROTATION_GRACE_PERIOD 環境変数を設定するか、Management API の POST /api/configs/oidc/private-keys/rotate エンドポイント呼び出し時にリクエストボディで rotationGracePeriod 値を明示的に指定してください。

警告:

ローテーションが有効になる前に繰り返し署名鍵をローテーションすることは避けてください（意図的に段階的な「Next」鍵を置き換えたい場合を除く）。

唯一の「Previous」鍵を早期に削除すると、その鍵で署名された既存の JWT やクッキーが無効になる可能性があります。

JWT における EC および RSA 署名アルゴリズムの紹介