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

カスタムアクセス トークン (Custom access token)

Logto では、アクセス トークン（JWT / 不透明トークン (Opaque token)）内にカスタムクレーム (Claim) を追加する柔軟性を提供しています。この機能により、ビジネスロジックに必要な追加情報をトークン内に安全に含めることができ、不透明トークン (Opaque token) の場合はイントロスペクション経由で取得できます。

はじめに​

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

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

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

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

多くの場合、標準のクレーム (Claim) だけではアプリケーションの特定のニーズを満たせません。JWT でも不透明トークン (Opaque token) でも同様です。これに対応するため、Logto ではアクセス トークン内にカスタムクレーム (Claim) を追加する柔軟性を提供しています。この機能により、ビジネスロジックに必要な追加情報をトークン内に安全に含めることができ、不透明トークン (Opaque token) の場合はイントロスペクション経由で取得できます。

カスタムトークンクレーム (Claim) の仕組み​

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

備考:

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

警告:

セキュリティ注意：セルフホスト型デプロイメントでは、カスタム JWT スクリプトは Logto サーバープロセスと同じ権限で実行されます。この機能は信頼できる管理者のみを対象としています。信頼できないユーザーや権限の低いユーザーに、これらのスクリプトの作成・変更・テストを許可しないでください。

Logto で JWT アクセス トークンにカスタムクレーム (Claim) を追加して認可 (Authorization) を強化する