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

カスタムトークンクレーム

Logto は、アクセス トークン (JWT / 不透明トークン) 内にカスタマイズされたクレームを追加する柔軟性を提供します。この機能により、ビジネスロジックのための追加情報をトークン内に安全に送信し、不透明トークンの場合はイントロスペクションを通じて取得できます。

はじめに​

アクセス トークン は、認証 (Authentication) と認可 (Authorization) プロセスにおいて重要な役割を果たし、サブジェクトのアイデンティティ情報と権限を運び、Logto サーバー（認証サーバーまたはアイデンティティプロバイダー (IdP) として機能）、ウェブサービスサーバー（リソースプロバイダー）、クライアントアプリケーション（クライアント）間で渡されます。

トークンクレーム は、エンティティまたはトークン自体に関する情報を提供するキーと値のペアです。クレームには、ユーザー情報、トークンの有効期限、権限、および認証 (Authentication) と認可 (Authorization) プロセスに関連するその他のメタデータが含まれる場合があります。

Logto には 2 種類のアクセス トークンがあります：

  • JSON Web Token: JSON Web Token (JWT) は、クレームを安全かつクライアントが読み取れる形式でエンコードする人気のあるフォーマットです。sub、iss、aud などの一般的なクレームは、OAuth 2.0 プロトコルに沿って使用されます（詳細は このリンク を参照）。JWT トークンは、消費者が追加の検証ステップなしでクレームに直接アクセスできるようにします。Logto では、特定のリソースまたは組織の認可リクエストをクライアントが初期化する際に、デフォルトで JWT 形式でアクセス トークンが発行されます。
  • 不透明トークン: 不透明トークン は自己完結型ではなく、常に トークンイントロスペクション エンドポイントを介した追加の検証ステップが必要です。その不透明な形式にもかかわらず、不透明トークンはクレームを取得し、当事者間で安全に送信するのに役立ちます。トークンクレームは Logto サーバーに安全に保存され、クライアントアプリケーションがトークンイントロスペクションエンドポイントを介してアクセスします。認可リクエストに特定のリソースまたは組織が含まれていない場合、不透明形式でアクセス トークンが発行されます。これらのトークンは主に OIDC userinfo エンドポイントやその他の一般的な目的で使用されます。

多くの場合、標準のクレームではアプリケーションの特定のニーズを満たすことができません。JWT または不透明トークンを使用している場合でも同様です。これに対処するために、Logto はアクセス トークン内にカスタマイズされたクレームを追加する柔軟性を提供します。この機能により、ビジネスロジックのための追加情報をトークン内に安全に送信し、不透明トークンの場合はイントロスペクションを通じて取得できます。

カスタムトークンクレームはどのように機能しますか？​

Logto は、getCustomJwtClaims コールバック関数を通じて アクセス トークン にカスタムクレームを挿入することを許可します。getCustomJwtClaims 関数の実装を提供して、カスタムクレームのオブジェクトを返すことができます。返された値は元のトークンペイロードとマージされ、最終的なアクセス トークンを生成するために署名されます。

警告:

Logto の組み込みトークンクレームは上書きまたは変更できません。カスタムクレームは追加のクレームとしてトークンに追加されます。組み込みクレームと競合するカスタムクレームがある場合、それらのカスタムクレームは無視されます。

Logto を使用して JWT アクセス トークンにカスタムクレームを追加し、認可を強化する