アクションを使用したリフレッシュトークン

アクションを使ったリフレッシュトークンの管理について説明します。

現在、アクションを使ったリフレッシュトークンはプライベート早期アクセスの段階であり、エンタープライズプランのお客様が利用できます。この機能へのアクセスは、担当の技術アカウント管理者（TAM）を通じてリクエストできます。Auth0のリリース段階については、「製品のリリース段階」をお読みください。

リフレッシュトークンにアクションを使用すると、認証後のリスク検出と応答機能を構成して、アプリケーションとユーザーを侵害されたリフレッシュトークンから保護することができます。リフレッシュトークンの有効期限を動的にカスタマイズすることもできます。

• event.refresh_token ：creation、expiry dates、associated clients、resource servers、deviceのコンテキストなどの関連情報と、ブラウザーベースのフローにsession_idを提供します。
• api.refreshToken ：セッションを取り消すか、有効期限日を変更することで、既存のリフレッシュトークンを管理することができます。

これを容易にするために、ログイン後のアクションには以下の2つの重要なオブジェクトがあります。

event.refresh_tokenとapi.refreshTokenオブジェクトは両方とも、リフレッシュトークンの交換トランザクションに対応しています。

event.refresh_tokenオブジェクトを使用すると、last_exchange_atプロパティを確認し、現在のトランザクションに関してリスクを評価することができます。event.refresh_tokenオブジェクトをevent.authenticationなど、他のイベントオブジェクトと組み合わせることもできます。

• イベントオブジェクト：フレッシュトークンのイベントオブジェクトとプロパティについて説明します。
• APIオブジェクト：フレッシュトークンのAPIオブジェクトとメソッドについて説明します。

​

アクションでリフレッシュトークンを取り消す

api.refreshTokenオブジェクトを使用して、既存のリフレッシュトークンの有効期限日をリセットするか、リフレッシュトークンを取り消すことができます。

これらのオブジェクトの詳細については、以下をご確認ください。

​

イベントログの取り消しを監視する

ポストログインの api.refreshToken.revoke(reason) メソッドを使用すると、トランザクションに関したリスクに対処することができます。このメソッドでは以下を行うことができます。

api.refresh_token(reason)メソッドを使用したい場合は、event.refresh_tokenのプロパティを必ず定義してください。

取り消し操作を行うと、テナントログに以下のログイベントが追加されます。

​

アクションでリフレッシュトークンの有効期限日を変更する

リフレッシュトークンの取り消しを示すsrrtイベントコード

• Auth0で現在のリフレッシュトークンのトランザクションを無効にする
• 403 HTTPステータスコードを返して、現在のトランザクションを拒否する

リフレッシュトークンが以前に認証されたセッションにバインドされている場合、ログには、session_id属性に認証済みセッションへの参照が含まれます。

• api.refreshToken.setExpiresAt(Date) は、特定のリフレッシュトークンに新しい絶対ライフタイムを定義できるようにします。
• api.refreshToken.setIdleExpiresAt(Date) は、特定のリフレッシュトークンに新しい非アクティブタイムアウトを設定できるようにします。
• 特定ユーザーのグループメンバーシップまたはプロファイル
• リスク評価
• アクションの実行中に使用できる他の動的条件

リフレッシュトークンの有効期限日を変更するには、以下のポストログインメソッドを使用します。

​

制限事項

これらのメソッドを使用すると、以下を基に、リフレッシュトークンのライフタイムと非アクティブポリシーを動的にカスタマイズすることができます。

api.refreshToken.setExpiresAt(absolute)メソッドとapi.refreshToken.setIdleExpiresAt(idle)メソッドを使用すると、発行前にリフレッシュトークンの有効期限を定義したり、リフレッシュトークン交換フロー中にリフレッシュトークンに既存の有効期限を変更したりできます。

api.refreshToken.setExpiresAt(absolute)メソッドとapi.refreshToken.setIdleExpiresAt(idle)メソッドは、リフレッシュトークン有効期限のデフォルト設定を最大値として使用し、有効期限のないリフレッシュトークンを有効期限のあるリフレッシュトークンに変換します。

api.refreshToken.setIdleExpiresAt(idle)は、リフレッシュトークンの非アクティブタイムアウトを設定します。正常な交換でこのメソッドが呼び出されない場合には、アプリケーション設定にあるリフレッシュトークンのライフタイムを使って、非アクティブタイムアウトが上書きされます。

2023年9月21日以降に発行されたリフレッシュトークン（US-3リ－ジョンのテナントの場合は2024年2月22日）には、適切な値を持つセッションID（session_id）プロパティが含まれます。この日付よりも前に発行されたリフレッシュトークンには、null値を持つこのプロパティが含まれます。

ポストログインAPIメソッドのapi.refreshToken.revoke(reason)がリリースされる前に発行されたリフレッシュトークンには、event.refresh_token.device情報は含まれません。

​

ユースケース：リフレッシュトークンを取り消す

無期限のリフレッシュトークンや未交換のリフレッシュトークンには、event.refresh_token.last_exchanged_atプロパティは含まれません。

​

ImpossibleTravelによるトークンの取り消し

セキュリティ上の理由から、非アクティブタイムアウトと絶対タイムアウトを、リフレッシュトークンの有効期限日で定義されたアプリケーションのフレッシュトークンの設定を超えた値には設定できません。有効期限日を超えた日付を設定しようとすると、APIメソッドはリフレッシュトークンの有効期限まで更新し、テナントログに警告イベント（w）を記録します。

アクションを使用すると、リスク検出を構成して、リフレッシュトークンをapi.refreshToken.revoke(reason)メソッドとイベントオブジェクトを使って取り消すことができます。

Adaptive MFAのアセスメントオブジェクトを使用すると、ユーザーがImpossibleTravelを示す場所からログインしているか判定し、そのトランザクションに関連付けられた現在のリフレッシュトークンを取り消すことができます。

• ユーザーの組織
• ユーザーのAuth0接続
• 特定ユーザーのグループメンバーシップまたはプロファイル
• リスク評価

​

IPバインディングによるリフレッシュトークンの取り消し

exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication ?? {};
  const ImpossibleTravel = riskAssessment?.assessments.ImpossibleTravel;

  // If this is an impossible travel and this is a refresh token exchange
  if (ImpossibleTravel?.code === "impossible_travel_from_last_login") {
    if (event.refresh_token) {
      api.refreshToken.revoke("Refresh token revoked due to impossible travel");
    }
  }
};

この例では、アクションの開始時点でevent.authentication.ImpossibleTravel.codeがimpossible_travel_from_last_loginプロパティに等しいか検証されます。trueの場合、アクションはapi.refreshToken.revoke()を呼び出し、以下を行います。

ポストログインオブジェクトプロパティのevent.refresh_token.device.initial_ipとevent.request.ipを使って、その期間、リフレッシュトークンのトランザクションに同じIPアドレスが維持されるようにします。このシナリオでは、IPの変更はすべて危険だとみなされ、新しいリフレッシュトークンが要求されます。

• ユーザーの組織
• ユーザーのAuth0接続
• 「403 access_denied」のエラー応答を返す
• 「Refresh token revoked due to impossible travel（impossible travelによりトークンが取り消されました）」というエラーを発行する

exports.onExecutePostLogin = async (event, api) => {
  const refreshTokenInitialIp = event.refresh_token?.device?.initial_ip;
  const requestCurrentIp = event.request.ip;

  // if there is a refresh token and the IP changes
  if (
    refreshTokenInitialIp &&
    requestCurrentIp &&
    refreshTokenInitialIp != requestCurrentIp
  ) {
    api.refreshToken.revoke("Invalid IP change");
  }
};

​

ユースケース：リフレッシュトークンの有効期限日をカスタマイズする

この例では、アクションの開始時点で、event.refresh_token.device.initial_ipとevent.request.ipのプロパティを使ってIPアドレスの追跡が確認されます。アクションは、トランザクションのIPアドレスが変更されたかを判定します。trueの場合、アクションはapi.refreshToken.revoke()を呼び出し、以下を行います。

​

組織を基にリフレッシュトークンの絶対有効期限日をカスタマイズする

または、制限の少ないアクションでは、event.request.asnプロパティとevent.refresh_token.device.initial_asnプロパティを追跡し、IPの変更でなく、ASNの変更を監視することができます。

アクションを使用すると、リフレッシュトークンのライフタイムと非アクティブの日付をカスタマイズすることができます。具体的には、特定のトランザクションについて、リフレッシュトークンのアイドルTTLと絶対有効期限日を設定することができます。これには、ポストログインのapi.refreshToken.setExpiresAt(Date)メソッドとapi.refreshToken.setIdleExpiresAt(Date)メソッドを使用します。

以下のポストログインオブジェクトプロパティを使用すると、現在のトランザクションに関連付けられた組織について、リフレッシュトークンのライフタイムを定義することができます。

• トランザクションを拒否する
• リフレッシュトークンを取り消す

​

メンバーシップロールを基にリフレッシュトークンの非アクティブタイムアウトをカスタマイズする

exports.onExecutePostLogin = async (event, api) => {
  // Refresh token timeout (in miliseconds) metadata configured in the Organizations
  const organization_refresh_token_lifetime =
    event.organization?.metadata?.refresh_token_timeout;

  if (organization_refresh_token_lifetime) {
    // Refresh token already exists
    if (event.refresh_token) {
      const created = Date.parse(event.refresh_token.created_at);

      const new_expiration_time =
        created + Number(organization_refresh_token_lifetime);
      api.refreshToken.setExpiresAt(new_expiration_time);
    } else {
      // Refresh token doesn't exist yet (e.g., token is being issued)
      const current_time = new Date().getTime();

      const new_expiration_time =
        current_time + Number(organization_refresh_token_lifetime);
      api.refreshToken.setExpiresAt(new_expiration_time);
    }
  }
};

この例では、アクションの開始時点で、リフレッシュトークンのライフタイムがorganization_refresh_token_lifetimeよりも長いかが検証されます。リフレッシュトークンのライフタイムの方がが長い場合、アクションはリフレッシュトークンの有効期限が「リフレッシュトークンの作成日+organization_refresh_token_lifetime」と等しくなるように設定します。

ポストログインオブジェクトプロパティのevent.refresh_token.last_exchanged_atと event.refresh_token.idle_expires_atを使用すると、ユーザーのメンバーシップロールを基に、リフレッシュトークンの非アクティブタイムアウトを定義することができます。