Vault Userpass 認証の基本：学習・小規模用途で手早く試す

userpass は Vault に内蔵されたシンプルな人間向け認証方式で、ラボや小規模利用に最適です。

本稿では、最小手順のセットアップ、認証フロー、ポリシー付与、運用の基本、他方式との比較、試験の落とし穴をまとめます。

userpass の概要と適用範囲

userpass は、Vault に対してユーザー名とパスワードでログインし、トークンを発行する認証方式です。外部 IdP を必要としないため、単体の Vault を素早く検証したいときに向いています。

一方で、企業規模の運用では SSO 連携 (OIDC など) やマシン認証 (AppRole, Kubernetes など) が推奨です。userpass は学習・小規模・一時的運用に限定すると割り切るのが現実的です。

• 長所: 導入が速い、依存が少ない、トラブルシュートが容易
• 短所: パスワード管理が必要、アカウントライフサイクル運用の負担、SSO/Federation 不可
• 適用: 個人学習、少人数の検証、PoC、隔離されたラボ環境

最小セットアップ：有効化からユーザー作成まで

Vault が初期化・アンシール済みで、管理者トークンを持っている前提です。CLI は VAULT_ADDR と VAULT_TOKEN を適切に設定してください。

userpass を有効化し、ユーザーを作成してポリシーを割り当てれば、すぐにログインできます。

• auth method の有効化は一度きり。デフォルトパスは auth/userpass/
• ユーザー作成は auth/userpass/users/<username> に write
• ポリシー名は既存の ACL ポリシーをカンマ区切りで指定

有効化とユーザー作成（CLI と HTTP API）

## 有効化（CLI）
$ vault auth enable userpass

## ユーザー作成（CLI）
$ vault write auth/userpass/users/alice \
    password="s3cr3t!" \
    policies="default,dev"

## ログイン（CLI）
$ vault login -method=userpass username=alice password="s3cr3t!"

## 有効化（HTTP API）
$ curl -sS \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  $VAULT_ADDR/v1/sys/auth/userpass \
  --data '{"type":"userpass"}'

## ユーザー作成（HTTP API）
$ curl -sS \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  $VAULT_ADDR/v1/auth/userpass/users/alice \
  --data '{"password":"s3cr3t!","policies":"default,dev"}'

認証フローとトークンの性質

userpass のログインは /v1/auth/userpass/login/:username にパスワードを送信し、応答の auth.client_token をクライアントが保存して以降のリクエストに使用します。トークンの有効期限 (ttl) は Vault 側の設定に従います。

auth method ごとに発行トークンのデフォルト TTL と最大 TTL をチューニングできます。CLI の vault auth tune で -token_ttl および -token_max_ttl を指定します。

• 発行トークンのポリシーはログイン時点で固定。後からユーザーのポリシーを変更しても既存トークンには反映されない
• renewable なトークンは期限前に vault token renew で延長可能（最大 TTL まで）
• 不要になったら vault token revoke またはユーザーを削除して利用停止を徹底

userpass 認証フロー（概念図）

トークンの確認と TTL チューニング

## トークンの属性を確認
$ vault token lookup

## userpass が発行するトークンの TTL を調整（例: デフォルト1h、最大4h）
$ vault auth tune -token_ttl=1h -token_max_ttl=4h userpass/

## トークンの延長（renewable な場合）
$ vault token renew

最小のポリシー設計：必要最小限で始める

userpass ユーザーには ACL ポリシーでアクセス境界を与えます。個人学習やチーム検証では、読み取り専用のスコープを明確にし、書き込みは限定的にします。

ポリシーの更新は次回発行されるトークンから反映されます。既存トークンに即時反映させたい場合は、対象トークンを revoke して再ログインさせます。

• 最小権限の原則: path を具体化し、capabilities は read/list から始める
• 共通権限は default ではなく専用の共通ポリシーで明示する
• 人間ユーザーの書き込みは監査対象のみに限定する

サンプルポリシーとユーザーへの適用

# dev.hcl（例：KV v2 の読み取りと限定的な書き込み）
path "secret/data/dev/*" {
  capabilities = ["create", "update", "read", "list"]
}

path "secret/metadata/dev/*" {
  capabilities = ["list", "read"]
}

# ポリシー登録
$ vault policy write dev dev.hcl

# ポリシーを付与してユーザー作成/更新
$ vault write auth/userpass/users/alice \
    password="rotate-2026-04" \
    policies="default,dev"

運用の基本：ローテーション、監査、無効化

小規模でも運用の要点は同じです。不要なアカウントやトークンを残さない、パスワードを定期的にローテーションする、監査ログを確認する、という基本を守ります。

auth method を無効化すると、そのメソッドが発行したトークンはすべて無効になります。計画的に実施してください。

• パスワードの管理は外部ルールで運用（Vault 自身は userpass の複雑度ポリシーを強制しない）
• 監査デバイスを有効化し、login 成功/失敗を追跡
• ユーザー変更は API idempotent に実行可能（同じエンドポイントに再 write）
• Enterprise の Namespaces 使用時は mount のパスに注意（例: ns1/auth/userpass/）

よく使う運用コマンド

## パスワード変更
$ vault write auth/userpass/users/alice password="new-P@ss-2026"

## ユーザー一覧
$ vault list auth/userpass/users

## ユーザー削除
$ vault delete auth/userpass/users/alice

## トークンの失効（強制ログアウト）
$ vault token revoke <token>

## auth method の無効化（影響大：要計画）
$ vault auth disable userpass/

他方式との比較：学習・小規模用途の位置づけ

学習や小規模用途では userpass の手軽さが強みです。対して、組織内運用では OIDC による SSO、マシンワークロードでは AppRole や Kubernetes Auth が現実解になります。

試験対策では、各方式の主目的と人間/マシン適性、導入コストの違いを言語化できることが重要です。

• ラボ開始: userpass、一段進んだ人間ログイン: GitHub/OIDC
• 自動化/CI: AppRole、Kubernetes 上の Pod: Kubernetes Auth
• 長期運用は IdP 連携を前提に設計する

Associate 試験対策：問われやすいポイント

Associate レベルでは、userpass の有効化、ユーザー作成、ログインフロー、ポリシー付与、トークン TTL 調整といった基本操作が問われやすいです。CLI と HTTP API の両方のパスを把握しておくと有利です。

TTL/Lease の混同に注意。auth が発行するのはトークンで、tune の対象は token_ttl/token_max_ttl。一方でシークレットエンジンはデフォルト/最大リース TTL を調整します。

• 有効化コマンド: vault auth enable userpass
• ユーザー作成パス: auth/userpass/users/<username>
• ログインエンドポイント: POST /v1/auth/userpass/login/:username
• トークン TTL 調整: vault auth tune -token_ttl -token_max_ttl userpass/

覚えておくと得点しやすいスニペット

# 有効化と TTL 調整（まとめ）
$ vault auth enable userpass
$ vault auth tune -token_ttl=1h -token_max_ttl=4h userpass/

# 作成・ログイン・確認
$ vault write auth/userpass/users/alice password="p" policies="dev"
$ vault login -method=userpass username=alice password="p"
$ vault token lookup

問題で確認

よくある質問