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

署名キー

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. Console > Signing keys に移動します。そこから、OIDC プライベートキーと OIDC クッキーキーの両方を管理できます。

  2. 署名キーをローテーションするには、「Rotate private keys」または「Rotate cookie keys」ボタンをクリックします。プライベートキーをローテーションする際には、署名アルゴリズムを変更するオプションがあります。

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

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

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

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

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

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

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