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

署名鍵

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

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

注記:

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

仕組み​

  • OIDC プライベート鍵 Logto インスタンスの初期化時に、公開鍵とプライベート鍵のペアが自動的に生成され、基盤となる OIDC プロバイダーに登録されます。これにより、Logto が新しい JWT（アクセス トークン (Access token) または ID トークン (ID token)）を発行する際、そのトークンはプライベート鍵で署名されます。同時に、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 クッキー鍵の場合、前の鍵は削除できますが、現在の鍵は削除できません。

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

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

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

Logto Cloud では、OIDC プライベート鍵のローテーションは 4 時間の猶予期間後に有効となります。この期間中、新しい鍵は JWKS で公開され、Logto が新しい JWT の署名に使用し始める前に準備されます。コンソールのテーブルでは、有効日時 列で段階的な「次回」鍵が「現在」になるタイミングを確認できます。

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

警告:

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

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

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