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

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

始める前に

• アプリケーションで MFA grant type を有効にします。詳しくは、Grant Types の更新を参照してください。

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

​

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

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

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

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

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

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

​

Universal Login

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

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

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

​

リソースオーナー・パスワード・グラント

Resource Owner Password Grant (ROPG) を使用している場合は、次の 3 つの方法があります。

• ログイン時に https://{yourDomain}/mfa/ のオーディエンスを要求し、後で リフレッシュトークン を使用して更新します。
• 認証要素の一覧表示と削除が必要な場合は、https://{yourDomain}/mfa/ のオーディエンスを指定して /oauth/token で再度 認証 するようユーザーに求めます。ユーザーは、認証要素の一覧表示や削除を行う前に MFA を完了する必要があります。
• 認証要素の一覧表示だけが必要な場合は、username/password を使用して /oauth/token で再度 認証 するようユーザーに求めます。このエンドポイントは mfa_required エラーと、認証要素の一覧表示に使用できる mfa_token を返します。ユーザーが自分の認証要素を表示するには、パスワードを入力する必要があります。

​

スコープ

MFA のオーディエンスに対するトークンをリクエストする場合は、次のスコープを要求できます。

スコープ	説明
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 では、認証要素 の種類に応じて次の登録が一覧表示されます。

Authenticator	Actions
Push and OTP	push が有効な場合、Auth0 は OTP の登録も作成します。登録を一覧表示すると、両方が表示されます。
SMS and Voice	SMS と voice の両方が有効な場合、ユーザーが SMS または voice のいずれかで登録すると、Auth0 はその電話番号に対して 2 つの 認証要素 (1 つは SMS 用、もう 1 つは voice 用) を自動的に作成します。
Email	確認済みのすべてのメールアドレスが 認証要素 として一覧表示されます。

​

認証要素の登録

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

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

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

​

認証要素を削除する

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

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

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

認証要素を削除すると、認証要素の種類に応じて次の動作が行われます。

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

​

回復コードを再生成する

回復コードを削除して新しいコードを生成するには、Auth0 Management API アクセストークンを取得し、Management API の回復コード再生成エンドポイントを使用します。

新しい回復コードが返されるため、エンドユーザーはそれを記録しておく必要があります。たとえば、次のようになります。

{  
   "recovery_code": "FA45S1Z87MYARX9RG6EVMAPE"
}

​

詳細情報

• SMS および音声認証要素の登録とチャレンジ
• OTP 認証要素の登録とチャレンジ
• Push 認証要素の登録とチャレンジ
• メールアドレス認証要素の登録とチャレンジ
• 回復コードを使用したチャレンジ