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

カスタムトークンクレームスクリプトの作成

アクセス トークン (Access token)カスタムクレーム (Custom claims) を追加するには、それらのクレームを含むオブジェクトを返すスクリプトを用意する必要があります。スクリプトは、カスタムクレームを含むオブジェクトを返す JavaScript 関数として記述します。

  1. コンソール > カスタム JWT に移動します。

  2. カスタマイズ可能なアクセス トークン (Access token) クレームには、2 種類あります:

    • ユーザーアクセス トークン (User access token):エンドユーザー向けに発行されるアクセス トークン (Access token)。例:Web アプリケーションやモバイルアプリケーション向け。
    • マシン間通信アクセス トークン (Machine-to-Machine access token):サービスやアプリケーション向けに発行されるアクセス トークン (Access token)。例:マシン間通信アプリケーション 向け。

    アクセス トークン (Access token) の種類ごとに、トークンペイロードのコンテキストが異なる場合があります。各種類ごとにトークンクレームを個別にカスタマイズできます。

    カスタマイズしたいアクセス トークン (Access token) の種類を選択し、カスタムクレームを追加 ボタンをクリックして新しいスクリプトを作成します。

注記:

カスタムトークンクレーム機能は、以下のユーザーのみ利用可能です:

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 IDstring
    audトークンのオーディエンス (Audience)string
    scopeトークンのスコープ (Scope)string
    clientIdトークンのクライアント IDstring
    accountIdトークンのユーザー IDstring
    expiresWithSessionトークンがセッションとともに失効するかboolean
    grantIdトークンの現在の認証 (Authentication) グラント IDstring
    gtyトークンのグラントタイプstring
    kindトークンの種類AccessToken
  • マシン間通信アクセス トークン (Machine-to-machine access token) データオブジェクト
    プロパティ説明
    jti一意の JWT IDstring
    audトークンのオーディエンス (Audience)string
    scopeトークンのスコープ (Scope)string
    clientIdトークンのクライアント IDstring
    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現在のユーザーインタラクションのユーザー IDstring
    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: スクリプトのテスト

スクリプトを保存する前に必ずテストしてください。ページ右側の テストコンテキスト タブをクリックし、テスト用のモックトークンペイロードやユーザーデータコンテキストを編集できます。

エディタ右上の テスト実行 をクリックすると、モックデータでスクリプトを実行できます。スクリプトの出力は テスト結果 ドロワーに表示されます。

カスタム JWT スクリプトのテスト
注記:

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

作成 ボタンをクリックしてスクリプトを保存します。カスタムトークンクレームスクリプトは保存され、アクセス トークン (Access token) 発行プロセスに適用されます。