Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Authentication Methods

AppRole Authentication

Learn the AppRole auth method for machines: role ID versus secret ID, creating roles, delivering secret IDs with response wrapping, TTLs and use limits, and the pull and push models.

AppRole is the general-purpose machine login method. An application presents two values: a role ID, which is like a username and identifies the role (the kind of workload), and a secret ID, which is like a password and proves the caller is an authorized instance. Splitting them lets different systems deliver each half, so that stealing one is not enough.

This lesson creates a role, explains how the two IDs travel, and shows the settings that make secret IDs short-lived and single-use. Runnable models cover the login check and the delivery pattern.

Vault is not available here; the commands are read-only and I do not print real IDs or tokens. The Python code models role and secret ID rules in simplified form.

Two halves, two delivery paths

  • Role ID: static, not very secret, tied to the role. Typically baked into the machine image or config by your provisioning tool.
  • Secret ID: dynamic, can be single-use and short-lived, generated on demand. Typically delivered by a trusted broker (for example the CI system or an orchestrator) at deploy time.

An attacker needs both. If the role ID leaks from a config repository, it is useless without a valid secret ID; if a secret ID is intercepted, it is useless without the role ID, and a single-use one is gone after the first login.

sequenceDiagram
    participant Prov as Provisioner (trusted)
    participant V as Vault
    participant App as Application
    Prov->>V: read role-id (static)
    Prov->>V: write secret-id, wrap-ttl 60s
    V-->>Prov: wrapping token
    Prov->>App: role-id + wrapping token
    App->>V: unwrap, get secret-id
    App->>V: login with role-id + secret-id
    V-->>App: client token with the role's policies

The two halves arrive by different routes, and the secret ID is wrapped in transit.

Setting it up

Terminal
vault auth enable approle

vault write auth/approle/role/web \
    token_policies="web-read" \
    token_ttl=1h \
    token_max_ttl=4h \
    secret_id_ttl=10m \
    secret_id_num_uses=1 \
    token_num_uses=0

vault read  -field=role_id auth/approle/role/web/role-id
vault write -f -wrap-ttl=60s auth/approle/role/web/secret-id

The final command, run by the trusted broker, returns a wrapping token instead of the secret ID (see Cubbyhole and Response Wrapping). The application unwraps it and logs in:

Terminal
vault write auth/approle/login role_id="$ROLE_ID" secret_id="$SECRET_ID"

The response includes auth.client_token. Important role settings:

Setting Purpose
token_policies Policies attached to the issued token
token_ttl, token_max_ttl Lifetime of tokens
secret_id_ttl How long a generated secret ID stays valid
secret_id_num_uses How many logins one secret ID allows (0 = unlimited)
secret_id_bound_cidrs / token_bound_cidrs Restrict by source IP address
bind_secret_id Require a secret ID (default true)

Use secret_id_num_uses=1 and a short TTL whenever the delivery path allows it. Restrict the policy path that can generate secret IDs to the broker identity only: whoever can write auth/approle/role/web/secret-id can mint access for that role.

Pull versus push

  • Push: the broker generates a secret ID and pushes it to the app (wrapped).
  • Pull: the app retrieves what it needs from a trusted authority at startup, for example using a CI job's own identity to request the secret ID for the job.

In either case, the key design question is: what already-trusted identity authenticates the delivery? In CI, it is often the CI provider's signed identity token (see the JWT method) rather than a stored Vault secret.

Login logic you can run

Python Model AppRole login with single-use secret IDs

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 replay fails because secret_id_num_uses=1 consumed the secret ID on first login: if an attacker used it first, your own application would be refused and you would notice.

Choosing TTLs

Python How long is the secret ID exposed?

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.

Single-use secret IDs shrink the exposure to the delivery delay.

Pitfalls

  • Reusing one long-lived secret ID across many servers turns it into a shared password.
  • Putting both role ID and secret ID in the same config file defeats the split.
  • Letting the application renew tokens beyond token_max_ttl is impossible; it must log in again with a new secret ID, so design the secret ID delivery for restarts and re-logins.
  • Forgetting CIDR binding where addresses are stable.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which AppRole value is meant to be short-lived and delivered at runtime?

    The role ID is static; the secret ID is dynamic and can be single use.
  2. 2. What does secret_id_num_uses=1 give you?

    After one successful login the secret ID is consumed, so replays fail.
  3. 3. Why wrap the secret ID when the broker hands it to the application?

    Response wrapping limits exposure and gives tamper evidence.
  4. 4. Who should be able to write to auth/approle/role/web/secret-id?

    Whoever can generate secret IDs can mint access to the role.

Summary

  • AppRole splits machine login into a role ID and a secret ID, delivered by different routes.
  • Prefer short-lived, single-use secret IDs delivered with response wrapping.
  • Roles define policies, token TTLs, secret ID TTLs, use counts and CIDR bindings.
  • Restrict secret ID generation to a trusted broker.
  • Platform-based methods are better when the platform offers identity.

Next: Kubernetes and Cloud Authentication