Authentication API で認証要素を管理する

アプリケーションで Auth0 MFA API を使用して、MFA 認証器の登録を管理する方法について説明します。

始める前に

• アプリケーションで MFA グラントタイプを有効にします。詳しくは、グラントタイプを更新するをご覧ください。

Auth0 には、アプリケーションで使用している 多要素認証 (MFA) 用の認証器を管理するための API エンドポイント がいくつか用意されています。これらのエンドポイントを使用すると、ユーザーが自分の認証器を管理できる完全なユーザーインターフェースを構築できます。

​

MFA API のアクセストークンを取得する

登録を管理するために MFA API を呼び出すには、まず MFA API 用の アクセストークン を取得する必要があります。

認証フローの一部として MFA API を使用するには、Resource Owner Password Grant と MFA を使用して認証する に記載された手順に従ってください。認証要素を管理するユーザーインターフェースを構築する場合は、認証時だけでなく、いつでも MFA API で使用できるトークンを取得する必要があります。

MFA アクセストークン、または https://{yourDomain}/mfa/ の audience を持つアクセストークンは、認証を行うと同時に MFA の チャレンジリクエスト を開始します。MFA チャレンジが開始されるかどうかは、テナント での認証要素の有効化状況と、ユーザーの登録状況によって決まります。

• テナント で複数の認証要素の登録が許可されており、ユーザーがワンタイムパスワード (OTP) などの有効な認証要素 (email を除く) を登録している場合、ログイン時に MFA チャレンジがユーザーに送信されます。
• ユーザーがどの認証要素にも登録していない場合、または email 認証要素のみに登録している場合は、MFA トークンが発行され、ユーザーにチャレンジは送信されません。

https://{yourDomain}/mfa/* audience を持つアクセストークンのデフォルトの有効期限は 10 分です。この値は設定できません。

​

Universal Login

Universal Login を使用している場合は、https://{yourDomain}/mfa/ を audience に指定して、Authorize エンドポイントにリダイレクトします。

audience に https://{yourDomain}/mfa/ を指定すると、MFA が強制されます。.../mfa/ を audience に指定している場合、エンドユーザーが Remember this browser を有効にしても、その設定は反映されません。

Auth0 では、テナント管理者が allowRememberBrowser を false に設定する Action を作成する ことを推奨しています。これにより、エンドユーザーの画面には Remember this browser が表示されなくなります。

​

リソース所有者パスワードグラント

リソース所有者パスワードグラント (ROPG) を使用している場合、次の 3 つの方法があります。

• ログイン時に https://{yourDomain}/mfa/ の audience を要求し、後で リフレッシュトークン を使って更新します。
• 認証器の一覧表示と削除が必要な場合は、https://{yourDomain}/mfa/ の audience を指定して、/oauth/token でユーザーに 再度認証 してもらいます。認証要素を一覧表示または削除するには、ユーザーは先に MFA を完了する必要があります。
• 認証器の一覧表示だけが必要な場合は、ユーザー名/パスワードを使って /oauth/token でユーザーに 再度認証 してもらいます。エンドポイントからは mfa_required エラーと、認証器の一覧表示に使える mfa_token が返されます。ユーザーが自分の認証器を表示するには、パスワードを入力する必要があります。

​

スコープ

MFA audience 向けのトークンをリクエストする際は、次のスコープを指定できます。

スコープ	説明
enroll	新しい認証器を登録するため。
read:authenticators	既存の認証器を一覧表示するため。
remove:authenticators	認証器を削除するため。

​

認証器を一覧表示する

ユーザーの認証器の一覧を取得するには、MFA Authenticators エンドポイントを呼び出します。

レスポンスでは、認証器の種類に関する情報を受け取れます。

[
  {
    "authenticator_type": "recovery-code",
    "id": "recovery-code|dev_IsBj5j3H12VAdOIj",
    "active": true
  },
  {
    "authenticator_type": "otp",
    "id": "totp|dev_nELLU4PFUiTW6iWs",
    "active": true,
  },
  {
    "authenticator_type": "oob",
    "oob_channel": "sms",
    "id": "sms|dev_sEe99pcpN0xp0yOO",
    "name": "+1123XXXXX",
    "active": true
  }
]

エンドユーザーが自分の認証要素を管理するためのユーザーインターフェースを構築する場合は、active が false の認証器を無視してください。これらの認証器はユーザーによる確認が完了していないため、MFA のチャレンジには使用できません。

MFA API では、認証器の種類に応じて次の登録が一覧表示されます。

認証器	内容
プッシュ and OTP	プッシュ が有効になっている場合、Auth0 は OTP の登録も作成します。登録を一覧表示すると、両方が表示されます。
SMS and 音声	SMS と音声の両方が有効になっている場合、ユーザーが SMS または音声のいずれかで登録すると、Auth0 はその電話番号に対して 2 つの認証器を自動的に作成します。1 つは SMS 用、もう 1 つは音声用です。
Email	確認済みのすべてのメールアドレスが認証器として一覧表示されます。

​

認証器を登録する

各認証要素の認証器を登録する方法について詳しくは、以下のリンクを参照してください。

• SMS または音声
• ワンタイムパスワード (OTP)
• プッシュ
• Email

また、ユーザーの登録には Universal Login フロー をいつでも使用できます。

​

認証器を削除する

関連付けられている認証器を削除するには、MFA Authenticators エンドポイントに DELETE リクエストを送信し、AUTHENTICATOR_ID を対象の認証器 ID に置き換えます。この ID は、認証器を一覧表示した際に取得できます。

認証器の一覧表示に mfa_token を使用した場合、認証器を削除するには、audience が https://{yourDomain}/mfa/ のアクセストークンを取得するために MFA を完了する必要があります。

認証器が削除されると、204 レスポンスが返されます。

認証器を削除すると、認証器の種類に応じて次の動作が発生します。

認証器	動作
プッシュ and OTP	ユーザーが プッシュ 認証器を登録すると、Auth0 は OTP も登録します。どちらか一方を削除すると、もう一方も削除されます。
SMS and 音声	ユーザーが SMS または 音声 のいずれかを登録すると、Auth0 は SMS と 音声 の 2 つの認証器を作成します。どちらか一方を削除すると、もう一方も削除されます。
Email	検証済みのメールアドレスはすべて認証器として一覧表示されますが、削除することはできません。削除できるのは、明示的に登録された email 認証器のみです。

​

リカバリーコードを再生成する

リカバリーコードを削除して新しいコードを生成するには、Auth0のManagement API アクセストークンを取得し、Management APIのRecovery Code Regeneration endpointを使用します。

新しいリカバリーコードが発行されるので、エンドユーザーはそれを控えておく必要があります。たとえば、次のようになります。

{  
   "recovery_code": "FA45S1Z87MYARX9RG6EVMAPE"
}

​

詳細はこちら

• SMS および音声の認証器の登録とチャレンジ
• OTP 認証器の登録とチャレンジ
• プッシュ認証器の登録とチャレンジ
• Email 認証器の登録とチャレンジ
• リカバリーコードでのチャレンジ