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');
  }

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

};

パラメータ

非表示パラメータ

string

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

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;
    }
  }

};

パラメータ

非表示パラメータ

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;
};

パラメータ

非表示パラメータ

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;
};

パラメータ

非表示パラメータ

string

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

customtokenexchangesetuserbyconnectionuserattributes

user_id を含むユーザーのプロファイル属性。email、name などのその他の属性は任意です。user_id フィールドは必須で、接続内でユーザーを一意に識別する識別子である必要があります。これは、ユーザーが存在するか、作成が必要かを判断するために使用されます。既存ユーザーの場合、この user_id は正規化されたユーザープロファイルの identities 配列を確認して取得できます。ユーザーがすでに存在する場合、次のユーザー属性は更新できません: email、email_verified、phone、phone_verified、username。これらが既存ユーザーの属性と一致しない場合、エラーが返されます。

表示 user_attributes プロパティ

string

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

boolean

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

string

ユーザーの姓。任意。

string

ユーザーの名。任意。

string

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

string

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

string

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

boolean

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

string

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

string

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

string

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

boolean

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

customtokenexchangesetuserbyconnectionoptions

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

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

表示 options プロパティ

string

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

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;
};

パラメータ

非表示パラメータ

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;
};

パラメータ

非表示パラメータ

actorparams

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

表示 actor プロパティ

string

dictionary

任意です。

表示 act プロパティ

string

dictionary

任意です。

表示 act プロパティ

string

dictionary

任意です。

表示 act プロパティ

string

dictionary

任意です。

表示 act プロパティ

string

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;
};

パラメータ

非表示パラメータ

string

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

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;
};

パラメータ

非表示パラメータ

string

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

unknown

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

`api.cache`

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

`api.cache.delete(key)`

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

非表示パラメータ

string

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

`api.cache.get(key)`

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

非表示パラメータ

string

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

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

指定したキーに文字列値をキャッシュへ保存または更新します。このキャッシュに保存された値は、設定されたトリガーのスコープ内でのみ使用できます。これらの値には、Actions Cache Limits が適用されます。この方法で保存された値の有効期間は、指定した ttl または expires_at の値までです。有効期間が指定されていない場合は、デフォルトで 15 分となります。有効期間は、Actions Cache Limits に記載されている最大期間を超えることはできません。重要: このキャッシュは、短期間のみ保持する一時的なデータ用に設計されています。指定された有効期間内であっても、後続のトランザクションでは項目を利用できない場合があります。 パラメータ

非表示パラメータ

string

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

string

保存するレコードの値。

cachesetoptions

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

表示 options プロパティ

number

Unix エポックからのミリ秒単位の絶対的な有効期限。キャッシュされたレコードはそれより前に削除される場合がありますが、指定した expires_at を超えて保持されることはありません。注: ttl の値も指定されている場合は、この値を指定しないでください。両方のオプションが指定されている場合は、 2 つのうち早い方の有効期限が使用されます。任意。

number

このキャッシュエントリのミリ秒単位の有効期間。キャッシュ値はそれより前に削除される場合がありますが、指定した ttl を超えて保持されることはありません。注: expires_at の値も指定されている場合は、この値を指定しないでください。両方のオプションが指定されている場合は、 2 つのうち早い方の有効期限が使用されます。任意。

`api.transaction`

[早期アクセス] トランザクションを変更します。

`api.transaction.setMetadata(key, value)`

[早期アクセス] 指定したキーのトランザクションメタデータに値を保存または更新します。このメソッドで変更したメタデータは、 event.transaction.metadata オブジェクトにリアルタイムで反映されます。

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // トランザクションの間、Actions 間で共有するデータを保存します。
  api.transaction.setMetadata('subject_verified', true);
  api.transaction.setMetadata('risk_score', 42);

  // イベントからリアルタイムで読み取ります。
  console.log(event.transaction.metadata.risk_score); // 42

  // `null` を渡すと、以前に設定したプロパティを削除できます。
  api.transaction.setMetadata('risk_score', null);
};

パラメータ

非表示パラメータ

string

設定するプロパティのキー。

object

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

Credentials Exchange

Custom Email Provider

Custom Phone Provider

Custom Token Exchange

Event Stream

Password Reset Post Challenge

Post Change Password

Post Login

Post User Registration

Pre User Registration

Send Phone Message

API オブジェクト

`api.access`

`api.access.deny(code, reason)`

`api.access.rejectInvalidSubjectToken(reason)`

`api.authentication`

`api.authentication.setUserById(user_id)`

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

`api.authentication.setOrganization(organization_id_or_name)`

`api.authentication.setActor(actor)`

`api.user`

`api.user.setAppMetadata(key, value)`

`api.user.setUserMetadata(key, value)`

`api.cache`

`api.cache.delete(key)`

`api.cache.get(key)`

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

`api.transaction`

`api.transaction.setMetadata(key, value)`

​api.access

​api.access.deny(code, reason)

​api.access.rejectInvalidSubjectToken(reason)

​api.authentication

​api.authentication.setUserById(user_id)

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

​api.authentication.setOrganization(organization_id_or_name)

​api.authentication.setActor(actor)

​api.user

​api.user.setAppMetadata(key, value)

​api.user.setUserMetadata(key, value)

​api.cache

​api.cache.delete(key)

​api.cache.get(key)

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

​api.transaction

​api.transaction.setMetadata(key, value)

`api.access`

`api.access.deny(code, reason)`

`api.access.rejectInvalidSubjectToken(reason)`

`api.authentication`

`api.authentication.setUserById(user_id)`

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

`api.authentication.setOrganization(organization_id_or_name)`

`api.authentication.setActor(actor)`

`api.user`

`api.user.setAppMetadata(key, value)`

`api.user.setUserMetadata(key, value)`

`api.cache`

`api.cache.delete(key)`

`api.cache.get(key)`

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

`api.transaction`

`api.transaction.setMetadata(key, value)`