API オブジェクト

custom-token-exchange Action トリガーの API オブジェクトについて説明します。

custom-token-exchange Actions トリガーの API オブジェクトには、以下が含まれます。

​

api.access

リクエストの拒否など、トークン交換リクエストへのアクセスを変更します。

​

api.access.deny(code, reason)

現在のトークン交換を拒否として扱います。

無効なサブジェクトトークンを理由にリクエストを拒否する場合は、サブジェクトトークンに対するブルートフォース試行と、リクエストを拒否するその他の理由を区別するため、代わりに api.access.rejectInvalidSubjectToken を使用することを推奨します。

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに認可ポリシーを適用する
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // ユーザーが認可されている場合は、以下のように処理を続行する

};

パラメータ

非表示 パラメータ

code · string

トークン交換を拒否する根拠となるエラーコード。invalid_request、server_error、または任意のカスタムコードを指定できます

reason · string

トークン交換リクエストを拒否する理由を、人が理解しやすい形式で説明します。

​

api.access.rejectInvalidSubjectToken(reason)

リクエストで指定されたサブジェクトトークンを無効として扱います。これにより、リクエストは “invalid_request” エラーコードで拒否されます。

また、無効なサブジェクトトークンが指定されたことが攻撃対策機能に通知されるため、 サブジェクトトークンに対するブルートフォース攻撃を防ぐための保護を適用できます。

exports.onExecuteCustomTokenExchange = async (event, api) => {

  try {
    // subject_token を検証
    const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
    // トランザクションに使用するユーザーを設定
    api.authentication.setUserById(subject_token.id);

  } catch (error) {
    if (error.message === 'Invalid Token') {
      // subject_token が無効であることが原因の場合
      console.error('Invalid Token error');
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      // その他の予期しないエラーが発生した場合は、サーバーエラーをスロー
      throw error;
    }
  }

};

パラメータ

非表示 パラメータ

reason · string

トークン交換リクエストを拒否する理由を、人が理解しやすい形式で説明します。

​

api.authentication

サブジェクトトークンの認証結果を示し、トークンの発行先となるユーザーを指定します。

​

api.authentication.setUserById(user_id)

userId を指定して、subject_token に対応するユーザーを指定します。トークン交換リクエストでは、このユーザーのトークンが発行されます。 指定するユーザーは既存のユーザーである必要があります。 注: カスタムトークン交換 Action では、api.authentication.setUserByConnection または api.authentication.setUserById のいずれか一方のみを呼び出す必要があります。

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに対して認可ポリシーを適用
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. トランザクションのユーザーを設定
  api.authentication.setUserById(subject_token.sub);

  return;
};

パラメータ

非表示 パラメータ

user_id · string

既存ユーザーのIDを指定します。

​

api.authentication.setUserByConnection(connection_name, user_attributes, options)

接続とユーザー属性を指定して、subject_token に対応するユーザーを設定します。 トークン交換リクエストでは、このユーザーのトークンが発行されます。

既存のユーザーまたは新規ユーザーを指定できます。ユーザーが存在しない場合は作成されます。 ユーザー_profile の user_id プロパティを使用して、ユーザーがすでに存在するかどうかを判断します。

注: カスタムトークン交換 Action では、api.authentication.setUserByConnection または api.authentication.setUserById のいずれか一方を必ず呼び出す必要があります。

Set user by connection with full profile attributes

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに認可ポリシーを適用する
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. トランザクションのユーザーを設定する
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: subject_token.email_verified,
      phone_number: subject_token.phone_number,
      phone_verified: subject_token.phone_number_verified,
      username: subject_token.preferred_username,
      name: subject_token.name,
      given_name: subject_token.given_name,
      family_name: subject_token.family_name,
      nickname: subject_token.nickname,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};

Create a user without verifying email

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // ユーザーを作成するが、メールアドレスは検証しない
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: false,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};

パラメータ

非表示 パラメータ

connection_name · string

ユーザーを保存する接続の名前。

user_attributes · customtokenexchangesetuserbyconnectionuserattributes

user_id を含むユーザーのプロファイル属性。email、name などのその他の属性は任意です。

user_id フィールドは必須で、接続内でユーザーを一意に識別する識別子である必要があります。 これは、ユーザーが存在するか、作成が必要かを判断するために使用されます。既存ユーザーの場合、この user_id は正規化されたユーザープロファイルの identities 配列を確認して取得できます。

ユーザーがすでに存在する場合、次のユーザー属性は更新できません: email、email_verified、phone、phone_verified、username。 これらが既存ユーザーの属性と一致しない場合、エラーが返されます。

表示 user_attributes プロパティ

email · string

ユーザーのメールアドレス。 任意。

email_verified · boolean

このメールアドレスが確認済み (true) か、未確認 (false) か。 任意。

family_name · string

ユーザーの姓。 任意。

given_name · string

ユーザーの名。 任意。

name · string

ユーザーのフルネーム。 任意。

nickname · string

ユーザーのニックネーム。 任意。

phone_number · string

ユーザーの電話番号 (E.164 の推奨形式) 。 任意。

phone_verified · boolean

この電話番号が確認済み (true) か、未確認 (false) か。 任意。

picture · string

ユーザーのプロフィール画像を指す URI。 任意。

user_id · string

接続内でユーザーを一意に識別する識別子。

username · string

ユーザーのユーザー名。 任意。

verify_email · boolean

作成後にユーザーへ確認メールを送信するか (true) 、送信しないか (false) 。 任意。

options · customtokenexchangesetuserbyconnectionoptions

setUserByConnection コマンドの動作を制御するオプション。

• creationBehavior - 接続内に指定した user_id を持つユーザーが存在しない場合に適用する動作。 ‘create_if_not_exists’ を指定すると、指定されたユーザー属性を使用して新しいユーザーが作成されます。 ‘none’ を指定すると、ユーザーは作成されず、ユーザーが存在しない場合はエラーが返されます。

• updateBehavior - 接続内に指定した user_id を持つユーザーがすでに存在する場合に適用する動作。 ‘replace’ を指定すると、既存ユーザーの属性が指定された ユーザー属性に置き換えられます。‘none’ を指定すると、既存ユーザーは変更されません。

表示 options プロパティ

creationBehavior · string

接続内に指定した user_id を持つユーザーが存在しない場合に適用する動作。 許可される値: create_if_not_exists、none

updateBehavior · string

接続内に指定した user_id を持つユーザーがすでに存在する場合に適用する動作。 許可される値: none、replace

​

api.authentication.setOrganization(organization_id_or_name)

トークン交換に関連付けられたユーザーのorganizationを設定します。

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに対して認可ポリシーを適用する
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. トランザクションに organization を設定する
  api.authentication.setOrganization('org_xS525r979AS33MSf');

  // 4. トランザクションにユーザーを設定する。setUserByConnection() を使ってもよい
  api.authentication.setUserById(subject_token.sub);

  return;
};

パラメータ

非表示 パラメータ

organization_id_or_name · string

ユーザーに設定するorganizationのIDまたは名前。

​

api.authentication.setActor(actor)

サブジェクトに代わって操作を行うエンティティを表すため、トークン交換のアクターを設定します。 setUserById または SetUserByConnection コマンドと併用する必要があります。setActor の呼び出しは任意です。 リクエストで actor_token を受信しても、act claim が自動的に生成されることはありません。Action でこのメソッドを明示的に呼び出す必要があります。 トランザクションにアクターが設定されている場合、リフレッシュトークンは発行されません。

exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
  const actor_token = await validateToken(event.transaction.actor_token, jwksUri);

  // 2. トランザクションの actor を設定する
  api.authentication.setActor({ sub: actor_token.sub });

  // 3. トランザクションのユーザーを設定する
  api.authentication.setUserById(subject_token.sub);

  return;
};

パラメータ

非表示 パラメータ

actor · actorparams

委譲チェーンを表すネストされたオブジェクトです。act レベルは最大4つまで追加できます (root actorを含めて合計5つのactor) 。各レベルで sub フィールドが必須です。さらに、最大5つの カスタムプロパティ (string、boolean、numberの値) を指定できます。

表示 actor プロパティ

sub · string

act · dictionary

任意です。

表示 act プロパティ

sub · string

act · dictionary

任意です。

表示 act プロパティ

sub · string

act · dictionary

任意です。

表示 act プロパティ

sub · string

act · dictionary

任意です。

表示 act プロパティ

sub · string

act · dictionary

任意です。

​

api.user

サブジェクトトークンに対応するユーザーの変更をリクエストします。

​

api.user.setAppMetadata(key, value)

サブジェクトトークンに対応するユーザーのアプリケーション固有のメタデータを設定します。

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // トランザクションのユーザーを設定する
  api.authentication.setUserById(subject_token.id);

  // subject_token に含まれる情報に基づいてユーザーグループを設定する
  api.user.setAppMetadata('group', subject_token.group);

  return;
};

パラメータ

非表示 パラメータ

key · string

設定するメタデータプロパティ。

value · unknown

メタデータプロパティ値。null を設定すると、 メタデータプロパティを削除できます。

​

api.user.setUserMetadata(key, value)

サブジェクトトークンに対応するユーザーの一般メタデータを設定します。

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // トランザクションのユーザーを設定する
  api.authentication.setUserById(subject_token.id);

  // subject_token に含まれる情報に基づいて、ユーザーの preferred_locale を設定する
  api.user.setUserMetadata('preferred_locale', subject_token.locale);

  return;
};

パラメータ

非表示 パラメータ

key · string

設定するメタデータプロパティ。

value · unknown

メタデータプロパティの値。この値を null に設定すると、メタデータプロパティを削除できます。

​

api.cache

実行をまたいで保持されるデータを保存・取得します。

​

api.cache.delete(key)

指定されたキーにキャッシュ値を表すレコードが存在する場合、そのレコードを削除します。

パラメータ

非表示 パラメータ

key · string

削除するキャッシュレコードのキー。

​

api.cache.get(key)

指定されたキーにキャッシュ内のレコードが存在する場合、そのキャッシュ値に関するレコードを取得します。レコードが見つかった場合、キャッシュ値は返されるオブジェクトの value プロパティに格納されています。

パラメータ

非表示 パラメータ

key · string

キャッシュに保存されているレコードのキー。

​

api.cache.set(key, value, options)

指定したキーに文字列値をキャッシュへ保存または更新します。

このキャッシュに保存された値は、設定されたトリガーのスコープ内でのみ使用できます。 これらの値には、Actions Cache Limits が適用されます。

この方法で保存された値の有効期間は、指定した ttl または expires_at の値までです。有効期間が指定されていない場合は、デフォルトで 15 分となります。有効期間は、Actions Cache Limits に記載されている最大 期間を超えることはできません。

重要: このキャッシュは、短期間のみ保持する一時的なデータ用に設計されています。指定された有効期間内であっても、後続のトランザクションでは 項目を利用できない場合があります。

パラメータ

非表示 パラメータ

key · string

保存するレコードのキー。

value · string

保存するレコードの値。

options · cachesetoptions

キャッシュの動作を調整するためのオプション。 任意。

表示 options プロパティ

expires_at · number

Unix エポックからのミリ秒単位の絶対的な有効期限。 キャッシュされたレコードはそれより前に削除される場合がありますが、 指定した expires_at を超えて保持されることはありません。

注: ttl の値も指定されている場合は、この値を 指定しないでください。両方のオプションが指定されている場合は、 2 つのうち早い方の有効期限が使用されます。 任意。

ttl · number

このキャッシュエントリのミリ秒単位の有効期間。 キャッシュ値はそれより前に削除される場合がありますが、 指定した ttl を超えて保持されることはありません。

注: expires_at の値も指定されている場合は、この値を 指定しないでください。両方のオプションが指定されている場合は、 2 つのうち早い方の有効期限が使用されます。 任意。