SMS and 音声認証器の登録とチャレンジ

認証要素としてSMSや音声通話を使用した独自のMFAフローの構築方法を説明します。

Auth0 には、Universal Login を使用した、組み込みの MFA の登録および認証フローが用意されています。ですが、独自のユーザーインターフェースを作成したい場合は、MFA API を使って実現することもできます。

​

前提条件

MFA API を使用する前に、アプリケーションで MFA グラントタイプを有効にする必要があります。Auth0 Dashboard > アプリケーション > 詳細設定 > グラントタイプ に移動し、MFA を選択します。

• Auth0 Dashboard または Management API を使用して、電話を認証要素として設定する。

​

SMS または音声で登録する

​

MFAトークンを取得する

登録を開始するタイミングに応じて、MFA API の利用に必要な アクセストークン は、いくつかの方法で取得できます。

• 認証時に登録する場合は、Authenticate With Resource Owner Password Grant and MFA を参照してください。
• ユーザーが任意のタイミングで認証要素を登録できるようにする場合は、Manage MFA Factor Enrollments を参照してください。

​

認証器を登録する

ユーザーの認証器を登録するには、MFA Associate endpoint に POST リクエストを送信します。この endpoint で必要なベアラートークンは、前の手順で取得した MFA トークンです。

SMS or 音声 で登録するには、SMS または 音声 のいずれかでチャレンジできる電話番号を登録します。endpoint を呼び出すには、以下のパラメーターを指定します。oob_channels パラメーターは、ユーザーに code を送信する方法 (SMS または 音声) を示します。

パラメーター	値
authentication_types	[oob]
oob_channels	[sms] または [voice]
phone_number	+11...9、電話番号 (E.164形式)

成功すると、次のようなレスポンスを受け取ります。

{
  "authenticator_type": "oob",
  "binding_method": "prompt",
  "recovery_codes": [ "N3BGPZZWJ85JLCNPZBDW6QXC" ],
  "oob_channel": "sms",
  "oob_code": "ata6daXAiOi..."
}
`

User is already enrolled エラーが表示される場合、そのユーザーにはすでに MFA の認証要素が登録されています。ユーザーに別の認証要素を関連付ける前に、既存の認証要素でユーザー本人の確認を行う必要があります。

これがユーザーにとって認証器を関連付ける初めてのケースであれば、レスポンスに recovery_codes が含まれていることがわかります。リカバリーコードは、ユーザーがアカウント、または第 2 認証要素の認証に使用しているデバイスにアクセスできなくなった場合に、アカウントへアクセスするために使用されます。これらのコードは 1 回限り有効で、必要に応じて新しいものが生成されます。

​

SMS または音声による登録を確認する

ユーザーには、アプリケーションに入力する必要がある 6 桁のコードを含むメッセージが届きます。

登録を完了するには、OAuth トークンエンドポイント に POST リクエストを送信します。前のレスポンスで返された oob_code と、メッセージで受け取った値を含む binding_code を指定する必要があります。

呼び出しが成功すると、アクセストークン を含む次の形式のレスポンスが返されます:

{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}

​

SMS または音声による認証チャレンジ

​

MFAトークンを取得する

MFA を使用して Resource Owner Password グラントで認証する の手順に従って、MFAトークンを取得します。

​

登録済みの認証器を取得する

ユーザーにチャレンジを送信するには、チャレンジする認証要素の authenticator_id が必要です。MFA Authenticators エンドポイント を使用して、登録済みの認証器をすべて一覧表示できます。

次の形式で認証器の一覧が返されます。

[
    {
        "id": "recovery-code|dev_O4KYL4FtcLAVRsCl",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "sms|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "sms",
        "name": "XXXXXXXX8730"
    },
        {
        "id": "voice|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "voice",
        "name": "XXXXXXXX8730"
    }
]

​

OTP を使ってユーザーにチャレンジする

チャレンジを実行するには、対応する authenticator_id と mfa_token を使用して、MFA Challenge エンドポイントに POST します。

​

受信したコードで認証を完了する

成功すると、次のレスポンスが返されます。

{
  "challenge_type": "oob",
  "oob_code": "asdae35fdt5...",
  "binding_method": "prompt"
}

アプリケーションでは、メッセージで送信された6桁のコードをユーザーに入力してもらい、その値を binding_code パラメータに設定する必要があります。前の呼び出しで返された binding_code と oob_code を指定して OAuth0 トークンエンドポイントを使用すると、コードを検証し、認証トークンを取得できます。

呼び出しが成功すると、アクセストークン を含む以下の形式のレスポンスが返されます：

{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}

注: SMS送信と「無効なコード」エラーの返却は、レート制限の対象です。SMSコードは10回送信でき、1時間ごとに1回分回復します。一方、「無効なコード」エラーは10回まで返され、6分ごとに1回分回復します。

​

MFA をカスタマイズする

Resource Owner Password Grant、埋め込み、またはリフレッシュトークン フローでのカスタマイズ可能な MFA は、早期アクセスです。この機能を使用すると、Okta の Master Subscription Agreement に記載された該当する Free Trial 条項に同意したものとみなされます。Auth0 のリリース段階の詳細については、Product Release Stages をご覧ください。早期アクセスへの参加をご希望の場合は、Auth0 Support までお問い合わせください。

カスタマイズ可能な MFA を使用すると、ユーザーはアプリケーションでサポートされている認証要素の中から任意のものを登録し、それによるチャレンジを受けることができます。

oauth/token エンドポイントでの認証中、レスポンスでは mfa_required エラーが返されます。このエラーには、MFA API で使用する mfa_token と、認証器の一覧を含む mfa_requirements パラメーターが含まれます。

{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //challengeでのみ使用可能
    ]
  }
}

mfa_token を使って mfa/authenticator エンドポイントを呼び出し、ユーザーが登録済みのすべての認証要素の一覧を取得したうえで、アプリケーションがサポートしている種類と一致するものを特定します。さらに、チャレンジを発行するには、対応する authenticator_type も取得する必要があります:

[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]

request/mfa/challenge エンドポイントを呼び出して、MFAチャレンジを必須にします。

Auth0 Actions を使用すると、MFAフローをさらに柔軟にカスタマイズできます。詳しくは、Actions トリガー: post-challenge - API Object をご覧ください。

​

詳しくはこちら

• Authentication API を使用して認証要素を管理する
• MFA の SMS 通知と音声通知を設定する
• リカバリーコードによるチャレンジ
• Email 認証器の登録とチャレンジ
• OTP 認証器の登録とチャレンジ
• Push 認証器の登録とチャレンジ