時刻ベースのワンタイムパスワードによる二要素認証(TOTP Authenticatorプラグイン)

PowerCMS X用の二要素認証(TOTP: Time-based One-Time Password)プラグインです。
画面キャプチャ：二要素認証のコード入力欄が表示された画面

概要

このプラグインは、Google Authenticator、Microsoft Authenticator、Okta Verifyなどの認証アプリを使用した二要素認証機能を提供します。ユーザーのログイン時に、パスワードに加えて時間ベースのワンタイムパスワードによる認証を要求することで、アカウントのセキュリティを向上させます。

※メール送信を用いた二要素認証・AuthTwilioプラグインによる二要素認証との併用はできません。

主な機能

TOTP認証 RFC 6238準拠の時間ベースワンタイムパスワード認証
QRコード対応 認証アプリへの簡単な登録
バックアップコード 認証アプリが使用できない場合の代替ログイン手段
ユーザー個別設定 各ユーザーが個別に二要素認証を設定可能
管理者機能 リストアクションからの一括設定削除

インストール

1. 依存パッケージのインストール

プロジェクトのルートディレクトリなどで以下のComposerコマンドを実行します：

composer require chillerlan/php-qrcode
composer require spomky-labs/otphp

初めてcomposerを使用する場合は環境変数composer_autoloadにautoload.phpのパスを指定してください。

2. シークレットキーの生成

プラグインに付属のツールを使用して、暗号化用のシークレットキーを生成します：

php path/to/plugins/TOTPAuthenticator/tools/make_secret_key.php

実行すると以下のような64文字の16進文字列が出力されます：

Secret key: 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f

重要: このシークレットキーは厳重に管理してください。漏洩した場合や紛失した場合、すべてのユーザーのTOTP設定をやり直す必要があります。

3. 設定ファイルの編集

powercmsx/config.jsonに以下の設定を追加します。totpauthenticator_issuer(認証アプリに表示される発行者名)の値は適宜変更してください。

"two_factor_method": "totp",
"totpauthenticator_secret_key": "[手順2で生成したシークレットキー]",
"totpauthenticator_issuer": "PowerCMS X"

二要素認証(TOTP)が未設定の場合に管理画面の操作を許可しないようにする場合、以下の環境変数を追加します。

"two_factor_auth_required": true,

管理画面の右上にある「設定」を開き、「2段階認証を利用する」にチェックを入れて二要素認証を有効化します。

使用方法

エンドユーザー向け

二要素認証の設定

  1. PowerCMS Xにログイン後、ユーザー編集画面（右上の人のアイコンをクリック）から「二要素認証(TOTP)のセットアップ」をクリックします
    画面キャプチャ：ユーザー編集画面の「二要素認証(TOTP)のセットアップ」の位置
  2. スマートフォンに認証アプリ(Google Authenticator等)をインストールします
  3. 表示されたQRコードを認証アプリでスキャンします
  4. 認証アプリに表示された6桁のコードを入力して設定完了です
  5. バックアップコードが表示されるので、安全な場所に保管します

ログイン手順(設定後)

  1. 通常通りユーザー名とパスワードを入力してログインします
  2. 認証コード入力画面が表示されます
  3. 認証アプリに表示されている6桁のコードを入力します
  4. ログイン完了です

バックアップコードの使用

認証アプリが使用できない場合(端末の紛失・故障等)：

  1. 認証コード入力画面で「バックアップコードを使用する」をクリックします
  2. 保管していたバックアップコード(例：A3F7-9K2P)を入力します
  3. ログイン完了です
注意

バックアップコードは一度使用すると再利用できません。残りが少なくなった場合は、二要素認証を再設定してください。

管理者向け

ユーザーの二要素認証設定を解除する

管理者は、他のユーザーの二要素認証設定を解除できます：

  1. ユーザー一覧画面で対象ユーザーを選択
  2. リストアクションから「二要素認証(TOTP)の設定を削除する」を選択
  3. 実行すると選択したユーザーのTOTP設定が削除されます
制限事項
  • リストアクションでは自分自身の設定は解除できません
  • 自分の設定を解除する場合は、ユーザー編集画面（右上の人のアイコンをクリック）から「二要素認証(TOTP)のセットアップ」をクリックし、「二要素認証(TOTP)の設定削除」ボタンで削除ができます
    画面キャプチャ：二要素認証(TOTP)の設定削除ボタンの位置

セキュリティ上の注意事項

  1. シークレットキーの管理

    • totpauthenticator_secret_keyは絶対に公開しないでください
    • バージョン管理システムにコミットしないよう注意してください

  2. バックアップコードの保管

    • ユーザーにバックアップコードの安全な保管を周知してください
    • 印刷またはパスワードマネージャーでの保管を推奨します

  3. HTTPSの使用

    • 二要素認証を使用する場合、必ずHTTPS環境で運用してください
    • 認証トークンの傍受を防ぐため、暗号化通信は必須です

トラブルシューティング

認証コードが一致しない

  • スマートフォンの時刻設定が正確か確認してください(自動時刻設定を推奨)
  • サーバーの時刻が正確か確認してください(NTP同期を推奨)
  • 認証コードは30秒ごとに更新されるため、古いコードを入力していないか確認してください

バックアップコードが使用できない

  • バックアップコードは一度使用すると無効になります
  • 未使用のバックアップコードを使用しているか確認してください
  • すべてのバックアップコードを使い切った場合は、管理者に設定解除を依頼してください

技術仕様

項目 内容
認証方式 TOTP (Time-based One-Time Password Algorithm, RFC 6238)
ハッシュアルゴリズム SHA-1
時間窓 30秒
コード長 6桁
バックアップコード 8個(初回設定時に生成)
暗号化 Sodium (libsodium) を使用した暗号化
日本語
ふりがな付き
English
简体中文
繁體中文
한국어