JWT / OIDC Authentication in Vault: IdP Integration in Practice and Associate Exam Prep

OIDC is an identity layer on top of OAuth 2.0, and JWT is the token format it uses. Vault provides auth methods that support both.

This article focuses on the two integration patterns you'll actually deploy: OIDC for humans signing in via a browser, and JWT for workloads presenting tokens machine-to-machine. We cover everything from minimal configuration to the points that show up most often on the exam.

OIDC / JWT Basics and Vault Terminology

OIDC is OAuth 2.0 plus an ID Token (a JWT). In the authorization code flow, Vault verifies the ID Token issued by the IdP to identify a user (or workload). Vault ships two relevant auth methods: oidc, which assumes discovery and an interactive browser login, and jwt, which mechanically verifies an externally-issued JWT that the client presents.

Vault identities are managed via Entities and Aliases. The identifier (typically sub) coming from each auth method (oidc, jwt, userpass, etc.) becomes an Alias, and the same person or workload can be unified under a single Entity. Issued Vault tokens carry policies, while TTLs and re-authentication requirements are controlled by the role configuration.

• Key OIDC fields: issuer (iss), audience (aud), subject (sub), nonce, scope, redirect_uri
• Core of JWT verification: signature check (JWK / JWKS / public key), iss and aud matching, and exp / nbf time validation
• Likely Vault Associate exam topics: the difference between auth methods and secrets engines, Entity / Alias, policy assignment, and claims mapping

JWT structure (reference)

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

IdP Integration Architecture (Humans vs. Workloads)

For human SSO, the OIDC Auth Method is the right fit. The Vault CLI and UI receive the callback locally (the default is http://localhost:8250/oidc/callback) and hand the IdP's authorization code to Vault. Vault fetches the IdP's JWKS via the discovery endpoint and validates the ID Token.

For workload integrations, the app or job runner presents a JWT it received from the IdP (or a platform-issued OIDC / JWT), and Vault's JWT Auth Method verifies it non-interactively. This lets headless environments and automation pipelines obtain Vault tokens securely.

• OIDC login from the CLI defaults to a callback on local port 8250 (configurable).
• The basic split is humans = OIDC, machines = JWT. Some platforms like Kubernetes also offer dedicated auth methods.
• Use Entity / Alias to map the unique identifier from the IdP (usually sub) and attach policies.

Vault OIDC login flow

 [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 発行]

OIDC login example from the CLI

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

Prerequisites on the IdP Side: Client Registration and Claim Design

Register an OIDC client on the IdP and set the redirect URIs to http://localhost:8250/oidc/callback (CLI) and the Vault UI's callback URI. The client type is typically a confidential client (one that holds a client_secret).

The ID Token must include at least iss, sub, aud, and exp. For group-based access control, add a custom or standard groups claim and bind it to policies via claim_mappings or groups_claim on the Vault side.

• Redirect URIs must match exactly — even a small difference or suffix mismatch will break the flow.
• Set aud to what Vault expects (e.g., "vault") and align it with bound_audiences on the JWT Auth Method.
• Time sync (NTP) is mandatory. exp / nbf mismatches are a common cause of verification failures.

Reference: IdP ID Token example (minimum required claims)

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

Vault Configuration (OIDC Auth Method): Role Design and Claim Mapping

On the OIDC Auth Method, configure the discovery URL and client credentials, then define per-role redirect URIs, scopes, user identifier claims, group claims, and the policies to grant. Start with the minimum configuration and only request the scopes and claims you actually need.

Design policies for least privilege. Linking group claims to Identity Groups via aliases makes group changes on the IdP take effect immediately — a pattern that's easy to operate over time.

• user_claim is normally sub. Be careful with email or other values that may not be uniquely stable.
• List both the CLI and UI URIs in allowed_redirect_uris.
• Keep oidc_scopes to the minimum needed (e.g., openid, profile, email, groups).

Enabling the OIDC Auth Method and an example role

# 有効化
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 Configuration (JWT Auth Method) and Method Comparison

The JWT Auth Method is the non-interactive path: Vault verifies a JWT that was issued elsewhere. You specify jwks_url (or a public key), bound_issuer, bound_audiences, and so on, then define verification requirements and policies per role. It's well suited to CI/CD and server-side machine identities.

Kubernetes and cloud workload identities (such as OIDC federation) are JWT verification under the hood. Vault offers a dedicated Kubernetes Auth Method, but you can also integrate via the generic JWT method if that fits better.

• jwks_url is resilient to key rotation — Vault automatically picks up JWK updates from the IdP.
• Define clear boundaries for aud / iss / sub and tighten bound_* values on each role.
• In headless environments, JWT is easier to implement than OIDC.

Enabling the JWT Auth Method and an example role

# 有効化
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"

Operations, Troubleshooting, and Key Points for the Associate Exam

Most verification failures come down to iss / aud mismatches, clock drift, redirect URI mismatches, or the wrong key. The standard playbook: decode the JWT, compare it against the role's bound_* values, and curl the IdP's discovery and JWKS endpoints to check what's actually being served.

For the exam, make sure you're crisp on the difference between Auth Methods and Secrets Engines, the Entity / Alias model, how policies are applied, when to choose OIDC vs JWT, and what roles, claim_mappings, and groups_claim actually do. Those topics translate directly into points.

• Decode the JWT to inspect iss / aud / sub / exp, then reconcile them with the role configuration.
• Use vault token lookup to inspect the policies attached to a Vault token.
• When the IdP's JWKS contains multiple keys, verify that the kid matches.

A field-tested verification workflow

# 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>

Check Your Understanding

Frequently Asked Questions