Actions トリガー: custom-token-exchange - API オブジェクト

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

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

​

api.access

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

​

api.access.deny(code, reason)

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

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

code · string

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

reason · string

トークン交換リクエストを拒否する理由を、人が読める形式で説明したものです。

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

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

};

​

api.access.rejectInvalidSubjectToken(reason)

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

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

reason · string

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

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

};

​

api.authentication

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

​

api.authentication.setUserById(user_id)

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

user_id · string

ユーザーの ID。既存のユーザーである必要があります。

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

​

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

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

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

注: Custom Token Exchange Action では、api.authentication.setUserByConnection または api.authentication.setUserById のいずれか一方のみを必ず呼び出す必要があります。

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 · optional

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

email_verified · boolean · optional

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

family_name · string · optional

ユーザーの姓。

given_name · string · optional

ユーザーの名。

name · string · optional

ユーザーのフルネーム。

nickname · string · optional

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

phone_number · string · optional

ユーザーの電話番号 (E.164 の推奨形式に従います) 。

phone_verified · boolean · optional

この電話番号が確認済みかどうか (true は確認済み、false は未確認) 。

picture · string · optional

ユーザーの画像を指す URI。

user_id · string

接続内でのユーザーの一意の識別子。

username · string · optional

ユーザーの username。

verify_email · boolean · optional

作成後にユーザーへ確認メールを送信するかどうか (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

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

​

api.authentication.setOrganization(organization_id_or_name)

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

organization_id_or_name · string

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

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.setOrganization('org_xS525r979AS33MSf');

  // 4. トランザクションのユーザーを設定する。setUserByConnection()を使用することもできます
  api.authentication.setUserById(subject_token.sub);

  return;
};

​

api.authentication.setActor(actor)

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

actor · actorparams

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

非表示 actor プロパティ

sub · string

act · dictionary · optional

非表示 act プロパティ

sub · string

act · dictionary · optional

非表示 act プロパティ

sub · string

act · dictionary · optional

表示 act プロパティ

sub · string

act · dictionary · optional

表示 act プロパティ

sub · string

act · undefined · optional

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. トランザクションのアクターを設定する
  api.authentication.setActor({ sub: actor_token.sub });

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

  return;
};

​

api.user

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

​

api.user.setAppMetadata(key, value)

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

key · string

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

value · unknown

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

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

​

api.user.setUserMetadata(key, value)

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

key · string

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

value · unknown

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

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

​

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 · optional

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

非表示 options のプロパティ

expires_at · number · optional

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

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

ttl · number · optional

このキャッシュエントリの存続時間をミリ秒で表した値です。 キャッシュされた値はこれより前に削除される場合がありますが、 指定された ttl を過ぎて保持されることはありません。

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