Job identity with ID tokens and OpenBao
Short-lived secrets for protected branches only, and the job token allowlist.
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: 8462befe127648221783bf8126acf38af528e9af938232b0873459ea884eae5cEvery 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:
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):
#!/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 pipefailgrep -q '^BAO_TOKEN=' .env || echo "BAO_TOKEN=$(openssl rand -hex 16)" >> .envdocker compose -f compose.yaml -f bao.yaml --progress quiet up -d baobao() { 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; donebao kv get secret/deploy >/dev/null 2>&1 || bao kv put secret/deploy password="$(openssl rand -hex 12)" >/dev/nullbao policy write deploy - >/dev/null <<'POL'path "secret/data/deploy" { capabilities = ["read"] }POLbao auth list | grep -q '^jwt/' || bao auth enable jwt >/dev/nullbao write auth/jwt/config jwks_url=http://gitlab:8929/oauth/discovery/keys bound_issuer=http://gitlab:8929 >/dev/nullbao 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"}ROLEecho "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
# The job asks GitLab for an ID token meant for OpenBao, and uses it instead of a stored secret.deploy:image: secopslog-py:3.15id_tokens:BAO_ID_TOKEN:aud: http://bao:8200script:- python bao_login.pyread-other:image: secopslog-py:3.15rules:- 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"
"""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.requestjwt = 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")
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
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 variable | ID token + secret manager | |
|---|---|---|
| Where the secret lives | In GitLab, readable by Maintainers | In the secret manager only |
| Lifetime | Until someone rotates it | Minutes (5, at most 10 here) |
| Who may use it | Any job on a ref that receives it | Only tokens whose signed claims match the role |
| After a leak | Valid until rotated | Expires on its own within minutes; nothing to rotate in GitLab |
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:
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:
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.
bound_claims of {"ref": "main"} only. Why is that too weak?claim ref = main.ref_protected too, so a branch name alone is never enough.aud (audience) claim protect against?exp claim.ref_protected is for.CI_JOB_TOKEN and gets 403, although the user who started the pipeline can read B. What is the likely cause?app was added to other's allowlist.