Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Authentication Methods

Kubernetes and Cloud Authentication

Authenticate workloads to Vault with platform identity: Kubernetes service account tokens, AWS IAM and EC2, Azure managed identity, GCP service accounts, with role bindings explained.

The cleanest answer to "how does a machine prove who it is?" is: let the platform vouch for it. A pod runs under a Kubernetes service account; an EC2 instance or Lambda has an IAM role; an Azure VM has a managed identity; a GCE instance has a service account. Each platform can produce a signed statement of that identity. Vault's platform auth methods verify that statement, which removes the need to store a password or secret ID on the workload at all.

This lesson explains how the Kubernetes method works in detail and gives the idea behind the cloud methods. The models check role bindings.

Vault, Kubernetes and cloud accounts are not available here. Commands and manifests are read-only, and the output of real commands is never invented. The Python models are simplified stand-ins.

Kubernetes auth

Every pod can have a service account token, a signed JWT that identifies its namespace and service account. The kubernetes auth method lets a pod send this token to Vault. Vault asks the Kubernetes API to validate it (the TokenReview API) and then checks the result against a Vault role that binds service account names and namespaces to policies.

sequenceDiagram
    participant Pod
    participant V as Vault (auth/kubernetes)
    participant K as Kubernetes API
    Pod->>V: login: role=web, jwt=<service account token>
    V->>K: TokenReview(jwt)
    K-->>V: authenticated: namespace=prod, serviceaccount=web
    V->>V: match against role bindings
    V-->>Pod: Vault token with policies

The pod proves its identity with a credential Kubernetes already gave it.

Setup, run by a Vault admin:

Terminal
vault auth enable kubernetes

vault write auth/kubernetes/config \
    kubernetes_host="https://kubernetes.default.svc"
    # Vault inside the cluster can use its own pod token and CA

vault write auth/kubernetes/role/web \
    bound_service_account_names="web" \
    bound_service_account_namespaces="prod" \
    token_policies="web-read" \
    token_ttl=1h

Login from a pod:

Terminal
JWT=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
vault write auth/kubernetes/login role=web jwt="$JWT"

In practice you rarely write this by hand: Vault Agent or the Vault Secrets Operator / CSI provider / agent injector performs the login and renews the token for the application. Applications then read a file or environment variable.

Security points:

  • Bind roles to a specific service account and namespace; a wildcard * lets any pod in the cluster log in.
  • Prefer short-lived, audience-bound projected tokens over the legacy long-lived secret-based tokens.
  • Vault needs permission to call TokenReview (the system:auth-delegator cluster role for the service account Vault uses).

Cloud methods in brief

Method Identity presented What Vault checks
aws (iam) A signed sts:GetCallerIdentity request The caller's IAM role/user ARN against bound ARNs
aws (ec2) Instance identity document + signature Account, region, AMI, instance profile
azure A managed identity JWT Subscription, resource group, VM or identity
gcp Signed JWT for a service account, or GCE instance metadata Project, service account, labels

All follow the same pattern: the workload obtains a signed identity from the platform, sends it to Vault, Vault verifies it (often by calling the cloud's API or using published keys) and matches role bindings, then issues a token. Example AWS role (read-only):

Terminal
vault auth enable aws
vault write auth/aws/role/web-role \
    auth_type=iam \
    bound_iam_principal_arn="arn:aws:iam::123456789012:role/web" \
    token_policies="web-read" \
    token_ttl=1h

Other platform methods follow the same shape: the JWT/OIDC method accepts tokens from any compliant issuer (CI providers such as GitHub Actions, GitLab, or your own), the TLS certificates method trusts client certificates, and GitHub, OIDC and SAML are for people.

Role binding check you can run

Python Match a Kubernetes identity against role bindings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The debug role shows why wildcards are dangerous: any pod in any namespace obtains the everything policy.

AWS ARN matching

Python Bound IAM principal ARNs with a wildcard suffix

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Pay attention to the account ID in an ARN: a role with the same name in another AWS account is a different identity.

Choosing and combining

  • Running in Kubernetes: use the Kubernetes method plus Vault Agent or the Secrets Operator.
  • Running on cloud VMs or functions: use that cloud's method with narrow principal bindings.
  • Running in CI: use JWT/OIDC with claims such as repository and branch, so no secret is stored in the CI system.
  • Everywhere else: AppRole with wrapped, single-use secret IDs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does the Kubernetes auth method verify a pod?

    Vault asks Kubernetes whether the presented token is valid and which service account it belongs to.
  2. 2. Why avoid bound_service_account_names="" and namespaces=""?

    Roles should bind specific service accounts and namespaces.
  3. 3. What advantage do platform auth methods give over static credentials?

    They avoid the secret-zero problem because the identity comes from the platform.
  4. 4. Which method suits a GitHub Actions job without storing a Vault secret in GitHub?

    The CI provider issues a signed token per job, and Vault verifies its claims.

Summary

  • Platform auth methods let Vault trust identities issued by Kubernetes or a cloud, so workloads hold no static Vault credential.
  • Kubernetes auth validates the service account token via TokenReview and matches a role's bound names and namespaces.
  • AWS, Azure and GCP methods verify signed identities against bound principals, projects or resources.
  • JWT/OIDC covers CI and custom issuers; AppRole is the portable fallback.
  • Avoid wildcard bindings, and let Vault Agent or the Secrets Operator handle login and renewal.

Next: Vault Policies: Writing Your First ACL Policy