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

署名鍵

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 クッキー鍵の両方を管理できます。

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

  3. 使用中のすべての署名鍵が一覧表示されたテーブルが表示されます。注意：前の鍵は削除できますが、現在の鍵は削除できません。

    ステータス説明
    現在この鍵が現在アプリケーションや API でアクティブに使用されていることを示します。
    前回以前使用されていたがローテーションされた鍵を指します。この署名鍵で発行された既存のトークンは引き続き有効です。

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

  1. 新しい署名鍵の作成：これにより、すべての アプリケーション および API で新しい署名鍵の採用が必要となります。
  2. 現在の鍵のローテーション：既存の鍵はローテーション後「前回」として指定され、新規作成されるアプリケーションや API では使用されません。ただし、この鍵で署名されたトークンは引き続き有効です。
  3. 前回の鍵の削除：ステータスが「前回」となっている鍵は失効し、テーブルから削除されます。
警告:

署名鍵を連続して（2 回以上）ローテーションしないでください。すべての発行済みトークンが無効になる可能性があります。

  • OSS ユーザーの場合、署名鍵をローテーションした後、新しい署名鍵を有効にするには Logto インスタンスの再起動が必要です。
  • Cloud ユーザーの場合、ローテーション後すぐに新しい署名鍵が有効になりますが、署名鍵を連続して複数回ローテーションしないようご注意ください。

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