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

署名鍵

Logto の OIDC 署名鍵（「OIDC プライベート鍵」や「OIDC クッキー鍵」とも呼ばれます）は、Logto の サインインセッション で JWT（アクセス トークン や ID トークン）およびブラウザクッキーに署名するために使用される鍵です。これらの署名鍵は、Logto データベースの初期化時（オープンソース）や新しいテナントの作成時（Cloud）に生成され、CLI（オープンソース）、Management API、またはコンソール 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 クッキー鍵
    ユーザーがサインインやサインアップフローを開始すると、サーバー上で「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 署名アルゴリズムの紹介