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

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

コンソール > カスタム JWT に移動します。
カスタマイズできるアクセストークンには 2 種類あります：
- ユーザーアクセストークン：エンドユーザー向けに発行されるアクセストークン。例：Web アプリケーションやモバイルアプリケーション向け。
- マシン間通信 (M2M) アクセストークン：サービスやアプリケーション向けに発行されるアクセストークン。例：マシン間通信アプリケーション向け。
アクセストークンの種類によって、トークンペイロードのコンテキストが異なる場合があります。各種類ごとにトークンクレームを個別にカスタマイズできます。

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

注記:

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

Logto OSS ユーザー
開発環境を持つ Logto Cloud テナント
本番環境を持つ Logto Cloud 有料テナント（Pro テナントや Enterprise テナントを含む）

`getCustomJwtClaims()` 関数の実装

カスタム JWT 詳細ページで、カスタムトークンクレームスクリプトを記述するためのスクリプトエディタが利用できます。スクリプトは、カスタムクレームのオブジェクトを返す JavaScript 関数である必要があります。

ステップ 1: スクリプトの編集

左側のコードエディタを使ってスクリプトを編集します。デフォルトで空のオブジェクトを返す getCustomJwtClaims が用意されているので、ここからカスタムクレームを返すように関数を修正できます。

const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
  return {};
};

このエディタは JavaScript 言語サーバーを利用して、基本的な構文ハイライト、コード補完、エラーチェックを提供します。入力パラメータは型情報と jsDoc スタイルのドキュメントが付与されています。エディタの IntelliSense を利用して、入力オブジェクトのプロパティに正しくアクセスできます。詳細なパラメータ定義はページ右側で確認できます。

注記:

この関数はモジュールとしてエクスポートされます。関数名は getCustomJwtClaims のままにして、モジュールが正しく関数をエクスポートできるようにしてください。

ユーザーアクセストークン では、認証 (Authentication) コンテキストクレーム acr、amr、auth_time は Logto により予約されています（ステップアップ認証を参照）。スクリプトでこれらのキーを返した場合、Logto はそれらを無視し、認証 (Authentication) コンテキストを保持します。

ステップ 2: 入力パラメータ

getCustomJwtClaims 関数は、オブジェクトを入力パラメータとして受け取ります。入力オブジェクトには次のプロパティが含まれます：

token

トークンペイロードオブジェクト。このオブジェクトには、元のトークンクレームやメタデータが含まれており、スクリプト内で参照できます。

トークンペイロードオブジェクトやユーザーデータオブジェクトの詳細な型定義は、ページ右側で確認できます。エディタの IntelliSense でも、入力オブジェクトのプロパティに正しくアクセスできます。

ユーザーアクセストークンデータオブジェクト

プロパティ	説明	型
`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`

マシン間通信 (M2M) アクセストークンデータオブジェクト

プロパティ	説明	型
`jti`	一意の JWT ID	`string`
`aud`	トークンのオーディエンス (Audience)	`string`
`scope`	トークンのスコープ (Scope)	`string`
`clientId`	トークンのクライアント ID	`string`
`kind`	トークンの種類	`ClientCredentials`

context（ユーザーアクセストークンのみ利用可能）

context オブジェクトには、現在の認可 (Authorization) プロセスに関連するユーザーデータやグラントデータが含まれます。

ユーザーデータオブジェクト ユーザーアクセストークンの場合、Logto は追加のユーザーデータコンテキストを提供します。ユーザーデータオブジェクトには、すべてのユーザープロファイルデータや組織 (Organization) メンバーシップデータが含まれており、カスタムクレームの設定に利用できます。詳細はユーザーおよび組織を参照してください。
組織 (Organization) データオブジェクト 組織アクセストークン（特定の組織向けにリクエストされたアクセストークン）の場合、Logto は context.organization を通じて対象の組織を提供します。これにより、組織ごとのクレームを付与できます。例えば、Logto の組織 ID を組織のカスタムデータに保存された内部 ID にマッピングするなど。このデータオブジェクトは、トークンが特定の組織向けに発行された場合のみ存在し、以下を含みます：

プロパティ説明型
id 一意の組織 ID string
name 組織名 string
description 組織の説明 string | null
customData 組織のカスタムデータ Record<string, unknown>

詳細は組織を参照してください。
グラントデータオブジェクト ユーザーなりすまし (User impersonation) トークン交換によって付与されたユーザーアクセストークンの場合、Logto は追加のグラントデータコンテキストを提供します。グラントデータオブジェクトには、サブジェクトトークンからのカスタムコンテキストが含まれます。詳細はユーザーなりすましを参照してください。

プロパティ	説明	型
`id`	一意の組織 ID	`string`
`name`	組織名	`string`
`description`	組織の説明	`string \| null`
`customData`	組織のカスタムデータ	`Record<string, unknown>`

ユーザーインタラクションデータオブジェクト 特定のユーザーアクセストークンについて、現在の認可 (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 状態を検証した場合。この場合、スクリプト内で全ての検証レコードを適切に処理する必要があります。

各検証レコードの種類は、ユーザーインタラクションデータオブジェクト内に 1 回だけ存在します。

environmentVariables

右側の 環境変数を設定 セクションで、スクリプト用の環境変数を設定できます。これらの変数は、スクリプト内でハードコーディングしたくない機密情報や設定データ（例：API キー、シークレット、URL など）を保存するのに利用できます。

ここで設定したすべての環境変数はスクリプト内で利用可能です。入力パラメータの environmentVariables オブジェクトを使ってアクセスしてください。

api

api オブジェクトは、トークン発行プロセスに対して追加のアクセス制御を行うためのユーティリティ関数を提供します。api オブジェクトには次の関数が含まれます：

api.denyAccess(message?: string): void

api.denyAccess() 関数を使うことで、カスタムメッセージ付きでトークン発行プロセスを拒否できます。トークン発行プロセスに対して追加のアクセスバリデーションを強制したい場合に利用できます。

ランタイム API

カスタムアクセストークンスクリプトでは、Logto Cloud とセルフホスト Logto の両方で次の標準 Web API を利用できます：

fetch、Request、Response、Headers
Web Crypto（crypto および crypto.subtle 経由）
TextEncoder および TextDecoder
URL および URLSearchParams

例えば、Web Crypto を使って SHA-256 や HMAC-SHA-256 の値を計算できます：

const toHex = (buffer) =>
  [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, '0')).join('');

const sha256 = async (input) =>
  toHex(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input)));

const hmacSha256 = async (key, input) => {
  const encoder = new TextEncoder();
  const cryptoKey = await crypto.subtle.importKey(
    'raw',
    encoder.encode(key),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  return toHex(await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(input)));
};

スクリプトでパッケージのインポートはできません。Node.js 固有のグローバルやモジュールは、セルフホスト Logto と Logto Cloud 間で移植性がなく、サポートされているスクリプト契約の一部ではないため、使用しないでください。

ステップ 3: 外部データの取得

スクリプト内で標準の 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 完了後に得られる「追加トークンクレーム」）。実際のトークンペイロードやユーザーデータコンテキストは、トークン発行プロセスでスクリプトが実行される際に異なります。

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

getCustomJwtClaims() 関数の実装​

ステップ 1: スクリプトの編集​

ステップ 2: 入力パラメータ​

token​

context（ユーザー アクセス トークンのみ利用可能）​

environmentVariables​

api​

ランタイム API​

ステップ 3: 外部データの取得​

ステップ 4: スクリプトのテスト​