1. プラグイン概要・スマート認証の仕組み
EC-CUBEの管理画面を保護するために2段階認証を導入するショップが増えていますが、従来のワンタイムパスワードアプリ（Google Authenticator等）方式には大きな課題がありました。
- 社内オフィスや固定のPCからログインする際も、毎回スマートフォンを取り出してアプリを起動しコードを入力しなければならず、受注・出荷処理の初動が遅れる。
- スマホの機種変更や破損・紛失時にコードが確認できず、管理者が完全に締め出されてしまう事故が多発する。
本プラグイン（AdminSmart2fa）は、このストレスを解消するために「スマートIP検知機能」と「信頼端末記憶機構」を搭載しています。
2. 動作要件・システム環境
| 項目 | 要件・対応仕様 |
|---|---|
| EC-CUBE バージョン | EC-CUBE 4.2.0 〜 4.3.x（4.2系・4.3系両対応） |
| PHP バージョン | PHP 8.1 / PHP 8.2 / PHP 8.3 |
| データベース | MySQL 5.7 / 8.0 / PostgreSQL 10〜16 |
| メール送信環境 | EC-CUBE本体のメール送信設定（SMTPまたはmail関数）が正常に稼働していること。 |
3. インストール・有効化手順
-
1
プラグインのインストール
管理画面の「オーナーズストア ＞ プラグイン ＞ プラグイン一覧」より本プラグインをインストールします。
-
2
メール送信テストの確認
2段階認証コードは管理者の登録メールアドレスへ送信されます。事前にEC-CUBEの「基本設定 ＞ 店舗設定」や管理者登録画面でメールアドレスが正しいことを確認してください。
-
3
設定画面での有効化
左メニューの「設定 ＞ システム設定 ＞ 管理者2段階認証設定」へ進み、「プラグインの有効化」にチェックを入れて保存します。
4. 管理画面の設定項目一覧
「設定 ＞ システム設定 ＞ 管理者2段階認証設定」で設定可能な全パラメータの一覧です。
| 設定項目名 | 初期値 | 説明・設定のポイント |
|---|---|---|
プラグインの有効化isEnabled |
OFF | 2段階認証機能全体のON/OFFを切り替えます。 |
認証モードauthMode |
スマートIP検知 （推奨） |
|
信頼端末の記憶enableTrustedDevice |
ON（有効） | コード入力画面に「この端末（ブラウザ）を信頼する」チェックボックスを表示します。ONにすることで、IPが変動しやすいモバイル端末でも継続利用が快適になります。 |
信頼IPプール保持数maxTrustedIpsPerMember |
10 件 | 管理者アカウントごとに自動記憶する「過去に認証成功した信頼IP」の最大件数です（1〜50件）。上限を超えた場合は古い順に破棄されます。 |
コード桁数codeLength |
6 桁 | 確認コードの長さを 4桁 / 6桁 / 8桁 から選択します。通常は「6桁」が推奨されます。 |
コード有効期限codeLifetimeMinutes |
5 分 | ワンタイムコードの有効期間を 1分 / 5分 / 10分 / 15分 から選択します。 |
使用文字種codeCharType |
数字のみ | コードを「数字のみ（例: 839201）」または「英数字混在（例: 7K9mA2）」から選択します。スマートフォンでの入力のしやすさを考慮し「数字のみ」を推奨します。 |
ロックまでの連続失敗数maxFailureAttempts |
5 回 | 確認コードの連続誤入力許容回数です（3〜10回）。上限に達するとアカウントが一時ロックされます。 |
アカウントロック時間lockoutMinutes |
15 分 | 上限失敗時にログインを禁止する時間（分）です（5〜60分）。 |
メール件名・本文mailSubject / mailBody |
既定テンプレート |
コード送信メールの件名および本文を編集できます。 利用可能な置換タグ： %%shop_name%%（ショップ名）、%%admin_name%%（管理者名）、%%otp_code%%（確認コード）、%%expire_minutes%%（有効期限分）、%%ip_address%%（接続元IP）、%%user_agent%%（端末情報）
|
5. ログイン時の挙動とブルートフォース対策
本プラグインが有効な場合、管理者のログイン処理は以下のフローで安全に実行されます。
認証フローチャート
-
1
ID・パスワードの一次認証
通常のログイン画面でID・パスワードを入力します。
-
2
スマート判定（スキップ判定）
接続元IPが「信頼IPプール」に含まれているか、またはブラウザのCookieに有効な「信頼端末トークン」が存在する場合、追加認証なしで即座に管理画面トップへ遷移します。
-
3
未知のIPの場合：コード自動生成＆メール送信
未知のIPからのアクセスの場合は中間画面（コード入力画面）へリダイレクトされ、同時に登録メールアドレスへ確認コードが自動発信されます。
-
4
コード検証と信頼登録
正しいコードを入力するとログインが完了し、現在のIPが「信頼IPプール」に自動登録されます。「この端末を信頼する」にチェックが入っていた場合は端末トークンも発行されます。
6. SSHコンソールコマンド（緊急脱出機能）
「メールサーバーの不調でコードが届かない」「管理者がロックされてログインできない」といった予期せぬトラブルが発生した場合でも、サーバーのSSHターミナルから即座に対処できるよう、多彩なCLIコマンドを標準装備しています。
# 1. 2段階認証を緊急OFF（完全バイパスしてログインしたい場合）
$ bin/console admin-smart-2fa:disable
# 2. 2段階認証を再開（トラブル解消後）
$ bin/console admin-smart-2fa:enable
# 3. 失敗ロックされたアカウントのロックを即時解除
$ bin/console admin-smart-2fa:unlock [管理者ログインID]
# 4. 指定したIPアドレスを特定の管理者の信頼IPに直接追加
$ bin/console admin-smart-2fa:trust-ip [管理者ログインID] [IPアドレス]
# 5. 現在の稼働ステータスと設定内容を表示
$ bin/console admin-smart-2fa:status7. よくある質問・トラブルシューティング
Q. メールが届かず、確認コードを入力できません。
迷惑メールフォルダに振り分けられていないかご確認ください。また、EC-CUBE本体のメール送信設定（.env の MAILER_DSN や基本設定）が正しく構成されているかをご確認ください。緊急時は上記のSSHコマンド（bin/console admin-smart-2fa:disable）で一時的に機能をOFFにすることでログイン可能です。
Q. 自宅のインターネット回線はIPアドレスが定期的に変わります。
コード入力画面に表示される「この端末（ブラウザ）を信頼する」にチェックを入れてログインしてください。ブラウザに安全な永続トークンが記録されるため、IPアドレスが変わっても追加認証なしでログインできるようになります。
Q. 信頼していた端末の登録を取り消したい（盗難・紛失時など）
別の信頼済みPCまたはコード入力で管理画面にログイン後、「設定 ＞ システム設定 ＞ 管理者2段階認証設定」の「信頼端末・IP管理」タブより、該当の端末トークンを個別に削除可能です。