OTP認証器の登録とチャレンジ

ワンタイムパスワード（OTP）を認証要素として使い、独自のMFAフローを構築する方法を説明します。

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

​

前提条件

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

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

​

OTPを登録する

​

MFAトークンを取得する

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

• authentication 中に登録する場合は、リソース所有者パスワードグラントとMFAを使用して認証する を参照してください。
• ユーザーがいつでも認証要素を登録できるようにする場合は、MFA 認証要素の登録を管理する を参照してください。

​

認証器を登録する

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

OTP で登録するには、authenticator_types パラメータを [otp] に設定します。

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

{
  "authenticator_type": "otp",
  "secret": "EN...S",
  "barcode_uri": "otpauth://totp/tenant:user?secret=...&issuer=tenant&algorithm=SHA1&digits=6&period=30",
  "recovery_codes": [ "N3B...XC"]
}

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

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

​

OTP の登録を確認する

登録を確認するには、エンドユーザーが前の手順で取得したシークレットを、Google Authenticator のような OTP 生成アプリケーションに入力する必要があります。シークレットは、barcode_uri の QR コードをスキャンするか、その OTP アプリケーションにシークレットコードを手動で入力して登録できます。ユーザーが QR コードをスキャンできない場合に備えて、シークレットをテキストとして取得できる手段も提供してください (たとえば、モバイル端末から登録している場合や、デスクトップの OTP アプリケーションを使用している場合) 。

ユーザーがシークレットを入力すると、OTP アプリケーションに 6 桁のコードが表示されるので、そのコードをアプリケーションに入力してもらいます。次に、その otp の値を含めて、アプリケーションから OAuth の Token endpoint に POST リクエストを送信する必要があります。

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

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

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

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

​

OTP を使用したチャレンジ

​

MFA トークンを取得する

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

​

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

MFA Authenticators エンドポイントを使用すると、登録済みの認証器をすべて一覧表示できます。

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

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

​

受け取ったコードを使用して認証を完了する

ユーザーはワンタイムパスワードを受け取るので、そのコードをユーザーから受け取ります。otpパラメータにワンタイムパスワードを指定してOAuth0のトークンエンドポイントを使用すると、コードを検証し、認証トークンを取得できます:

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

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

​

MFA をカスタマイズする

リソース所有者パスワードグラント、埋め込み、またはリフレッシュトークンのフローにおけるカスタマイズ可能な MFA は、早期アクセスで提供されています。この機能を使用すると、Okta のマスターサブスクリプション契約に定める該当する Free Trial 条項に同意したものとみなされます。Auth0 のリリースステージの詳細については、製品のリリースステージを参照してください。早期アクセスへの参加をご希望の場合は、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 オブジェクトをご覧ください。

​

詳しく見る

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