VaultでのJWT / OIDC 認証: IDプロバイダ統合の実務とAssociate対策

OIDCはOAuth 2.0上のIDレイヤ、JWTはそのトークン形式。Vaultは双方に対応する認証メソッド（auth method）を提供します。

本稿は、人がブラウザでSSOするOIDCと、ワークロードが機械間で提示するJWTの統合パターンを中心に、最小構成から試験頻出ポイントまでを実務目線で解説します。

OIDC / JWTの基礎とVaultの用語整理

OIDCはOAuth 2.0にIDトークン（ID Token, JWT）を追加した仕様です。認可コードフローでIdPが発行するIDトークンをVaultが検証し、ユーザ（またはワークロード）を識別します。Vaultは認証メソッドとして「oidc」「jwt」を提供し、前者はディスカバリと対話的ログイン（ブラウザ）を前提、後者は外部で発行済みのJWTを提示して機械的に検証します。

VaultのアイデンティティはEntityとAliasで管理されます。各Auth Method（例: oidc、jwt、userpassなど）から来る識別子（sub等）がAliasとなり、同一人物・ワークロードを同一Entityに統合できます。発行されるVaultトークンにはポリシーが付与され、TTLや再認証の要件はロール設定で制御します。

• OIDCのキーポイント: issuer(iss), audience(aud), subject(sub), nonce, scope, redirect_uri
• JWT検証の核心: 署名検証（JWK/JWKS/公開鍵）、issとaudの照合、exp/nbfの時刻検証
• Vault Associateで狙われやすい: auth methodとsecrets engineの違い、Entity/Alias、ポリシー付与、claims mapping

JWTの基本構造（参考）

{
  "header": {"alg": "RS256", "kid": "..."},
  "payload": {
    "iss": "https://idp.example.com/",
    "sub": "00u123abc",
    "aud": "vault",
    "exp": 1710000000,
    "groups": ["dev", "ops"]
  },
  "signature": "..."
}

IDプロバイダ統合アーキテクチャ（人/ワークロード）

人のSSOにはOIDC Auth Methodが適します。Vault CLIやUIはローカルでコールバック（標準でhttp://localhost:8250/oidc/callback）を受け、IdPの認可コードをVaultへ引き渡します。Vaultはディスカバリエンドポイント経由でIdPのJWKSを取得し、IDトークンを検証します。

ワークロード連携では、アプリやジョブランナーがIdP（またはプラットフォームが発行するOIDC/JWT）から受け取ったJWTを提示し、VaultのJWT Auth Methodで非対話的に検証します。これによりヘッドレス環境や自動化パイプラインでも安全にトークンを取得できます。

• CLIのOIDCログインはローカルポート8250でのコールバックが既定（変更可能）。
• 人=OIDC、機械=JWTという棲み分けが基本。Kubernetesなど一部プラットフォームは専用Auth Methodも提供。
• Entity/AliasでIdP由来の一意な識別子（通常はsub）をマッピングしてポリシーを付与する。

Vault OIDC ログインの流れ

 [User/CLI]
      | 1. vault login -method=oidc
      v
 [Local Callback 8250]  <-- 3. redirect with code ---  [IdP (OIDC)]
      ^                          2. auth request  -->         |
      |                                                         v
      |------------------ 4. code -> Vault OIDC auth ----------|
                              |
                              v
                      [JWKS取得/IDトークン検証]
                              |
                              v
                 [Identity: Entity + Alias 解決]
                              |
                              v
                        [Vault Token 発行]

CLIでのOIDCログイン例

export VAULT_ADDR="https://vault.example.com"
export VAULT_NAMESPACE=""  # Enterpriseで必要なら設定
vault login -method=oidc

事前準備（IdP側）: クライアント登録とクレーム設計

IdPでOIDCクライアントを登録し、リダイレクトURIにhttp://localhost:8250/oidc/callback（CLI）やVault UIのコールバックURIを設定します。クライアントタイプは機密クライアント（client_secretを持つ）を選ぶのが一般的です。

IDトークンのクレームに、少なくともiss, sub, aud, expが含まれる必要があります。グループベースの制御を行う場合はgroups等のカスタム/標準クレームを付与し、Vault側でclaim_mappingsやgroups_claimによりポリシーへ結びつけます。

• リダイレクトURIは厳格一致。誤差やサフィックス違いで失敗しやすい。
• audにはVault側の期待値を設定（例: "vault"）。JWT Auth Methodでbound_audiencesに合わせる。
• 時刻同期（NTP）は必須。exp/nbf不一致で検証失敗が起きやすい。

参考: IdPのIDトークン例（必要最小クレーム）

{
  "iss": "https://idp.example.com/",
  "sub": "00u123abc",
  "aud": "vault",
  "email": "[email protected]",
  "groups": ["dev", "ops"],
  "iat": 1709996400,
  "exp": 1710000000
}

Vault側の設定（OIDC Auth Method）: ロール設計とクレームマッピング

OIDC Auth Methodでは、ディスカバリURL/クライアント資格情報を設定し、ロールごとにリダイレクトURIやスコープ、ユーザ識別クレーム、グループクレーム、付与ポリシーを定義します。最小構成から始め、必要なスコープとクレームだけを要求するのが安全です。

ポリシーは最小権限で設計し、グループクレームをIdentity Groupにエイリアス連携することで、IdP側グループ変更が即座に反映されるパターンが運用で扱いやすいです。

• user_claimは通常sub。メール等は一意性に注意。
• allowed_redirect_urisはCLI/UI両方を列挙する。
• oidc_scopesは必要最小限（例: openid, profile, email, groups）。

OIDC Auth Methodの有効化とロール例

# 有効化
vault auth enable oidc

# グローバル設定（ディスカバリとクレデンシャル）
vault write auth/oidc/config \
  oidc_discovery_url="https://idp.example.com" \
  oidc_client_id="vault-client" \
  oidc_client_secret="s.********" \
  default_role="web"

# ロール定義
vault write auth/oidc/role/web \
  user_claim="sub" \
  bound_audiences="vault" \
  allowed_redirect_uris="http://localhost:8250/oidc/callback" \
  allowed_redirect_uris="https://vault.example.com/ui/vault/auth/oidc/oidc/callback" \
  oidc_scopes="openid,profile,email,groups" \
  groups_claim="groups" \
  claim_mappings="email=alias_email" \
  token_policies="dev"

# ログイン（ブラウザ連携）
vault login -method=oidc

Vault側の設定（JWT Auth Method）と方式比較

JWT Auth Methodは、外部で発行済みのJWTをVaultが検証する非対話的な方法です。jwks_url（または公開鍵）とbound_issuer、bound_audiences等を指定し、ロールで検証要件と付与ポリシーを定義します。CI/CDやサーバサイドのマシンIDに向いています。

KubernetesやクラウドのワークロードID（例: OIDCフェデレーション）も、原理的にはJWT検証です。VaultにはKubernetes専用のAuth Methodもありますが、汎用JWTで統合する設計も可能です。

• jwks_urlを使うと鍵ローテーションに強い（IdP側のJWK更新を自動追随）。
• aud/iss/subの境界を明確化し、ロールでbound_*を適切に絞る。
• ヘッドレス環境ではOIDCよりJWTが実装容易。

JWT Auth Methodの有効化とロール例

# 有効化
vault auth enable jwt

# JWT検証設定（JWKS推奨）
vault write auth/jwt/config \
  jwks_url="https://idp.example.com/.well-known/jwks.json" \
  bound_issuer="https://idp.example.com/"

# ロール定義（audやsubの束縛で絞り込み）
vault write auth/jwt/role/ci \
  role_type="jwt" \
  user_claim="sub" \
  bound_audiences="vault" \
  bound_subject="repo:org/app:ref:refs/heads/main" \
  token_policies="ci-readonly"

# ログイン（JWT提示）
JWT=$(cat idp-issued.jwt)
vault write auth/jwt/login role="ci" jwt="$JWT"

運用・トラブルシュートとAssociate試験での要点

検証失敗の大半はiss/aud不一致、時刻ずれ、リダイレクトURI不一致、鍵の取り違いです。まずJWTをデコードし、Vaultロールのbound_*と照合、IdPのディスカバリ/ JWKSをcurlで確認するのが定石です。

試験対策としては、Auth MethodとSecrets Engineの違い、Entity/Aliasの概念、ポリシー適用の流れ、OIDCとJWTの使い分け、roles/claim_mappings/groups_claimの役割を明確にしておくと得点に直結します。

• JWTデコードでiss/aud/sub/expを確認し、ロール設定と突き合わせる。
• Vaultトークンのポリシー確認はvault token lookupで。
• IdPのJWKSに複数鍵がある場合はkid一致を確認。

現場で使う確認手順の例

# 1) JWTの中身を確認（署名は検証しないがクレーム把握に有用）
cut -d'.' -f2 <<< "$JWT" | base64 -d 2>/dev/null | jq .

# 2) IdPのディスカバリ/JWKS確認
curl -s https://idp.example.com/.well-known/openid-configuration | jq .
curl -s https://idp.example.com/.well-known/jwks.json | jq .

# 3) Vaultロール/設定の点検
vault read -format=json auth/jwt/config | jq .
vault read -format=json auth/jwt/role/ci | jq .

# 4) 発行されたVaultトークンの確認
vault token lookup <vault_token>

問題で確認

よくある質問