メールアドレスオーセンティケーターの登録とチャレンジ

SMS または音声を認証要素として使用する独自の MFA フローを構築する方法について説明します。

Auth0 には、Universal Login を使用した組み込みの MFA の登録および認証フローがあります。ただし、独自のユーザーインターフェイスを作成する場合は、MFA API を使用して実装できます。

認証要素としてメールアドレスが有効になっている場合、検証済みのメールアドレスを持つすべてのユーザーは、そのメールアドレスを使用して MFA を完了できます。

利用可否は Auth0 のプランによって異なります

この機能を利用できるかどうかは、実装しているログイン方式と、Auth0 のプランまたは個別契約の内容によって異なります。詳細については、Pricing を参照してください。

​

前提条件

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

• Dashboard または Management API を使用して、要素として メールアドレスを設定 します。

​

メールアドレスを登録する

ユーザーがプライマリアイデンティティの確認済みメールアドレスに加えて別のメールアドレスを登録できるようにするには、次の手順を実行します。

​

MFAトークンを取得

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

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

​

オーセンティケーターを登録する

ユーザーのオーセンティケーターを登録するには、MFA Associate エンドポイントに POST リクエストを送信します。このエンドポイントに必要な Bearer トークンは、前の手順で取得した MFA トークンです。

次のパラメーターを使用します。

パラメーター	値
authentication_types	[oob]
oob_channels	[email]
email	[e-mail]。ユーザーのメールアドレス。

成功すると、次のようなレスポンスが返されます:

{
    "authenticator_type": "oob",
    "binding_method": "prompt",
    "oob_code" : "Fe26..nWE",
    "oob_channel": "email",
    "recovery_codes": [ "N3BGPZZWJ85JLCNPZBDW6QXC" ]
  }

User is already enrolled エラーが表示された場合、そのユーザーにはすでに MFA 要素が登録されています。ユーザーに別の要素を関連付ける前に、既存の要素でユーザーにチャレンジする必要があります。

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

​

メールアドレス登録の確認

ユーザーには、アプリケーションに入力する 6 桁の code が記載されたメールが届きます。

登録を完了するには、/oath/token エンドポイントに POST リクエストを送信します。前のレスポンスで返された oob_code と、メールメッセージに記載された値を持つ binding_code を含めてください。

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

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

この時点で、オーセンティケーターの関連付けは完了しており、使用できる状態です。また、ユーザーの認証トークンも取得できています。

オーセンティケーターが確認済みかどうかは、いつでも MFA Authenticators エンドポイントを呼び出して確認できます。オーセンティケーターが確認済みであれば、返される active の値は true になります。

必要に応じて、ユーザーが受信するメールをカスタマイズすることもできます。詳しくは、メールテンプレートをカスタマイズするを参照してください。

​

メールアドレスによるチャレンジ

​

MFAトークンを取得する

MFA を使用した Resource Owner Password Grant による認証で説明されている手順に従って、MFAトークンを取得します。

​

登録済みのオーセンティケーターを取得する

ユーザーにチャレンジを行うには、チャレンジする要素に対応する authenticator_id が必要です。MFA Authenticators エンドポイントを使用して、登録済みのオーセンティケーターをすべて一覧表示できます。

​

OTP でユーザーにチャレンジする

メールアドレスによるチャレンジを開始するには、対応する authenticator_id と mfa_token を指定して、MFA Challenge エンドポイントに POST リクエストを送信します。

​

受け取った code で認証を完了する

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

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

アプリケーションでは、ユーザーに code の入力を求め、次の oauth``/token エンドポイントの呼び出しで、その code を binding_code パラメーターとして送信する必要があります。

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

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

​

MFA をカスタマイズ

Resource Owner Password Grant、Embedded、またはリフレッシュトークンフローでのカスタマイズ可能な MFA は Early Access 提供です。この機能を使用すると、Okta の Master Subscription Agreement に記載されている該当する Free Trial 条項に同意したものとみなされます。Auth0 のリリースステージの詳細については、Product Release Stages を参照してください。Early Access への参加を希望する場合は、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"} //チャレンジでのみ使用可能
    ]
  }
}

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 Triggers: post-challenge - API Object を参照してください。

​

詳細情報

• Authentication API を使用して認証要素を管理する
• リカバリーコードを使用してチャレンジする
• OTP オーセンティケーターを登録してチャレンジする
• プッシュオーセンティケーターを登録してチャレンジする
• SMS および音声オーセンティケーターを登録してチャレンジする