Skip to content

AppRole & JWT Auth

Vault supports three auth methods: OIDC for interactive human access, AppRole for Ansible and application sidecars, and JWT for GitLab CI/CD pipelines.

Auth Methods Summary

Method Path Used By Token TTL
OIDC auth/oidc/ Humans (interactive, via Authentik SSO) Session-based
AppRole auth/approle/ Ansible playbooks, Vault Agent sidecars 1 hour (renewable)
JWT auth/jwt/ GitLab CI/CD pipelines Short-lived (pipeline duration)

OIDC Authentication (Interactive)

Vault uses Authentik as the OIDC provider. When a user runs vault login -method=oidc, Vault redirects to https://sso.shared.cwiq.io for authentication. After login, the Vault token inherits policies based on the user's Authentik groups.

export VAULT_ADDR="https://vault.shared.cwiq.io"
vault login -method=oidc
# Opens browser → Authentik login → returns Vault token

This is the standard method for all interactive Vault operations by team members.

AppRole Authentication

AppRole is used by Ansible playbooks and Vault Agent sidecars. Each application gets its own AppRole with a least-privilege policy.

How AppRole Works

1. Admin creates AppRole and policy:
   vault write auth/approle/role/authentik \
     token_policies="authentik-read" \
     token_ttl=1h

2. Admin retrieves role-id (stable, not secret):
   vault read auth/approle/role/authentik/role-id

3. Admin generates secret-id (one-time):
   vault write -f auth/approle/role/authentik/secret-id

4. Ansible deploys both to /data/{app}/vault/config/ on the EC2 host

5. Vault Agent reads role-id + secret-id and calls:
   POST /v1/auth/approle/login
   Returns: Vault token with 1h TTL

6. Agent uses token to read secrets, auto-renews every 45 minutes

Creating a New AppRole for an Application

# 1. Create the policy
vault policy write <app>-read - <<'EOF'
path "secret/data/cwiq/shared/<app>/*" {
  capabilities = ["read", "list"]
}
EOF

# 2. Create the AppRole
vault write auth/approle/role/<app> \
  token_policies="<app>-read" \
  token_ttl=1h \
  token_max_ttl=4h

# 3. Get the role-id (not secret, can be stored in Ansible vars)
vault read auth/approle/role/<app>/role-id

# 4. Generate a secret-id (treat as a password)
vault write -f auth/approle/role/<app>/secret-id

Store both values in the Ansible playbook's group_vars/all.yml on the ansible server (never in the repo).

Listing Existing AppRoles

vault list auth/approle/role

JWT Authentication (GitLab CI/CD)

GitLab CI/CD pipelines authenticate with Vault using short-lived JWT tokens that GitLab generates for each pipeline run. No static credentials are stored in GitLab variables.

How JWT Works in CI/CD

1. Pipeline starts — GitLab generates a signed JWT for the job

2. Pipeline requests Vault token:
   curl --request POST \
     --header "X-Vault-Token: " \
     --data '{"jwt": "'"$CI_JOB_JWT_V2"'", "role": "gitlab-orchestrator"}' \
     $VAULT_ADDR/v1/auth/jwt/login

3. Vault validates JWT signature against GitLab's JWKS endpoint

4. Vault returns short-lived token matching the role's policy

5. Pipeline uses token to read secrets it needs

Vault JWT Role Configuration

vault write auth/jwt/role/gitlab-orchestrator \
  role_type="jwt" \
  bound_claims='{"project_path": ["orchestrator/*"]}' \
  user_claim="sub" \
  token_policies="nexus-ci,sonarqube-ci,defectdojo-ci" \
  token_ttl=15m \
  token_max_ttl=30m

The bound_claims constraint ensures only pipelines from GitLab project paths matching orchestrator/* can authenticate.

JWT Bound Claims Reference

Claim Source Example
project_path GitLab project path orchestrator/server
namespace_path GitLab namespace orchestrator
ref Branch or tag main
environment Deploy environment production

See CI/CD Integration for the full pipeline pattern.

Policy Reference

Each AppRole and JWT role maps to one or more policies. Policies grant the minimum access required.

Standard Policy Pattern

# Read-only access to application secrets
path "secret/data/cwiq/shared/<app>/*" {
  capabilities = ["read", "list"]
}

# Allow listing the path
path "secret/metadata/cwiq/shared/<app>/*" {
  capabilities = ["list"]
}

Listing Existing Policies

vault policy list

# View a specific policy
vault policy read <app>-read