Job identity with ID tokens and OpenBao

Short-lived secrets for protected branches only, and the job token allowlist.

Advanced15 min · lesson 10 of 17
Lesson files
The scripts, test data and local test servers this lesson uses, exactly as they ran on the lab machine (20 files, 8 KB): oidc.tar.gz. The lab VM shares no folders with your computer, so fetch them inside the VM: cd ~/lab && curl -fsSLO https://secopslog.com/lab-files/ci-gitlab/oidc.tar.gz && tar -xzf oidc.tar.gz, which creates ~/lab/oidc/. SHA-256: 8462befe127648221783bf8126acf38af528e9af938232b0873459ea884eae5c

Every secret stored in a CI/CD variable has the same three weaknesses: it lives as long as someone remembers to rotate it, everyone who can read the settings can copy it, and any job on a ref that receives it can leak it. A better pattern is not to store the secret in GitLab at all. The job proves who it is, and a secret manager hands it a credential that expires in minutes and works only for that job's project and branch.

A job has an identity

GitLab is an OpenID Connect provider. It publishes signing keys, and on request it signs a token for a job that says which project, ref and pipeline the job belongs to:

ubuntu@secopslog-cicd:~/lab/oidc · GitLab 19.5.3
$ ./up.sh
runner lab-runner: online (tags: lab,docker) GitLab 19.5.3 is up on http://127.0.0.1:8929
$ curl -fsS http://127.0.0.1:8929/.well-known/openid-configuration | jq -c '{issuer, jwks_uri, id_token_signing_alg_values_supported}'
{"issuer":"http://gitlab:8929","jwks_uri":"http://gitlab:8929/oauth/discovery/keys","id_token_signing_alg_values_supported":["RS256"]}

A job asks for such an ID token with the id_tokens keyword, naming the audience it is meant for. Anything that trusts GitLab's keys can check the signature and read the claims. This lab uses OpenBao, the open-source fork of HashiCorp Vault, started next to GitLab in dev mode. bao-setup.sh stores one secret and creates a role that trusts GitLab's tokens only for one audience (bound_audiences) and only when the signed claims match (bound_claims):

bao-setup.sh
#!/usr/bin/env bash
# Starts OpenBao next to GitLab and lets GitLab jobs log in with their ID token, but only for
# protected branches of root/app. Policy "deploy" can read one secret. Safe to run again.
set -euo pipefail
grep -q '^BAO_TOKEN=' .env || echo "BAO_TOKEN=$(openssl rand -hex 16)" >> .env
docker compose -f compose.yaml -f bao.yaml --progress quiet up -d bao
bao() { docker compose -f compose.yaml -f bao.yaml exec -T -e BAO_ADDR=http://127.0.0.1:8200 -e "BAO_TOKEN=$(grep '^BAO_TOKEN=' .env | cut -d= -f2)" bao bao "$@"; }
for _ in $(seq 30); do bao status >/dev/null 2>&1 && break; sleep 1; done
bao kv get secret/deploy >/dev/null 2>&1 || bao kv put secret/deploy password="$(openssl rand -hex 12)" >/dev/null
bao policy write deploy - >/dev/null <<'POL'
path "secret/data/deploy" { capabilities = ["read"] }
POL
bao auth list | grep -q '^jwt/' || bao auth enable jwt >/dev/null
bao write auth/jwt/config jwks_url=http://gitlab:8929/oauth/discovery/keys bound_issuer=http://gitlab:8929 >/dev/null
bao write auth/jwt/role/deploy - >/dev/null <<'ROLE'
{
"role_type": "jwt",
"user_claim": "sub",
"bound_audiences": ["http://bao:8200"],
"bound_claims": { "project_path": "root/app", "ref_type": "branch", "ref_protected": "true" },
"token_policies": ["deploy"],
"token_ttl": "5m",
"token_max_ttl": "10m"
}
ROLE
echo "OpenBao ready: role deploy accepts protected branches of root/app"
ubuntu@secopslog-cicd:~/lab/oidc · GitLab 19.5.3
$ ./bao-setup.sh
OpenBao ready: role deploy accepts protected branches of root/app

Three OpenBao words are new here. A *policy* lists what a login may do, here read one secret. A *role* says which tokens may log in and which policies they get. A *lease* is how long the login lasts. The secret is stored at secret/deploy, and the policy names secret/data/deploy because the key-value engine keeps data under that internal path. The role accepts a token only if it was issued for audience http://bao:8200, for project root/app, on a branch that is protected. A token from any other project, or from a feature branch, gets nothing.

A protected branch

app/.gitlab-ci.yml
# The job asks GitLab for an ID token meant for OpenBao, and uses it instead of a stored secret.
deploy:
image: secopslog-py:3.15
id_tokens:
BAO_ID_TOKEN:
aud: http://bao:8200
script:
- python bao_login.py
read-other:
image: secopslog-py:3.15
rules:
- if: $READ_OTHER == "yes"
script:
- git clone -q "http://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab:8929/root/other.git" /tmp/other && echo "cloned root/other with the job token"
app/bao_login.py
"""Shows the job's ID token claims, trades the token for an OpenBao token, and reads one secret."""
import base64, json, os, urllib.error, urllib.request
jwt = os.environ["BAO_ID_TOKEN"]
payload = jwt.split(".")[1]
claims = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
for k in ("iss", "aud", "sub", "project_path", "ref", "ref_type", "ref_protected", "pipeline_source"):
print(f"claim {k} = {claims.get(k)}")
print(f"expires in {claims['exp'] - claims['iat']} s")
def call(path, body=None, token=None):
req = urllib.request.Request("http://bao:8200/v1/" + path, data=json.dumps(body).encode() if body else None)
if token:
req.add_header("X-Vault-Token", token)
with urllib.request.urlopen(req) as r:
return json.load(r)
try:
auth = call("auth/jwt/login", {"role": "deploy", "jwt": jwt})["auth"]
except urllib.error.HTTPError as e:
print("login refused:", json.load(e)["errors"][0])
raise SystemExit(1)
print(f"logged in: policies {auth['token_policies']}, lease {auth['lease_duration']} s")
secret = call("secret/data/deploy", token=auth["client_token"])["data"]["data"]["password"]
print(f"read secret/deploy: {len(secret)} characters")
ubuntu@secopslog-cicd:~/lab/oidc · GitLab 19.5.3
$ ./seed.sh app app/ && ./pipeline.sh app/
pushed app: 712a89a first commit --- job deploy (test): success $ python bao_login.py claim iss = http://gitlab:8929 claim aud = http://bao:8200 claim sub = project_path:root/app:ref_type:branch:ref:main claim project_path = root/app claim ref = main claim ref_type = branch claim ref_protected = true claim pipeline_source = push expires in 3600 s logged in: policies ['default', 'deploy'], lease 300 s read secret/deploy: 24 characters pipeline #1: success

The job printed the claims GitLab signed: issuer http://gitlab:8929, audience http://bao:8200, project_path = root/app, ref = main and ref_protected = true. OpenBao checked the claims against the role, logged the job in with the deploy policy and a 300 s lease, and the job read the 24-character secret. The ID token itself is valid for 3600 s, and it is a bearer credential: anyone who copies it out of the job can log in with it until it expires, so never print it. The OpenBao token can be renewed, but the role's token_max_ttl stops it at 10 minutes. Nothing in GitLab's settings held that secret.

An unprotected branch

ubuntu@secopslog-cicd:~/lab/oidc · GitLab 19.5.3
$ echo "# feature" >> app/bao_login.py && ./commit.sh app/ "feature work" feature/x && ./pipeline.sh app/ | grep -E "^(claim ref|login|logged|read|--- job|pipeline)"; exit ${PIPESTATUS[0]}
pushed: 968c8dc feature work to feature/x --- job deploy (test): failed claim ref = feature/x claim ref_type = branch claim ref_protected = false login refused: error validating claims: claim "ref_protected" does not match any associated bound claim values pipeline #2: failed

Same project, same job, same code, and OpenBao refused it: claim "ref_protected" does not match. The decision was made from claims GitLab signed, so a developer who edits the job on a branch can't change them. Compare that with a protected variable, which also depends on the ref being protected, but which, once a job has it, stays valid until someone rotates it.

Stored variableID token + secret manager
Where the secret livesIn GitLab, readable by MaintainersIn the secret manager only
LifetimeUntil someone rotates itMinutes (5, at most 10 here)
Who may use itAny job on a ref that receives itOnly tokens whose signed claims match the role
After a leakValid until rotatedExpires on its own within minutes; nothing to rotate in GitLab
Watch out
Bind roles to claims an attacker can't choose. project_path, ref_protected and ref_type are set by GitLab. A bound claim on ref alone is weaker than it looks: anyone who can push a branch with that name on an unprotected pattern matches it. And always bind the audience, so a token meant for one service can't be replayed to another. Paths can be renamed and later reused, so production roles bind project_id and namespace_id rather than project_path, and add ref when only one branch may deploy, because on the Free tier ref_protected accepts every protected branch of the project. The lab's plain-HTTP key URL and dev-mode OpenBao are lab only.

The CI job token and other projects

Every job also gets CI_JOB_TOKEN, a short-lived token GitLab issues for the job itself. It can clone repositories, pull packages and call parts of the API with the permissions of the user who started the pipeline. Its reach into other projects is limited by an allowlist on the project being accessed, and for new projects that allowlist is enforced from the start:

ubuntu@secopslog-cicd:~/lab/oidc · GitLab 19.5.3
$ ./seed.sh other other/ && ./gl.sh /projects/root%2Fother/job_token_scope | jq -c '{inbound_enabled}'
pushed other: 40752f3 first commit {"inbound_enabled":true}
$ git -C app checkout -q main && ./run-pipeline.sh app READ_OTHER=yes >/dev/null && sleep 3 && ./pipeline.sh app/ | sed -n "/--- job read-other/,\$p"; exit ${PIPESTATUS[0]}
--- job read-other (test): failed $ git clone -q "http://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab:8929/root/other.git" /tmp/other && echo "cloned root/other with the job token" remote: Authentication by CI/CD job token not allowed from app to project #2. fatal: unable to access 'http://gitlab:8929/root/other.git/': The requested URL returned error: 403 ERROR: Job failed: exit code 128 pipeline #3: failed

Root can read other, yet the job couldn't, because other hasn't allowed app. Add app to other's allowlist. The command looks up both numeric project IDs first, because the endpoint takes the allowed project as a numeric target_project_id:

ubuntu@secopslog-cicd:~/lab/oidc · GitLab 19.5.3
$ ./gl.sh /projects/$(./gl.sh /projects/root%2Fother | jq .id)/job_token_scope/allowlist -X POST -d target_project_id=$(./gl.sh /projects/root%2Fapp | jq .id) | jq -c '{source_project_id, target_project_id}'
{"source_project_id":2,"target_project_id":1}
$ ./run-pipeline.sh app READ_OTHER=yes >/dev/null && sleep 3 && ./pipeline.sh app/ | sed -n "/--- job read-other/,\$p"
--- job read-other (test): success $ git clone -q "http://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab:8929/root/other.git" /tmp/other && echo "cloned root/other with the job token" cloned root/other with the job token pipeline #4: success

In the reply, source_project_id 2 is other, the project whose allowlist changed, and target_project_id 1 is app, the project now allowed in. Keep allowlists short and reviewed, list single projects rather than whole groups, and leave "allow Git push with the job token" off. Each entry means every pipeline of that project can act on this one, with the triggering user's permissions.

Hands-on

Tighten the role so only pipelines started by a push get a secret: add "pipeline_source": "push" to bound_claims in bao-setup.sh and run ./bao-setup.sh again (it rewrites the role). The worked version, solutions/bao-setup.sh, also updates the message the script prints. Then start a pipeline on main with ./run-pipeline.sh app, which is an API trigger, and read the login line. Finish with ./down.sh.

What you should see: the worked bao-setup.sh reports that role deploy now accepts pushes to protected branches of root/app. The API-triggered pipeline runs on main, which is protected, yet login is refused: claim "pipeline_source" does not match any associated bound claim values, because the token says pipeline_source = api. Each bound claim narrows who may log in, and the decision rests on what GitLab signed, not on what the job claims.

Remember

Prefer an ID token and a secret manager over a stored secret. Bind the role to the audience, the project and ref_protected, keep credentials short-lived, and keep job token allowlists small.

Quick check
01A role in the secret manager has bound_claims of {"ref": "main"} only. Why is that too weak?
Incorrect — It is. The lab printed claim ref = main.
Correct — Every fork, and many other projects, have one. Bind the project, by ID, and ref_protected too, so a branch name alone is never enough.
Incorrect — The claims are fixed when the token is issued.
Incorrect — It enforces them. They are just too broad.
02What does the aud (audience) claim protect against?
Incorrect — That is the exp claim.
Incorrect — That is what ref_protected is for.
Incorrect — Nothing in the token prevents that. Keep tokens out of logs.
Correct — It stops a token meant for one service being replayed to another. Each service accepts only tokens issued for its own audience.
03A job in project A clones private project B with CI_JOB_TOKEN and gets 403, although the user who started the pipeline can read B. What is the likely cause?
Correct — The lab saw "Authentication by CI/CD job token not allowed" until app was added to other's allowlist.
Incorrect — They can, once the target project allows it.
Incorrect — That would work around the control instead of using it.
Incorrect — Private projects work once they allowlist the caller.

Related