Vault TOTP エンジン実践ガイド: 運用で外さないワンタイムパスワード管理

TOTP は30秒前後の短い有効期限を持つワンタイムパスワード方式です。Vault の TOTP Secrets Engine は、TOTP 秘密鍵の保管・コード生成・検証を API/CLI で一元化します。

本記事は、公式ドキュメントに基づく安定機能に限定して、導入から運用・監査・トラブルシュートまでを網羅します。Ops 視点でのポリシー設計や監査イベントも押さえ、試験対策ポイントも明示します。

TOTP エンジンの役割と全体像

Vault の TOTP Secrets Engine は、ユーザやサービス毎の TOTP 秘密鍵を安全に格納し、コードの生成および検証を提供します。クライアントは Vault を単一のトラスト・アンカーとして利用し、TOTP 取り扱いを標準化できます。

エンジンの基本機能は、鍵の登録/生成、現在コードの取得、入力コードの検証、鍵の一覧/削除です。いずれも専用のパス配下で実行し、ACL で細かく権限制御できます。

• 有効期限・桁数・発行者名などのパラメータを鍵単位で管理可能
• QR コードや otpauth URL を発行してユーザに配布可能（生成時の出力）
• コード生成と検証の API を分離し、最小権限の設計が容易

TOTP エンジンによるコード生成・検証の流れ

エンジン有効化と基本操作（CLI）

vault secrets enable totp

# 鍵の生成（issuer/account_name を明示）
vault write totp/keys/alice generate=true issuer="ExampleCorp" account_name="[email protected]"

# 現在コードの取得（クライアント側 2FA 入力代替など）
vault read totp/code/alice

# 入力コードの検証（true/false）
vault write totp/validate/alice code=123456

# 鍵の一覧と削除
vault list totp/keys
vault delete totp/keys/alice

プロビジョニング: 鍵登録と配布の実務

プロビジョニング担当は、ユーザごとに一意の名前を付けて鍵を登録します。名前は組織・用途・所有者を判別できる構成にし、後の棚卸しや削除フローを容易にします。

鍵は Vault 側で生成する方法（generate=true）と、既存の TOTP シークレットを持ち込む方法があります。運用一貫性の観点では Vault 生成を推奨します。生成時の出力には、otpauth URL や QR コード表現（サイズ指定など）が含まれるため、配布チャネルの保護と保管禁止のルール化が必須です。

• 名前規約例: totp/keys/app-prod/alice のように環境・アプリ・所有者を階層化
• issuer と account_name はユーザ端末アプリでの表示名に反映されるため、統一ルールを定義
• 生成出力は閲覧権限を絞り、二次保管（スクリーンショット等）を禁止

QR 付きで登録し、安全に配布する例（CLI と cURL）

# QR サイズを指定して鍵を生成
evault write totp/keys/app-prod/alice generate=true issuer="ExampleCorp" account_name="[email protected]" qr_size=200

# API での作成（例）
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"generate":true, "issuer":"ExampleCorp", "account_name":"[email protected]", "qr_size":200}' \
  $VAULT_ADDR/v1/totp/keys/app-prod%2Falice

# 応答に含まれる otpauth URL/QR データは直ちに利用者へ安全送付し、保存しない運用を徹底

最小権限ポリシー設計: 生成・検証・削除の分離

TOTP は閲覧範囲が広がるほどリスクが上がります。鍵の生成者、コードの取得者、検証を行うサービス、削除を行う管理者を論理的に分離し、それぞれのパスに必要最小限の権限のみを付与します。

監査上は誰がいつ鍵を発行し、誰が検証を実行したかが重要です。Vault の監査デバイスを有効化し、TOTP パス配下の操作をすべて記録します。

• 鍵発行ロール: totp/keys/* に create, update、読み取りは最小限
• 検証ロール: totp/validate/* に update、totp/code/* への read は不要な場合は付与しない
• 削除ロール: totp/keys/* に delete、実行前に二人承認など外部プロセスで統制

HCL ポリシー例（ロール分離）

# 鍵発行ロール（プロビジョナー）
path "totp/keys/app-prod/*" {
  capabilities = ["create", "update", "list"]
}

# 検証ロール（バックエンド API）
path "totp/validate/app-prod/*" {
  capabilities = ["update"]
}

# コード取得ロール（やむを得ずサーバ側でコード生成が必要な場合）
path "totp/code/app-prod/*" {
  capabilities = ["read"]
}

# 削除ロール（管理者）
path "totp/keys/app-prod/*" {
  capabilities = ["delete", "list"]
}

ライフサイクル運用: 命名、棚卸し、ローテーション

TOTP 鍵は動的リースではありません。明示的に棚卸しし、不要になった鍵は削除します。定期棚卸しでは所有者・最終使用時刻（検証ログ）・連絡先を対応付けて確認します。

ローテーションは新規鍵の発行と旧鍵の無効化を段階的に実行します。ユーザ側で Authenticator を再登録する手順をあらかじめ標準化し、移行期間を設定します。

• 一覧取得: vault list totp/keys で対象を洗い出す
• 利用実績の推定: 監査ログから totp/validate/* の呼び出し履歴を分析
• ローテーション計画: 新旧並行期間を明示し、旧鍵の削除は計画ウィンドウで実施

棚卸しと安全な削除の手順（例）

# 棚卸し
vault list -format=json totp/keys | jq -r '.[]' > keys.txt

# 対象ごとに最終検証時刻を監査ログから集計（監査ログの保存先に依存）
# 例: jq で totp/validate パスを抽出し、key 名でグルーピング

# 安全な削除（事前承認・告知後）
while read k; do
  echo "deleting $k";
  vault delete totp/keys/$k;
done < keys.txt

セキュリティ・監査: NTP、監査ログ、レスポンスラッピング

TOTP は時刻同期が前提です。Vault サーバ群と検証クライアントは信頼できる NTP で同期してください。時刻ずれは誤検知やロックアウトの原因になります。

監査はエンジン利用の前提です。Vault の監査デバイスを有効化し、totp/ 配下の read/update/delete をすべて記録します。鍵生成時の出力はラッピングトークンで配布し、使い切り・短期 TTL を徹底します。

• 時刻同期: OS の NTP クライアントを運用標準に含める
• 監査: 誰がいつ鍵を発行/削除/検証したかを追跡可能に
• 配布チャネル: otpauth URL/QR はレスポンスラッピングで一時化

監査とレスポンスラッピングの例

# 監査デバイスの有効化（例: ファイル）
vault audit enable file file_path=/var/log/vault_audit.log

# ラッピング（応答を 300 秒の一時トークンに包む）
vault write -wrap-ttl=300s totp/keys/app-prod/bob generate=true issuer="ExampleCorp" account_name="[email protected]"
# 出力された wrapping_token を安全な経路で配布

# 受領側が unwrap
evault unwrap <wrapping_token>

トラブルシュートと試験対策の要点

検証が失敗する場合、まず時刻同期、鍵名の取り違え、桁数や期間設定の不一致を確認します。生成側と検証側で issuer/account_name の視覚差異も誤認の原因になります。

資格試験（Ops）では、エンジンの有効化、パスごとの権限分離、監査の有効化、レスポンスラッピングの使い所といった運用設計が問われやすいです。CLI での基本操作と HCL ポリシーの読解を確実にしておきましょう。

• 典型的な誤り: totp/code と totp/validate の取り違え
• NTP の未設定や時刻ドリフトによる false 判定
• 削除・再発行時の周知不足によるユーザロックアウト

よくある確認コマンド

# パスの存在確認と一覧
vault list totp/keys

# 個別キーのメタ確認（出力内容は権限に依存）
vault read totp/keys/app-prod/alice || echo "権限/存在を確認"

# 直近の検証可否を手動チェック
vault write totp/validate/app-prod/alice code=$(vault read -field=code totp/code/app-prod/alice)

問題で確認

よくある質問