カスタムトークンクレームスクリプトの作成
アクセス トークン (Access token) に カスタムクレーム (Custom claims) を追加するには、それらのクレームを含むオブジェクトを返すスクリプトを用意する必要があります。スクリプトは、カスタムクレームを含むオブジェクトを返す JavaScript
関数として記述します。
-
コンソール > カスタム JWT に移動します。
-
カスタマイズ可能なアクセス トークン (Access token) クレームには、2 種類あります:
- ユーザーアクセス トークン (User access token):エンドユーザー向けに発行されるアクセス トークン (Access token)。例:Web アプリケーションやモバイルアプリケーション向け。
- マシン間通信アクセス トークン (Machine-to-Machine access token):サービスやアプリケーション向けに発行されるアクセス トークン (Access token)。例:マシン間通信アプリケーション 向け。
アクセス トークン (Access token) の種類ごとに、トークンペイロードのコンテキストが異なる場合があります。各種類ごとにトークンクレームを個別にカスタマイズできます。
カスタマイズしたいアクセス トークン (Access token) の種類を選択し、カスタムクレームを追加 ボタンをクリックして新しいスクリプトを作成します。
カスタムトークンクレーム機能は、以下のユーザーのみ利用可能です:
- Logto OSS ユーザー
- 開発環境を持つ Logto Cloud テナント
- 本番環境を持つ Logto Cloud 有料テナント(Pro テナントおよび Enterprise テナント を含む)
getCustomJwtClaims()
関数の実装
カスタム JWT 詳細ページで、カスタムトークンクレームスクリプトを記述するためのスクリプトエディタが利用できます。スクリプトは、カスタムクレームのオブジェクトを返す JavaScript
関数である必要があります。

ステップ 1: スクリプトの編集
左側のコードエディタを使ってスクリプトを編集します。デフォルトで空のオブジェクトを返す getCustomJwtClaims
が用意されているので、ここからカスタムクレームのオブジェクトを返すように関数を修正できます。
const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
return {};
};
このエディタは JavaScript 言語サーバーを使用しており、基本的な構文ハイライト、コード補完、エラー検出を提供します。入力パラメータは型情報と jsDoc スタイルでドキュメント化されています。エディタの IntelliSense を利用して、入力オブジェクトのプロパティに正しくアクセスできます。詳細なパラメータ定義はページ右側に表示されます。
この関数はモジュールとしてエクスポートされます。関数名は getCustomJwtClaims
のままにして、モジュールが正しく関数をエクスポートできるようにしてください。
ステップ 2: 入力パラメータ
getCustomJwtClaims
関数は、オブジェクトを入力パラメータとして受け取ります。入力オブジェクトには次のプロパティが含まれます:
token
トークンペイロードオブジェクト。このオブジェクトには、元のトークンクレームやスクリプトで参照可能なメタデータが含まれます。
トークンペイロードオブジェクトやユーザーデータオブジェクトの詳細な型定義は、ページ右側で確認できます。エディタの IntelliSense も、入力オブジェクトのプロパティへのアクセスをサポートします。
- ユーザーアクセス トークン (User access token) データオブジェクト
プロパティ 説明 型 jti
一意の JWT ID string
aud
トークンのオーディエンス (Audience) string
scope
トークンのスコープ (Scope) string
clientId
トークンのクライアント ID string
accountId
トークンのユーザー ID string
expiresWithSession
トークンがセッションとともに失効するか boolean
grantId
トークンの現在の認証 (Authentication) グラント ID string
gty
トークンのグラントタイプ string
kind
トークンの種類 AccessToken
- マシン間通信アクセス トークン (Machine-to-machine access token) データオブジェクト
プロパティ 説明 型 jti
一意の JWT ID string
aud
トークンのオーディエンス (Audience) string
scope
トークンのスコープ (Scope) string
clientId
トークンのクライアント ID string
kind
トークンの種類 ClientCredentials
context(ユーザーアクセス トークン (User access token) のみ利用可能)
context オブジェクトには、現在の認可 (Authorization) プロセスに関連するユーザーデータやグラントデータが含まれます。
-
ユーザーデータオブジェクト ユーザーアクセス トークン (User access token) の場合、Logto は追加のユーザーデータコンテキストを提供します。ユーザーデータオブジェクトには、カスタムクレームの設定に必要なすべてのユーザープロファイルデータや組織 (Organization) メンバーシップデータが含まれます。詳細は ユーザー および 組織 をご確認ください。
-
グラントデータオブジェクト なりすましトークン交換によって付与されたユーザーアクセス トークン (User access token) の場合、Logto は追加のグラントデータコンテキストを提供します。グラントデータオブジェクトには、サブジェクトトークンからのカスタムコンテキストが含まれます。詳細は ユーザーなりすまし をご確認ください。
-
ユーザーインタラクションデータオブジェクト 特定のユーザーアクセス トークン (User access token) について、現在の認可 (Authorization) セッションのユーザーインタラクション詳細にアクセスする必要がある場合があります。たとえば、サインインに使用されたエンタープライズシングルサインオン (SSO) のアイデンティティを取得したい場合などです。このユーザーインタラクションデータオブジェクトには、ユーザーが直近で送信したインタラクションデータが含まれます:
プロパティ 説明 型 interactionEvent
現在のユーザーインタラクションのイベント SignIn
またはRegister
userId
現在のユーザーインタラクションのユーザー ID string
verificationRecords
インタラクション中にユーザーが本人確認のために提出した認証記録のリスト VerificationRecord[]
検証記録の型:
// VerificationType.Password
{
id: string;
type: 'Password';
identifier: {
type: 'username' | 'email' | 'phone' | 'userId';
value: string;
}
verified: boolean;
}// VerificationType.EmailVerificationCode
{
id: string;
templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
verified: boolean;
type: 'EmailVerificationCode';
identifier: {
type: 'email';
value: string;
}
}// VerificationType.PhoneVerificationCode
{
id: string;
templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
verified: boolean;
type: 'PhoneVerificationCode';
identifier: {
type: 'phone';
value: string;
}
}// VerificationType.Social
{
id: string;
type: 'Social';
connectorId: string;
socialUserInfo?: {
id: string;
email?: string | undefined;
phone?: string | undefined;
name?: string | undefined;
avatar?: string | undefined;
rawData?: Record<string, unknown> | undefined;
} | undefined;
}// VerificationType.EnterpriseSso
{
id: string;
type: 'EnterpriseSso';
connectorId: string;
enterpriseUserInfo?: {
id: string;
email?: string | undefined;
phone?: string | undefined;
name?: string | undefined;
avatar?: string | undefined;
[key: string]?: unknown;
} | undefined;
issuer?: string | undefined;
}// VerificationType.Totp (MFA)
{
id: string;
type: 'Totp';
userId: string;
verified: boolean;
}// VerificationType.WebAuthn (MFA)
{
id: string;
type: 'WebAuthn';
userId: string;
verified: boolean;
}// VerificationType.BackupCode (MFA)
{
id: string;
type: "BackupCode";
userId: string;
code?: string | undefined;
}// VerificationType.OneTimeToken
{
id: string;
type: "OneTimeToken";
verified: boolean;
identifier: {
type: "email";
value: string;
};
oneTimeTokenContext?: {
jitOrganizationIds?: string[] | undefined;
} | undefined;
}注記:ユーザーインタラクションデータオブジェクトには、複数の検証記録が含まれる場合があります。特に、ユーザーが複数回サインインや登録プロセスを経ている場合です。
例:ユーザーが
Social
検証記録でサインインし、その後EmailVerificationCode
検証記録で新しいメールアドレスを紐付け、さらにTotp
検証記録で MFA 状態を検証した場合など。この場合、スクリプト内で全ての検証記録を適切に処理する必要があります。各検証記録の種類は、ユーザーインタラクションデータオブジェクト内に一度だけ存在します。
environmentVariables
右側の 環境変数の設定 セクションで、スクリプト用の環境変数を設定できます。これらの変数は、スクリプト内でハードコーディングしたくない機密情報や設定データ(例:API キー、シークレット、URL など)を保存するのに利用できます。
ここで設定したすべての環境変数は、スクリプト内で利用可能です。入力パラメータの environmentVariables
オブジェクトを使ってアクセスします。
api
api
オブジェクトは、トークン発行プロセスに対して追加のアクセス制御を行うためのユーティリティ関数群を提供します。api
オブジェクトには次の関数が含まれます:
api.denyAccess(message?: string): void
api.denyAccess()
関数は、カスタムメッセージ付きでトークン発行プロセスを拒否できます。トークン発行プロセスに対して追加のアクセスバリデーションを強制したい場合に利用できます。
ステップ 3: 外部データの取得
スクリプト内で node 組み込みの fetch
関数を使って外部データを取得できます。fetch
関数は Promise ベースで、外部 API への HTTP リクエストを行えます。
const getCustomJwtClaims = async ({ environmentVariables }) => {
const response = await fetch('https://api.example.com/data', {
headers: {
Authorization: `Bearer ${environmentVariables.API_KEY}`,
},
});
const data = await response.json();
return {
data,
};
};
外部データの取得は、トークン発行プロセスに遅延をもたらす可能性があるため注意してください。外部 API が十分に信頼でき、かつ高速であることを確認してください。
さらに:
- スクリプト内でエラーやタイムアウトを適切に処理し、トークン発行プロセスがブロックされないようにしてください。
- 適切な認可 (Authorization) ヘッダーを使用し、外部 API への不正アクセスを防止してください。
ステップ 4: スクリプトのテスト
スクリプトを保存する前に必ずテストしてください。ページ右側の テストコンテキスト タブをクリックし、テスト用のモックトークンペイロードやユーザーデータコンテキストを編集できます。
エディタ右上の テスト実行 をクリックすると、モックデータでスクリプトを実行できます。スクリプトの出力は テスト結果 ドロワーに表示されます。

テスト結果は、モックデータを使った getCustomJwtClaims
関数の出力です(シーケンス図 のステップ 3 で得られる「追加トークンクレーム」)。実際のトークンペイロードやユーザーデータコンテキストは、トークン発行プロセスでスクリプトが実行される際に異なります。
作成 ボタンをクリックしてスクリプトを保存します。カスタムトークンクレームスクリプトは保存され、アクセス トークン (Access token) 発行プロセスに適用されます。