Vault TOTP Engine Practical Guide: One-Time Password Management That Holds Up in Operations

TOTP is a one-time password scheme with a short validity period of roughly 30 seconds. Vault's TOTP Secrets Engine centralizes the storage of TOTP secret keys, code generation, and verification behind a single API/CLI surface.

This article focuses on stable features described in the official documentation, covering everything from onboarding through operations, auditing, and troubleshooting. It includes Ops-oriented policy design and audit events, and calls out the points that matter for the exam.

What the TOTP Engine Does and How It Fits

Vault's TOTP Secrets Engine securely stores per-user or per-service TOTP secret keys and provides code generation and verification. Clients can use Vault as a single trust anchor and standardize how TOTP is handled across the organization.

The engine's core capabilities are key registration/generation, retrieving the current code, validating an input code, and listing/deleting keys. Each operation lives under a dedicated path, so you can apply fine-grained ACLs.

• Manage parameters such as period, digit count, and issuer name on a per-key basis
• Generate QR codes and otpauth URLs as part of the create-time output for distribution to users
• Code generation and verification live on separate APIs, making least-privilege design straightforward

Code generation and verification flow with the TOTP engine

Enabling the engine and basic CLI operations

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

Provisioning: Practical Key Registration and Distribution

The provisioning owner registers each key with a unique name per user. Structure the name so the organization, purpose, and owner are obvious, which makes downstream inventory and deletion workflows much easier.

There are two ways to create a key: have Vault generate it (generate=true) or bring an existing TOTP secret. For operational consistency, Vault-side generation is preferred. The create-time output includes an otpauth URL and a QR code representation (with sizing options), so protecting the distribution channel and prohibiting downstream storage must be codified as policy.

• Naming convention example: layer environment, app, and owner — e.g., totp/keys/app-prod/alice
• issuer and account_name appear in the user's authenticator app, so define a unified convention for both
• Restrict view access to the generation output and prohibit secondary storage (screenshots, etc.)

Registering with a QR code and distributing it safely (CLI and 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 データは直ちに利用者へ安全送付し、保存しない運用を徹底

Least-Privilege Policy Design: Separating Generation, Verification, and Deletion

The broader the read access to TOTP, the higher the risk. Logically separate the key creator, the code retriever, the verifying service, and the deleting administrator, and grant only the minimum capabilities required on each path.

From an audit perspective, who issued a key and who ran a verification — and when — matters most. Enable Vault audit devices and record every operation under the TOTP paths.

• Key issuer role: create and update on totp/keys/*; keep read to a minimum
• Verifier role: update on totp/validate/*; do not grant read on totp/code/* unless it is genuinely needed
• Deletion role: delete on totp/keys/*; gate execution behind an external process such as two-person approval

Example HCL policies (role separation)

# 鍵発行ロール（プロビジョナー）
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"]
}

Lifecycle Operations: Naming, Inventory, and Rotation

TOTP keys are not dynamic leases. Inventory them explicitly and delete those that are no longer needed. During periodic inventories, cross-reference each key with its owner, last-use timestamp (from verification logs), and contact information.

Rotation is a phased process: issue a new key and then invalidate the old one. Standardize the steps users follow to re-enroll their authenticator app, and define a transition window in advance.

• List the targets: use vault list totp/keys to enumerate keys
• Estimate usage: analyze the call history for totp/validate/* in the audit log
• Rotation plan: spell out the dual-running period and delete the old key within a planned window

Example inventory and safe-deletion procedure

# 棚卸し
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

Security and Auditing: NTP, Audit Logs, and Response Wrapping

TOTP assumes accurate time synchronization. Sync the Vault servers and verification clients against a trusted NTP source. Clock drift causes both false negatives and lockouts.

Auditing is a prerequisite for using this engine. Enable Vault audit devices and record every read, update, and delete under totp/. Distribute the create-time output via a wrapping token, and enforce single-use and short TTLs.

• Time sync: include the OS NTP client in your operational baseline
• Auditing: make it traceable who issued, deleted, or verified each key, and when
• Distribution channel: ephemeralize otpauth URL/QR data with response wrapping

Example: auditing and response wrapping

# 監査デバイスの有効化（例: ファイル）
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>

Troubleshooting and Exam Focus Points

When verification fails, first check time sync, mis-typed key names, and mismatches in digit count or period. Visual differences in issuer/account_name between the generating side and the verifying side are also a common source of confusion.

On the Ops certification, expect operations-design questions about enabling the engine, splitting capabilities by path, turning on auditing, and knowing where response wrapping fits. Lock in the basic CLI operations and HCL policy reading skills.

• Common mistake: confusing totp/code with totp/validate
• False results caused by missing NTP setup or clock drift
• User lockouts due to poor communication during deletion or re-issuance

Common diagnostic commands

# パスの存在確認と一覧
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)

Check Your Understanding

Frequently Asked Questions