> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Adaptive MFAをカスタマイズする

> Adaptive MFA（多要素認証）をカスタマイズする方法を説明します。

<Tooltip data-tooltip-id="react-containers-DefinitionTooltip-4" href="/docs/ja-jp/glossary?term=adaptive-multi-factor-authentication" tip="Adaptive Multifactor Authentication: ログイン試行が信頼性の低いログインであると判断された場合にのみ、ユーザーに対してトリガーされる多要素認証（MFA）。" cta="用語集の表示">Adaptive MFA</Tooltip>は、[Auth0 Actions](/docs/ja-jp/customize/actions)を使用してさまざまなシナリオでカスタマイズできます。

## Adaptive MFAをカスタマイズするタイミング

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Adaptive MFAのカスタマイズは、ユーザーがMFAに登録されていて、IDとしてメールアドレスを使用することが求められている場合のみ検討するようにしてください。
</Callout>

ユーザーが<Tooltip data-tooltip-id="react-containers-DefinitionTooltip-0" href="/docs/ja-jp/glossary?term=multifactor-authentication" tip="多要素認証（MFA）: ユーザー名とパスワードに加えて、SMS経由のコードなどの要素を使用するユーザー認証プロセス。" cta="用語集の表示">MFA</Tooltip>に登録されていない場合は、Adaptive MFAにデフォルトのポリシーを使用してください。ユーザーがMFAに登録されておらず、アクションが高リスクだと判断した場合、不正者を阻止する方法は限られてしまいます。

Adaptive MFAのカスタマイズを始める前に、ご自身で以下の点を検討してください。

* どの信頼レベルでMFAをトリガーしたいか？
* リスクをどのように測定したいか？
* Auth0で信頼度を測定したいか、それともカスタム測定をしたいか？
* MFAに登録していないユーザーをどのように処理するか？

## 信頼度を評価する

Adaptive MFAは、3つの評価分析に基づいて全体的な信頼スコアを計算します。評価ごとに独自の信頼スコアが設定されています。詳細については、「[Adaptive MFA](/docs/ja-jp/secure/multi-factor-authentication/adaptive-mfa)」をお読みください。

### 信頼スコア

信頼スコアと関連するアクションについては以下に説明します。

| 信頼度スコア    | 説明                                          | アクション                  |
| --------- | ------------------------------------------- | ---------------------- |
| `low`     | ログイントランザクションがユーザーによって前に表示されたパターンに一致しません。    | MFAが必要です。              |
| `medium`  | ログイントランザクションがユーザーによって前に表示されたパターンに多少一致します。   | MFAは必要でありません。          |
| `high`    | ログイントランザクションがユーザーによって前に表示されたパターンにぴったり一致します。 | MFAは必要でありません。          |
| `neutral` | 非該当。今後使用するために予約されています。                      | 非該当。今後使用するために予約されています。 |

### カスタム信頼スコア

さまざまなシナリオの全体的な信頼スコアを評価するために独自のメソッドを実装したい場合は、[riskAssessment](#riskassessment-context-object)オブジェクトにあるデータを使用することができます。

以下の例をお読みいただき、Adaptive MFAがさまざまなユースケースの信頼スコアをどのように計算するか理解してください。

#### 「リスクが高く、信頼度が低い」シナリオの例

下の表は、リスクが高いために信頼スコアが`low`（低）になるシナリオを示しています。

| ユーザーの状態  | 希望するログインフリクション | 希望する登録ポリシー                | 実装                              |
| -------- | -------------- | ------------------------- | ------------------------------- |
| MFAに登録済み | MFAを必要としない     | 非該当（ユーザーは登録済み）            | MFAをバイパスするようアクションを使用する          |
| MFAに未登録  | メール確認を必要とする    | 登録をスキップする（追加の鑑別工具を収集しない）  | デフォルトの動作（MFAに関連しないアクション）        |
| MFAに未登録  | メール確認を必要とする    | MFA登録を必要とする（追加の鑑別工具を収集する） | アクションを使ってMFA登録を強制する（テンプレート利用可能） |

#### 「リスクが低く、信頼度が高い」シナリオの例

下の表は、リスクが低いために信頼スコアが`high`（高）になるシナリオを示しています。

| ユーザーの状態  | 望ましいログイン時フリクション | 必要な登録ポリシー                        | 実装                            |
| -------- | --------------- | -------------------------------- | ----------------------------- |
| MFAに登録済み | フリクションなし        | 非該当（ユーザーは登録済み）                   | デフォルトの動作（MFA関連のアクションなし）       |
| MFAに未登録  | フリクションなし        | 登録をスキップ（追加のAuthenticatorを収集しない）  | デフォルトの動作（MFA関連のアクションなし）       |
| MFAに未登録  | フリクションなし        | MFAの登録が必要（追加のAuthenticatorを収集する） | アクションを使ってMFA登録を実施（テンプレート利用可能） |

### riskAssessmentオブジェクト

`riskAssessment`オブジェクトには、全体的な信頼スコア、バージョン情報、および各評価の詳細が含まれています。

| プロパティ         | 説明                              | タイプ    | 可能な値                                  |
| ------------- | ------------------------------- | ------ | ------------------------------------- |
| `confidence`  | Adaptive MFAによって計算された全体の信頼度スコア。 | 文字列    | `low`、`medium`、`high`、`neutral`       |
| `version`     | リスク評価APIのバージョン識別子。              | 文字列    | `1`                                   |
| `assessments` | 個々の評価詳細が含まれるオブジェクト。             | オブジェクト | 「[評価オブジェクト](#assessments-object)」を参照。 |

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.authentication && event.authentication.riskAssessment) {
    event.authentication.riskAssessment = {
      confidence: 'low' | 'medium' | 'high' | 'neutral',
      version: '1',
      assessments: {
        UntrustedIP: {
          confidence: 'low' | 'medium' | 'high' | 'neutral',
          code: 'not_found_on_deny_list' | 'found_on_deny_list',
          details: { // only if 'found_on_deny_list'
            ip: '192.168.1.1',
            matches: '192.168.0/64',
            source: 'firehol',
            category: 'abuse'
          }
        },
        NewDevice: {
          confidence: 'low' | 'medium' | 'high' | 'neutral',
          code: 'match' | 'partial_match' | 'no_match',
          details: {
            device: 'known' | 'unknown',
            useragent: 'known' | 'unknown',
          }
        },
        ImpossibleTravel: {
          confidence: 'low' | 'medium' | 'high' | 'neutral',
          code: 'missing_geoip', | 'anonymous_proxy' | 'unknown_location' | 'initial_login' | 'location_history_not_found' | 'invalid_travel' | 'minimal_travel_from_last_login' | 'impossible_travel_from_last_login' | 'substantial_travel_from_last_login' | 'travel_from_last_login'
        } 
      },
       PhoneNumber: {
          code: "requires_verification | ok",
          confidence: "low | medium | high | neutral",
          details: {
	        	lineType: "FIXED_LINE | MOBILE | FIXED_LINE_OR_MOBILE | TOLL_FREE | PREMIUM_RATE | SHARED_COST | VOIP | PERSONAL_NUMBER | PAGER | UAN | UNKNOWN"
	            isValid: true | false,
		        countryCode: 1,
		        number: "+12223334444"
        }
      }
    };
  }
}
```

### assessmentsオブジェクト

`assessments`オブジェクトには、3つの各リスク評価の詳細が含まれています。

1. [NewDevice評価](#newdevice-assessment)
2. [ImpossibleTravel評価](#impossibletravel-assessment)
3. [UntrustedIP評価](#untrustedip-assessment)
4. [PhoneNumber評価](#phonenumber-assessment)

各評価には[信頼スコア](#confidence-scores)、評価結果を説明するコード、およびその他のコンテキスト情報が含まれています。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  アセスメントバックエンドシステムで障害が発生するという極めて稀な状況では、Auth0がデフォルトで安全な動作をとるため、アセスメントコードが`assessment_not_available`、関連付けられた信頼度が`low`になります。Actionsを使用すると、この信頼度スコアをオーバライドできます。詳細については、「[Auth0がアセッサーを実行できない場合の安全な処理](#safely-handle-when-auth0-fails-execute-assessors)」をお読みください。
</Callout>

#### NewDevice評価

`NewDevice`評価では、ユーザーが既知のデバイスからログインしているかどうかを判定し、以下のプロパティが含まれます。

| プロパティ        | 説明                       | タイプ    | 使用可能な値                                                                                                             |
| ------------ | ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `confidence` | Adaptive MFAが計算した信頼度スコア。 | 文字列    | `low`、`medium`、`high`、`neutral`                                                                                    |
| `code`       | アセスメントの評価結果。             | 文字列    | `match`、`partial_match`、`no_match`、`initial_login`、`unknown_device`、`no_device_history`、`assessment_not_available` |
| `details`    | 追加のコンテキスト情報。             | オブジェクト | 以下の表を参照してください。                                                                                                     |

##### NewDevice評価コードのプロパティ

`NewDevice`評価`code`プロパティは以下のいずれかの値に等しくなります。

| 値                          | 説明                                |
| -------------------------- | --------------------------------- |
| `match`                    | `details`オブジェクトのプロパティ値が同等です。      |
| `partial_match`            | `details`オブジェクトのプロパティ値が類似しています。   |
| `no_match`                 | `details`オブジェクトのプロパティ値が異なります。     |
| `initial_login`            | ユーザーが初めてデバイスにログインしました。            |
| `unknown_device`           | Auth0はデバイスのメタデータを見つけることができませんでした。 |
| `no_device_history`        | デバイスに関連するログイン履歴がありません。            |
| `assessment_not_available` | Auth0はデバイスの評価を実行できませんでした。         |

##### NewDevice評価の詳細オブジェクト

`code`プロパティの値が`match`、`partial_match`、または`no_match`に等しい場合、`NewDevice`評価には以下のプロパティを持つ`details`オブジェクトが含まれます。

| プロパティ       | 説明               | タイプ | 可能な値              |
| ----------- | ---------------- | --- | ----------------- |
| `device`    | ユーザーのデバイス。       | 文字列 | `known`、`unknown` |
| `useragent` | ユーザーのユーザーエージェント。 | 文字列 | `known`、`unknown` |

#### ImpossibleTravel評価

`ImpossibleTravel`評価では、ユーザーが不可能な移動を示す場所からログインしているかどうかを判定し、以下のプロパティが含まれます。

| プロパティ        | 説明                       | タイプ | 使用可能な値                                                                                                                                                                                                                                                                           |
| ------------ | ------------------------ | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `confidence` | Adaptive MFAが計算した信頼度スコア。 | 文字列 | `low`、`medium`、`high`、`neutral`                                                                                                                                                                                                                                                  |
| `code`       | アセスメントの評価結果。             | 文字列 | `minimal_travel_from_last_login`、`travel_from_last_login`、`substantial_travel_from_last_login`、`impossible_travel_from_last_login`、`invalid_travel`、`missing_geoip`、`anonymous_proxy`、`unknown_location`、`initial_login`、`location_history_not_found`、`assessment_not_available` |

#### UntrustedIP評価

`UntrustedIP`評価では、ユーザーのIPアドレスがレピュテーションが低いIPアドレス（「拒否リスト」）のAuth0のリポジトリに存在するかどうかを判定し、以下のプロパティが含まれます。

| プロパティ        | 説明                       | タイプ    | 使用可能な値                                                                                        |
| ------------ | ------------------------ | ------ | --------------------------------------------------------------------------------------------- |
| `confidence` | Adaptive MFAが計算した信頼度スコア。 | 文字列    | `low`、`medium`、`high`、`neutral`                                                               |
| `code`       | アセスメントの評価結果。             | 文字列    | `not_found_on_deny_list`、`found_on_deny_list`、`invalid_ip_address`、`assessment_not_available` |
| `details`    | 追加のコンテキスト情報。             | オブジェクト | 以下の表を参照してください。                                                                                |

##### UntrustedIP評価の詳細オブジェクト

`UntrustedIP`評価の`code`プロパティの値が`found_on_deny_list`に等しい場合、`details`オブジェクトは存在し、以下のプロパティが含まれます。

| プロパティ      | 説明                       | タイプ    | 取り得る値                                                       |
| ---------- | ------------------------ | ------ | ----------------------------------------------------------- |
| `ip`       | デバイスのIPアドレス。             | string | 任意の有効なIPv4またはIPv6アドレス。                                      |
| `matches`  | IPアドレスが属するサブネットマスク。      | string | 任意の有効なIPv4またはIPv6サブネットマスク。                                  |
| `source`   | 拒否リストの脅威インテリジェンスソースの名前。  | string | 任意の有効なテキスト。                                                 |
| `category` | IPアドレスが信頼されない理由を示したカテゴリ。 | string | `abuse`、`anonymizer`、`datacenter`、`reputation`、`unroutable` |

##### UntrustedIP評価の詳細オブジェクトカテゴリのプロパティ

`UntrustedIP`評価の`details`オブジェクト`category`のプロパティでは、Adaptive MFAが特定のIPアドレスを信用できないものとみなす一般的な理由を説明し、以下のいずれかの値に等しくなります。

| 値            | 説明                                                            |
| ------------ | ------------------------------------------------------------- |
| `abuse`      | IPアドレスの動作が不正か、ボットネットの一部だと判明しました。                              |
| `anonymizer` | VPNプロバイダー、公開プロキシ、Tor Exitノードなど、匿名サービスのIPアドレスです。               |
| `datacenter` | クラウドホスティングサービスやコロケーションデータセンターのIPアドレスです。                       |
| `reputation` | IPアドレスのアクティビティを基にした評判スコアが低いこをと示しています。                         |
| `unroutable` | IPアドレスが、公認のインターネットレジストリーによって割り当てや委任された範囲内にないか、一般利用に許可されていません。 |

#### PhoneNumber評価

`PhoneNumber`評価では、送られてくるトランザクションに指定された電話番号のリスクを判定し、以下のプロパティが含まれます。

| プロパティ        | 説明                           | タイプ    | 可能な値                                                                                |
| ------------ | ---------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `code`       | 評価結果の説明。                     | 文字列    | `ok`、`requires_verification`、`phone_number_not_provided`、`assessment_not_available` |
| `confidence` | Adaptive MFAによって計算された信頼度スコア。 | 文字列    | `low`、`medium`、`high`、`neutral`                                                     |
| `details`    | 追加のコンテキスト情報。                 | オブジェクト | 下の表を参照。                                                                             |

##### PhoneNumber評価の詳細オブジェクト

`PhoneNumber`評価の`details`オブジェクトには、以下のプロパティが含まれます。

| プロパティ         | 説明          | タイプ  | 使用可能な値                                                                                                                                  |
| ------------- | ----------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `lineType`    | 電話回線のタイプ    | 文字列  | `FIXED_LINE`、`MOBILE`、`FIXED_LINE_OR_MOBILE`、`TOLL_FREE`、 `PREMIUM_RATE`、`SHARED_COST`、`VOIP`、`PERSONAL_NUMBER`、`PAGER`、`UAN`、`UNKNOWN` |
| `isValid`     | 番号の有効性を返します | ブール値 | `true`、`false`                                                                                                                          |
| `countryCode` | 電話の発信元の国コード | 整数   | `0-999`                                                                                                                                 |
| `number`      | 電話番号        | 文字列  | 有効な番号（`countryCode`を含む）                                                                                                                 |

## アクションの結果

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  MFAをトリガーするアクションは、デフォルトのAdaptive MFAの動作に優先します。
</Callout>

いずれかのアクションが信頼スコアに基づいてMFAをトリガーする場合、デフォルトのAdaptive MFAポリシーは、信頼スコアが`low`（低）のときにMFAをトリガーします。

下の表は、アクションとデフォルトのAdaptive MFAポリシーアクションの組み合わせに基づいて考えられる結果を示しています。

| アクションの結果 | Adaptive MFAアクション | 結果       |
| -------- | ----------------- | -------- |
| 未承認      | MFAをトリガー          | 未承認      |
| 未承認      | MFA不要             | 未承認      |
| MFAをトリガー | MFAをトリガー          | MFAをトリガー |
| MFAをトリガー | MFA不要             | MFAをトリガー |
| MFA不要    | MFAをトリガー          | MFAをトリガー |
| MFA不要    | MFA不要             | MFA不要    |

## Actionテンプレート

Auth0には、Adaptive MFAに基づいて、[Adaptive MFA](#adaptive-mfa)と[Require MFA Enrollment（MFA登録を必須にする）](#require-mfa-enrollment)という2つのカスタマイズ可能なテンプレートが用意されています。

### Adaptive MFAテンプレート

このテンプレートは例として、個々のリスク評価を使ってカスタムビジネスフローを構築する方法の始点を提供します。

```javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  if (event.authentication && 
      event.authentication.riskAssessment && 
      event.authentication.riskAssessment.assessments.NewDevice) {

  // Example condition: prompt MFA only based on the NewDevice 
    // confidence level, this will prompt for MFA when a user is logging in 
    // from an unknown device.
    let shouldPromptMfa;

    switch (event.authentication.riskAssessment.assessments.NewDevice.confidence) {
      case 'low':
      case 'medium':
        shouldPromptMfa = true;
        break;
      case 'high':
        shouldPromptMfa = false;
        break;
      case 'neutral':
        // When this assessor has no useful information about the confidence, 
        // do not prompt MFA.
        shouldPromptMfa = false;
        break;
    }

      // It only makes sense to prompt for MFA when the user has at least one 
      // enrolled MFA factor.
    const canPromptMfa = event.user.multifactor && event.user.multifactor.length > 0;

    if (shouldPromptMfa && canPromptMfa) {
      api.multifactor.enable('any', { allowRememberBrowser: true });
    }
  }
};
```

### Require MFA Enrollmentテンプレート

このテンプレートは、標準またはAdaptive MFAポリシーを使うときに、MFA登録をどのように強制できるかを示しています。ここでは、`event.user.multifactor`を使ってユーザーがMFAに登録しているかどうかを確認し、登録していない場合は、登録するよう促します。

```javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  if (!event.user.multifactor || event.user.multifactor.length == 0) {
    api.multifactor.enable('any', { allowRememberBrowser: true });
  }
};
```

## Actionのユースケース

ユースケースに基づいてカスタムアクションを構築する方法に関する提案をご紹介します。

### 全体的な信頼スコアがXの場合にアクションを実行する

`riskAssessment.confidence`プロパティを評価してから、`high`、`medium`、または`low`といった定数と比較します。

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const riskIsMedium = riskAssessment && riskAssessment.confidence === 'medium';

  if (riskIsMedium) {
    // ....
  }
}
```

### 信頼スコアがX以上またはX以下である場合にアクションを実行する

信頼スコアは範囲でなく不連続の値です。そのため、比較演算子（`<`や`>`など）を使って複数の値を1つの状況で評価することはできません。

複数の状況を使って、処理したいすべての信頼スコアを論理的に組み合わせます。たとえば、信頼スコアが`low`より大きいかどうかを知りたい場合は、`medium`または`high`に等しいかどうかを確認します。

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const riskIsMediumOrHigh = riskAssessment && 
                                  (riskAssessment.confidence === 'high' || 
                                   riskAssessment.confidence === 'medium');

  if (riskIsMediumOrHigh) {
    // ...
  }
}
```

### 全体的な信頼スコアがXの場合に追加の詳細を取得する

`riskAssessment`オブジェクトはテナントログに保存されています。ログエントリーを表示し、リスク評価スコアと決定的な要因（理由）を確認します。

`riskAssessment`オブジェクトを表示し、結果を別の場所で報告します。たとえば、メールを送信したり、レコードを外部データベースに保存したりできます。

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const riskIsLow = riskAssessment && riskAssessment.confidence === 'low';

  if (riskIsLow) {
    // log(externalDatabase, riskAssessment);
  }
}
```

### 特定の評価に特定の結果が含まれている場合にアクションを実行する

[assessments](#assessments-object)オブジェクト（`code`プロパティなど）を使って各評価の詳細にアクセスします。

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const { ImpossibleTravel } = riskAssessment && riskAssessment.assessments;

  if (ImpossibleTravel.code === 'impossible_travel_from_last_login') {
    // ...
  }
}
```

### カスタムの全体的な信頼スコアの評価を集約する

[assessments](#assessments-object)オブジェクトを使って各評価の詳細にアクセスしてから、`confidence`プロパティ、`code`プロパティ、またはその両方を使用します。

カスタム信頼スコアの詳細については、「[カスタム信頼スコア](#custom-confidence-scoring)」をお読みください。

### 特定の評価に特定の結果が含まれている場合は、現在のトランザクションをブロックし、エラーとメッセージを返します。

[assessments](#assessments-object)オブジェクト（`code`プロパティなど）を使って各評価の詳細にアクセスします。

`UnauthorizedError`オブジェクトを[エラーパラメーター](/docs/ja-jp/troubleshoot/error-handling-best-practices)に使用してコールバック関数を返すことで、ログイントランザクションが完了するのをブロックします。`UnauthorizedError`オブジェクトは必ず`error`を`unauthorized`に設定しますが、`error_message`をカスタマイズすることはできます。

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const { ImpossibleTravel } = riskAssessment && riskAssessment.assessments;

  if (ImpossibleTravel.code === 'impossible_travel_from_last_login') {
    return api.access.deny('Login blocked due to impossible travel detected.')
  }
}
```

これによってユーザーは、`error`および`error_message`パラメーターを含んだアプリケーションのコールバックURLにリダイレクトされます。

### Auth0が評価を実行できない場合に安全に処理する

リスク評価の実行時に何かしらのエラーが発生した場合、Auth0は自動的に`low`信頼レベルを割り当てます。

このシナリオを軽減するには、[assessments](#assessments-object)オブジェクトを使って個々の評価の`code`プロパティを点検し、値が`assessment_not_available`に設定されているかどうかを確認します。

## もっと詳しく

* [Adaptive MFAを有効にする](/docs/ja-jp/secure/multi-factor-authentication/adaptive-mfa/enable-adaptive-mfa)
* [Adaptive MFAログイベント](/docs/ja-jp/secure/multi-factor-authentication/adaptive-mfa/adaptive-mfa-log-events)
* [アクションのトリガー：ログイン後 - APIオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)
* [アクションのトリガー: ポストログイン - イベントオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)