プッシュ認証器の登録とチャレンジ

プッシュを認証要素として使用して、独自のMFAフローを構築する方法を説明します。

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

MFA API を使用すると、Guardian アプリケーションまたは SDK でプッシュ通知を利用して、ユーザーの登録やチャレンジを行えます。

​

前提条件

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

• Auth0 Dashboard または Management API を使用して、認証要素として プッシュを設定 します。

​

プッシュ通知を登録

​

MFAトークンを取得する

登録を開始するタイミングに応じて、MFA API で使用する access token を、さまざまな方法で取得できます。

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

​

認証器を登録する

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

プッシュで登録するには、authenticator_types パラメーターを [oob] に、oob_channels パラメーターを [auth0] に設定します。

成功した場合、次のようなレスポンスが返されます。

{
    "authenticator_type": "oob",
    "barcode_uri": "otpauth://totp/tenant:user?enrollment_tx_id=qfjn2eiNYSjU3xID7dBYeCBSrdREWJPY&base_url=tenan",
    "recovery_codes": [
        "ALKE6EJZ4853BJYLM2DM2WU7"
    ],
    "oob_channel": "auth0",
    "oob_code": "Fe26.2...SYAg"
}

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

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

​

プッシュ登録を確認する

登録を確認するには、エンドユーザーは 5 分以内に、Guardian アプリで barcode_uri の QR コードをスキャンする必要があります。

これが完了すると、Guardian アプリはユーザーの登録が正常に完了したことを Auth0 に通知します。実際に完了したかどうかを確認するには、MFA Associate エンドポイントの呼び出しで返された oob_code を使って、Auth0 の トークンエンドポイント をポーリングします。

ユーザーがコードをスキャンしていない場合は、authorization_pending レスポンスが返されます。これは、数秒後に oauth_token を再度呼び出す必要があることを示しています。

{
    "error": "authorization_pending",
    "error_description": "Authorization pending: please repeat the request in a few seconds."
}

呼び出しが成功すると、次の形式で access token を含むレスポンスが返されます。

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

この時点で、認証器の関連付けは完了しており、使用可能な状態です。また、ユーザーの認証トークンも取得できています。

MFA Authenticators エンドポイントを呼び出すことで、認証器が確認済みかどうかをいつでも確認できます。認証器が確認済みであれば、active に返される値は true です。

​

プッシュ通知による認証チャレンジ

​

MFAトークンを取得する

MFA を使用したリソース所有者パスワードグラントによる認証で説明されている手順に従って、MFAトークンを取得します。

​

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

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

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

[
    {
        "id": "recovery-code|dev_Ahb2Tb0ujX3w7ilC",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "push|dev_ZUla9SQ6tAIHSz6y",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "auth0",
        "name": "user's device name"
    },
    {
        "id": "totp|dev_gJ6Y6vpSrjnKeT67",
        "authenticator_type": "otp",
        "active": true
    }
]

ユーザーがプッシュで登録すると、OTPにも登録されます。これは、ユーザーが接続できない状況でも Guardian が OTPでのチャレンジ をサポートしているためです。

​

プッシュでユーザーにチャレンジを求める

プッシュチャレンジを開始するには、対応する authenticator_id と mfa_token を使用して、MFA Challenge エンドポイントに POST リクエストを送信します。

​

受け取ったコードで認証を完了する

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

{
    "challenge_type": "oob",
    "oob_code": "Fe26...jGco"
}

アプリケーションは、ユーザーがプッシュ通知を承認するまで、OAuth0 Token endpoint へのポーリングを開始する必要があります。

この呼び出しは、次のいずれかの結果を返します。

結果	説明
authorization_pending	エラー: challenge がまだ承認または拒否されていない場合。
slow_down	エラー: polling の頻度が高すぎる場合。
access_token と refresh_token	challenge が承認された場合。この時点で polling は停止してください。
invalid_grant	エラー: challenge が拒否された場合。この時点で polling は停止してください。

​

MFA をカスタマイズする

リソース所有者パスワードグラント、埋め込み、またはリフレッシュトークンのフローでのカスタマイズ可能な MFA は、早期アクセスです。この機能を使用することで、Okta の Master Subscription Agreement に記載されている該当する無料トライアル条項に同意したものとみなされます。Auth0 のリリースステージの詳細については、Product Release Stages を参照してください。早期アクセスに参加するには、Auth0 Support にお問い合わせください。

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

oauth/token エンドポイントでの認証時には、レスポンスとして、MFA API で使用する mfa_token を含む mfa_required エラーと、認証器のリストを含む 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 Triggers: post-challenge - API Object をご覧ください。

​

詳細はこちら

• Authentication API を使用して認証要素を管理する
• MFA のプッシュ通知を設定する
• リカバリーコードでチャレンジする
• Email 認証器の登録とチャレンジ
• OTP 認証器の登録とチャレンジ
• SMS および Voice 認証器の登録とチャレンジ