ログイン画面に2段階認証を実装する
概要
Kurocoのログインのエンドポイントには2段階認証を実装するためのパラメータの準備があり、Email, Authenticator, SMSによる2段階認証を容易に実装できます。
本チュートリアルでは3つの認証方法による2段階認証のログイン動作を確認し、それを利用したフロントエンドのコードを紹介します。
学べること
以下の手順でログイン画面に2段階認証を実装します。
前提条件
このページは、KurocoとNuxt.jsでのプロジェクトが構築済みであることを前提としています。
まだ構築していない場合は、下記のチュートリアルを参照してください。
本チュートリアルでは以下のバージョンでコードを書いています。
Nuxt2: v2.15.8
Nuxt3: v3.8.0
本ドキュメントではCookie認証による設定の流れを説明します。
動的アクセストークンを利用する場合は、動的アクセストークンの場合の認証方法も参照してください。
2段階認証の動作を確認する
Emailによる2段階認証
エンドポイントの作成
任意のAPIで「新しいエンドポイントの追加」をクリックします。

以下の設定をします。
| 項目 | 設定内容 |
|---|---|
| パス | 2steplogin/email |
| カテゴリー | 認証 |
| モデル | Login |
| オペレーション | login_challenge |
| twofactor_method |

設定ができたら[追加する]をクリックしてエンドポイントを追加します。
SwaggerUIで動作の確認
対象のAPIから[Swagger UI]をクリックします。

追加したエンドポイントを開き[Try it out]をクリックします。

認証情報を入力して[Execute]をクリックします。

正しい認証情報が入力された場合は「追加の認証情報が必要です。」のレスポンスが返ります。

ユーザーのメールアドレス宛に認証コードが届きます。

通知の内容はlogin/authentication_codeのメッセージひな形で編集可能です。
Request bodyからpasswordを削除し、onetime_passwordを入力して再度[Execute]をクリックします。

grant_tokenが発行され、ログインできたことを確認できました。

Authenticatorによる2要素認証
Authenticatorによる2要素認証を利用するには、メンバーごとにAuthenticator(Google Authenticatorなどの認証アプリ)を登録する必要があります。
本チュートリアルでは、ログインしたメンバーがAPIを使って自身のAuthenticatorを登録する手順を説明します。
エンドポイントの作成
任意のAPIで「新しいエンドポイントの追加」をクリックします。

以下の設定をします。
| 項目 | 設定内容 |
|---|---|
| パス | 2steplogin/code |
| カテゴリー | 認証 |
| モデル | Login |
| オペレーション | login_challenge |
| twofactor_method | code |

設定ができたら[追加する]をクリックしてエンドポイントを追加します。
同様に、Authenticatorの登録とログアウトに使う以下のエンドポイントを追加します。
| パス | カテゴリー | モデル | オペレーション |
|---|---|---|---|
| 2steplogin/authenticator/reserve | 認証 | TwofactorMethod | reserve |
| 2steplogin/authenticator/regist | 認証 | TwofactorMethod | regist |
| logout | 認証 | Login | logout |
ログアウトのエンドポイントがすでにある場合は、そのエンドポイントを利用してください。
ワンタイムパスワードを登録する
対象のAPIから[Swagger UI]をクリックします。

2steplogin/codeのエンドポイントを開き[Try it out]をクリックし、認証情報(email、password)を入力して[Execute]をクリックします。
Authenticatorを登録していないため、パスワードのみでログインが成功します。
2steplogin/authenticator/reserveのエンドポイントを開き[Try it out]をクリックし、[Execute]をクリックします。
レスポンスのsecret_strに、Authenticatorに登録するシークレットキーが返ります。

Authenticatorのアプリを開き、secret_strの値をセットアップキーとして入力します。
QRコードで読み込ませる場合は、otpauth://totp/ラベル?secret=secret_strの値の形式のURIをQRコードに変換してください。ラベルには、アプリ上でアカウントを識別するための文字列(サイト名やメールアドレスなど)を指定します。
2steplogin/authenticator/registのエンドポイントを開き[Try it out]をクリックし、アプリに表示された6桁の認証コードをverify_codeに入力して[Execute]をクリックします。
レスポンスのmessagesに「登録しました。」が返れば、登録は完了です。

TwofactorMethodのエンドポイントは、ログイン中のメンバーのAuthenticatorを登録します。ログインしていない状態ではエラーになります。reserveを実行してから24時間以内にregistを実行してください。- Authenticatorを登録済みのメンバーが
reserve、registを実行するとエラーになります。登録し直す場合は、TwofactorMethod::deleteで登録を削除してから実行してください。
最後にlogoutのエンドポイントを実行してログアウトします。
ログイン中のメンバーと同じメンバーでログインした場合は2段階目の認証が要求されないため、次の動作確認の前に必ずログアウトしてください。
SwaggerUIで動作の確認
対象のAPIから[Swagger UI]をクリックします。

追加したエンドポイントを開き[Try it out]をクリックします。

認証情報を入力して[Execute]をクリックします。

正しい認証情報が入力された場合は「追加の認証情報が必要です。」のレスポンスが返ります。

端末からGoogle Authenticatorのアプリを開き認証コードを確認します。
Request bodyからpasswordを削除し、onetime_passwordを入力して再度[Execute]をクリックします。

grant_tokenが発行され、ログインできたことを確認できました。

SMSによる2要素認証
SMSによる2要素認証を利用するには、Twilioとの連携が必要です。
また、メンバー情報の電話番号に"090","080","070","060"から始まる日本国内の電話番号が登録されている必要があります。
始めに、以下のドキュメントを参考に設定をしてください。
エンドポイントの作成
SMS利用の準備ができたら、任意のAPIで「新しいエンドポイントの追加」をクリックします。

以下の設定をします。
| 項目 | 設定内容 |
|---|---|
| パス | 2steplogin/sms |
| カテゴリー | 認証 |
| モデル | Login |
| オペレーション | login_challenge |
| twofactor_method | sms |

設定ができたら[追加する]をクリックしてエンドポイントを追加します。
SwaggerUIで動作の確認
対象のAPIから[Swagger UI]をクリックします。

追加したエンドポイントを開き[Try it out]をクリックします。

認証情報を入力して[Execute]をクリックします。

正しい認証情報が入力された場合は「追加の認証情報が必要です。」のレスポンスが返ります。

SMSで認証コードが届きますので値を確認します。
通知の内容はlogin/sms_authentication_codeのメッセージひな形で編集可能です。
Request bodyからpasswordを削除し、onetime_passwordを入力して再度[Execute]をクリックします。

grant_tokenが発行され、ログインできたことを確認できました。

追加認証の強制
Authenticatorによる2要素認証(twofactor_method: code)では、Authenticatorを登録していないメンバーは、パスワードのみでログインが成功します。
ログイン後にAuthenticatorを登録させることを想定していますが、ログインをさせずにエラーを出したい場合はカスタム処理を作成し、後処理に設定することで対応してください。
Emailによる2段階認証、SMSによる2要素認証では、メールアドレスや電話番号が登録されていないなどの理由で認証コードを送信できなかった場合、ログインは失敗します。パスワードのみでログインが成功することはありません。
以下は追加の認証情報のステップを通さずにログインが完了した場合に、強制ログアウトし、エラーのレスポンスを出す後処理の例です。
{if isset($smarty.post.password) && $json.grant_token != null}
{append var=json.errors value='追加の認証情報が登録されていません。'}
{logout}
{/if}
{assign var=processed_json value=$json}

フロントエンドの実装をする
最後に、SwaggerUIで確認した動作をフロントエンドで実装します。
/login/2step_login/のディレクトリにindex.vue のファイルを作成します。
以下はEmailを利用した2段階認証の例です。
- Nuxt2
- Nuxt3
loading...
loading...
上記サンプルのサンプルは参考のため最低限のコードになっています。
実際に利用する際には、フォームのバリデーション処理や、@nuxt/auth などのライブラリもご利用ください。
/rcms-api/1/2steplogin/emailの部分はご自身のエンドポイントのURLに変更してください。
動作確認
実行し、動作確認ができたら、ログイン画面への2段階認証の実装は完了です。

動的アクセストークンの場合の認証方法
動的アクセストークンを利用する場合、2段目の認証に Login::login_challenge_mfa のエンドポイントを使用します。

アクセストークン取得までの流れは以下のようになります。
- Login::login_challengeのエンドポイントにemail/passwordをPOSTし、mfa_access_tokenを取得する

- Login::login_challenge_mfa のエンドポイントに以下のリクエストを送り、grant_tokenを取得する
- mfa_access_tokenをX-RCMS-API-ACCESS-TOKENのヘッダーに含める
- Request bodyにonetime_passwordを含める
3. grant_tokenをLogin::token のエンドポイントにPOSTするとアクセストークンが取得できる
関連ドキュメント
サポート
お探しのページは見つかりましたか?解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。