Actionsでリフレッシュトークンを管理する

Actions を使用して Auth0 リフレッシュトークンを管理し、リフレッシュトークンのクレームの読み取りや変更、カスタム有効期限の設定、トークンの取り消しを行います。

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

これを実現するために、post-login Actions には 2 つの重要なオブジェクトが用意されています。

• event.refresh_token: 既存の refresh_tokens に関する情報を提供します。これには id、created_at、expires_at、idle_expires_at、clients_id、ASN、IP、User_agent などの device 情報に加え、ブラウザベースのフローでは session_id が含まれます。このオブジェクトは、リフレッシュトークン交換 フローで設定されます。
• api.refreshToken: セッションの取り消しや有効期限の変更を通じて、既存のリフレッシュトークンを管理できます。

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

その後、api.refreshToken オブジェクトを使用して、リフレッシュトークンの有効期限を設定することも、リフレッシュトークンを取り消すこともできます。

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

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

​

Actions を使用してリフレッシュトークンを無効化する

post-login の api.refreshToken.revoke(reason) メソッドを使用すると、トランザクションに関連するリスクに対応できます。リフレッシュトークンを無効化すると、そのリフレッシュトークンは無効になり、現在のトランザクションを拒否するために HTTP ステータスコード 403 が返され、テナントログ (srrt) にリフレッシュトークンの無効化イベントが記録されます。

api.refreshToken.revoke(reason) メソッドを使用する場合は、event.refresh_token オブジェクトが存在することを確認してください。

​

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

revoke 操作を実行すると、テナントのログに次のログイベントが追加されます。

リフレッシュ トークンが取り消されたことを示す srrt イベントコード。

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

​

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

次の post-login メソッドを使用して、リフレッシュトークンの有効期限を変更できます。

• api.refreshToken.setExpiresAt(absolute) を使うと、指定したリフレッシュトークンの新しい絶対有効期限を設定できます。
• api.refreshToken.setIdleExpiresAt(idle) を使うと、指定したリフレッシュトークンの非アクティブ時のタイムアウトによる新しい有効期限を設定できます。

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

• ユーザーの organization
• ユーザーの Auth0 connection
• 特定ユーザーのグループ所属やプロフィール
• リスク評価
• Action の実行中に利用可能なその他の動的な条件

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

api.refreshToken.setExpiresAt(absolute) メソッドと api.refreshToken.setIdleExpiresAt(idle) メソッドは、既定の Refresh Token expirations 設定を最大値として使用し、無期限のリフレッシュトークンを有効期限付きのリフレッシュトークンに変換します。

api.refreshToken.setIdleExpiresAt(idle) メソッドは、リフレッシュトークンの非アクティブ時タイムアウトを設定します。このメソッドが成功したすべての exchange で毎回呼び出されない場合、非アクティブ時タイムアウトはリフレッシュトークンの有効期間に関するアプリケーション設定で上書きされます。

​

制限事項

• 2023-09-21 以降に発行されたリフレッシュトークン (US-3 リージョンのテナントでは 2024-02-22 以降) には、適切な値を持つセッション ID (session_id) プロパティが含まれます。これより前に発行されたリフレッシュトークンでは、このプロパティの値は null です。

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

• 有効期限のないリフレッシュトークン、または一度も交換されていないリフレッシュトークンには、event.refresh_token.last_exchanged_at プロパティは含まれません。

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

• api.refreshToken.setExpiresAt() と api.refreshToken.setIdleExpiresAt() は、どちらも現在の値からそれぞれの有効期間を短くすることしかできません。有効期間を延長したり増やしたりすることはできません。

​

ユースケース: リフレッシュトークンを無効化する

Actions を使用すると、リスク検出を設定し、api.refreshToken.revoke(reason) メソッドと event オブジェクトを使ってリフレッシュトークンを無効化できます。

​

ImpossibleTravel による refresh tokens の取り消し

Adaptive MFA の assessments オブジェクトを使用すると、ユーザーが ImpossibleTravel を示す場所からログインしているかどうかを判断し、そのトランザクションに関連付けられている現在の refresh token を取り消すことができます。

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

  // 不可能な移動が検出され、かつリフレッシュトークンの交換である場合
  if (ImpossibleTravel?.code === "impossible_travel_from_last_login") {
    if (event.refresh_token) {
      api.refreshToken.revoke("Refresh token revoked due to impossible travel");
    }
  }
};

この例では、Action の冒頭で event.authentication.ImpossibleTravel.code が impossible_travel_from_last_login property と一致するかどうかを確認します。true の場合、Action は api.refreshToken.revoke() を呼び出して、次の処理を行います。

• トランザクションを拒否する
• リフレッシュトークンを無効にする
• 403 の access_denied エラーレスポンスを返す
• 「不可能な移動のため、リフレッシュトークンは無効化されました」というエラーを返す

​

IP バインディングによりリフレッシュトークンを失効させる

post-login オブジェクトのプロパティ event.refresh_token.device.initial_ip と event.request.ip を使用して、リフレッシュトークンのトランザクションが有効期間中ずっと同じ IP アドレスから行われるようにする場合。このシナリオでは、IP アドレスの変更はすべてリスクと見なされ、新しいリフレッシュトークンが必要になります。

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

  // リフレッシュトークンが存在し、IPアドレスが変更された場合
  if (
    refreshTokenInitialIp &&
    requestCurrentIp &&
    refreshTokenInitialIp != requestCurrentIp
  ) {
    api.refreshToken.revoke("Invalid IP change");
  }
};

この例では、Action の冒頭で event.refresh_token.device.initial_ip プロパティと event.request.ip プロパティを使用して IP アドレスを追跡するチェックが行われます。Action は、トランザクションの IP アドレスが変更されたかどうかを判定します。true の場合、Action は api.refreshToken.revoke() を呼び出して、次の処理を行います。

• トランザクションを拒否する
• リフレッシュトークンを取り消す
• 403 レスポンスの access_denied エラーを返す
• 「Invalid IP change」というエラーを発生させる

また、より制限の緩い Action として、IP の変更ではなく ASN の変更を監視するために、event.request.asn プロパティと event.refresh_token.device.initial_asn プロパティを追跡することもできます。

​

ユースケース: Refresh Token の有効期限をカスタマイズする

Actions を使用すると、Refresh Token の有効期間や非アクティブ時の有効期限をカスタマイズできます。具体的には、post-login の api.refreshToken.setExpiresAt(absolute) メソッドと api.refreshToken.setIdleExpiresAt(idle) メソッドを使用して、特定のトランザクションにおける Refresh Token のアイドル時の有効期限と絶対有効期限を設定できます。

​

Organization に基づいて Refresh Token の絶対有効期限をカスタマイズする

post login action を使用すると、Organization ごとに Refresh Token の有効期間を設定できます。以下の例では、Organization の refresh_token_timeout メタデータを使用して、Refresh Token の有効期限を設定します。

exports.onExecutePostLogin = async (event, api) => {
  // Organizationsで設定されたリフレッシュトークンのタイムアウト（ミリ秒）メタデータ
  const organization_refresh_token_lifetime =
    event.organization?.metadata?.refresh_token_timeout;

  if (organization_refresh_token_lifetime) {
    // リフレッシュトークンが既に存在する
    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 {
      // リフレッシュトークンがまだ存在しない（例：トークンが発行中の場合）
      const current_time = new Date().getTime();

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

この例では、Organization に特定の絶対タイムアウトが定義されている場合、Action はリフレッシュトークンの絶対タイムアウトを次のように設定します。

• 新たに発行されたトークン: current_time に organization_refresh_token_lifetime を加えた値
• 既存のトークン: event.refresh_token.created_at に organization_refresh_token_lifetime を加えた値

​

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

アプリケーション と ユーザーメタデータ を使用すると、ログイン後のアクションでリフレッシュトークンのアイドルタイムアウトを定義できます。以下の例では、ユーザーメタデータ内のロールを使ってユーザーのメンバーシップロールを定義し、アプリケーションメタデータを使って想定するリフレッシュトークンのアイドルタイムアウトを定義しています。

exports.onExecutePostLogin = async (event, api) => {
  // 管理者のRefresh Tokenアイドルタイムアウトは、アプリケーションメタデータで短く設定されています
  const max_idle_lifetime =
    event.client.metadata?.admin_refresh_token_idle_timeout;

  // ユーザーのアプリメタデータのroles属性を確認して、管理者ユーザーかどうかを判定します。
  const isAdmin = event.user?.app_metadata?.roles?.find(
    (role) => role === "admin",
  );

  // アプリケーションに特定のアイドルタイムアウトが定義されている場合、タイムアウトを設定します
  if (max_idle_lifetime && isAdmin) {
    const current_time = new Date().getTime();

    api.refreshToken.setIdleExpiresAt(current_time + Number(max_idle_lifetime));
  }
};

この例では、Application に特定のアイドルタイムアウトが定義されており、かつユーザーが Admin の場合、Action はリフレッシュトークンの非アクティブ時タイムアウトを、current_time に refresh_token_idle_timeout を加えた値に設定します。なお、リフレッシュトークン交換時には、新たに発行されるトークンと既存のトークンの両方のタイムアウトを変更しています。