RoleID
A role identifier; often non-secret but still scoped operational data.
Chapter contract
Prerequisites:
Chapter 6 complete and bootstrap-generated AppRole inputs present under .runtime.
User-visible outcome:
orders-api can exchange separately delivered AppRole factors for a short-lived, scoped token.
Learning objectives
- Compare AppRole, AWS IAM, Kubernetes, and JWT by trust source.
- Perform AppRole login from protected runtime files.
- Keep RoleID and SecretID delivery paths independent.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Defines consumption, validation, reload, and stop-using behavior. |
| Platform team owns | Provides trusted runtime identity, protected delivery, network, and telemetry. |
| Vault owns | Operates auth mounts, policies, engines, audit, and recovery. |
Core concepts
SecretID
The secret factor, ideally short-lived and response-wrapped.
Response wrapping
A single-purpose token transfers sensitive response data.
Native identity
A signed runtime identity such as IAM, Kubernetes, or CI OIDC.
Commands and configuration
source learn-vault/.runtime/learner.env
cd learn-vault/labs/approle-app
./login.sh
jq '{policies:.auth.policies,lease_duration:.auth.lease_duration}' ../../.runtime/approle-login.json
./whoami.shSecret-safety stop
Stop: If RoleID and SecretID live in the same image, repository, CI variable set, or bundle, AppRole has become a static shared credential.
Failure drill
| Symptom | AppRole login reports invalid role or secret ID. |
|---|---|
| Likely causes | Wrong mount, expired or exhausted SecretID, wrong-environment RoleID, or bind mismatch. |
| Inspect safely | Check file presence, modes, timestamps, role, mount, and SecretID accessor metadata. |
| Do not print | SecretID, wrapping token, unwrap response, or Vault token. |
Break it / fix it
Break it: Swap RoleID and SecretID or use an expired SecretID.
Show diagnosis and fix
Fix it: Restore separately delivered factors or mint a new bounded SecretID through bootstrap.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Use bootstrap-generated RoleID and SecretID files to log in; scripts retain the response only under ignored runtime storage.
cd learn-vault/labs/approle-app
./login.sh
test -s ../../.runtime/approle-login.json
jq -e '.auth.policies|index("lockbox-orders-api")' ../../.runtime/approle-login.json
test "$(stat -f '%Lp' ../../.runtime/approle-login.json)" = 600
./cleanup.shSuccess criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- Login has the lockbox-orders-api policy and a finite TTL.
- The response file is mode 0600.
- Cleanup removes the token-bearing response.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Run the lab cleanup. Bootstrap can mint a fresh SecretID for another session.
Project Lockbox increment
AppRole is the portable local identity; production prefers AWS IAM on EC2 and Kubernetes auth on EKS.
Quick check
When does AppRole fit?
Machines or legacy schedulers without a verifiable platform identity.
Why separate the factors?
One delivery-channel compromise should not complete the login.
What does wrapping protect?
Sensitive response delivery through an intermediary.
What is preferred on EKS?
A narrowly bound Kubernetes service-account identity.
Gotchas
- SecretID accessors manage IDs without revealing them.
- Unlimited long-lived SecretIDs create rotation debt.
- Pull-mode delivery still needs an initial trusted identity.
Recap and next
Workload auth should derive trust from the runtime; AppRole is a controlled fallback, not the universal default.