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

署名キー

Logto の OIDC 署名キー は、「OIDC プライベートキー」や「OIDC クッキーキー」としても知られ、Logto の サインインセッション で JWT（アクセス トークン と ID トークン）やブラウザクッキーを署名するために使用されます。これらの署名キーは、Logto データベースをシードする際（オープンソース）や新しいテナントを作成する際（Cloud）に生成され、CLI（オープンソース）、Management API、または Console 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 サービス自体によってのみ署名および検証され、非対称暗号化手段は必要ありません。したがって、クッキー署名キーにはペアになった公開鍵はなく、非対称暗号化アルゴリズムもありません。

Console UI から署名キーをローテーションする​

Logto は「署名キーのローテーション」機能を導入しており、テナント内で新しい OIDC プライベートキーとクッキーキーを作成できます。

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

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

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

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

ローテーションには次の 3 つのアクションが含まれることを忘れないでください：

  1. 新しい署名キーの作成：これにより、すべての アプリケーション と API が新しい署名キーを採用する必要があります。
  2. 現在のキーのローテーション：既存のキーはローテーション後に「以前」として指定され、新しく作成されたアプリケーションや API では使用されません。ただし、このキーで署名されたトークンは依然として有効です。
  3. 以前のキーの削除：ラベルが「以前」とされているキーは取り消され、テーブルから削除されます。
警告:

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

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

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