Day 12: GitLab CI and Jenkins
Goal: GitLab jobs log in to OpenBao via
id_tokens, and Jenkins fetches secrets via AppRole with a wrapped secret ID. · Duration: approx. 90 min · Prerequisite: Day 10
Briefing
- GitLab issues JWTs only if the job requests them via
id_tokens:with its ownaud. The issuer is the URL of the GitLab instance. - Important claims:
project_id,project_path,namespace_path,ref,ref_type,ref_protected,environment,environment_protected. - Two ways in the job:
secrets:withvault:(Premium/Ultimate, the runner fetches the secret) orbaoin the job image (any edition, full control). - Jenkins without OIDC: AppRole from Day 10. The controller is the trusted orchestrator and passes only a wrapping token to the agent.
GitLab job ── id_tokens (aud) ──▶ auth/jwt-gitlab/login role=shop-deploy
Jenkins ── issuer token ──▶ secret-id (wrapped)
└──▶ agent: unwrap ──▶ approle/login
Drill 1: GitLab Issuer via Discovery
For your instance, you enter its URL. Discovery supplies the keys
from /oauth/discovery/keys. To try it out, use gitlab.com
in a throwaway mount:
mkdir -p ~/secrets-lab/tag12 && cd ~/secrets-lab/tag12
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
curl -s https://gitlab.com/.well-known/openid-configuration | jq '{issuer, jwks_uri}'
bao auth enable -path=jwt-gitlab-com jwt >/dev/null
bao write auth/jwt-gitlab-com/config oidc_discovery_url=https://gitlab.com \
bound_issuer=https://gitlab.com
bao read -field=status auth/jwt-gitlab-com/config; echo
bao auth disable jwt-gitlab-comExpected:
{
"issuer": "https://gitlab.com",
"jwks_uri": "https://gitlab.com/oauth/discovery/keys"
}
Success! Data written to: auth/jwt-gitlab-com/config
valid
Success! Disabled the auth method (if it existed) at: jwt-gitlab-com/
For your own instance it looks like this (pattern, do not run):
bao write auth/jwt-gitlab/config \
oidc_discovery_url=https://gitlab.example.com \
bound_issuer=https://gitlab.example.com
# alternatively without discovery:
# bao write auth/jwt-gitlab/config \
# jwks_url=https://gitlab.example.com/oauth/discovery/keys \
# bound_issuer=https://gitlab.example.com
Tip: If the instance has an internal certificate, the CA belongs in
oidc_discovery_ca_pemorjwks_ca_pem, not in a skip-verify switch.
Save your progress? Sign up for free
Drill 2: Recreating GitLab Claims in the Lab
A GitLab JWT for a deploy job on a protected main with a
protected environment. The values come from the GitLab docs; boolean
claims are strings there.
cp ../tag10/{mint-jwt.sh,ci-issuer.key,ci-issuer.pub} .
cat > gitlab-claims.json <<'EOF'
{
"iss": "https://gitlab.lab.example", "aud": "https://openbao.lab.example",
"sub": "project_path:acme/shop:ref_type:branch:ref:main",
"namespace_id": "7", "namespace_path": "acme",
"project_id": "42", "project_path": "acme/shop",
"user_login": "zachmann", "pipeline_id": "1234", "pipeline_source": "push",
"job_id": "5678", "ref": "main", "ref_type": "branch", "ref_path": "refs/heads/main",
"ref_protected": "true", "environment": "production",
"environment_protected": "true", "deployment_tier": "production",
"runner_environment": "self-hosted"
}
EOF
export BASE=gitlab-claims.json
claims() { jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/")
| @base64d | fromjson'; }
./mint-jwt.sh | claims | jq '{iss, sub, ref, ref_protected, environment}'Expected:
{
"iss": "https://gitlab.lab.example",
"sub": "project_path:acme/shop:ref_type:branch:ref:main",
"ref": "main",
"ref_protected": "true",
"environment": "production"
}
Note the differences from GitHub: ref here is just
main; the full path is in ref_path. The
default sub is
project_path:<group>/<project>:ref_type:<type>:ref:<ref>.
Save your progress? Sign up for free
Drill 3: Mount jwt-gitlab/ and
Role shop-deploy
bao auth enable -path=jwt-gitlab jwt
bao write auth/jwt-gitlab/config [email protected] \
bound_issuer=https://gitlab.lab.example
bao write auth/jwt-gitlab/role/shop-deploy - <<'EOF'
{
"role_type": "jwt",
"user_claim": "user_login",
"bound_audiences": ["https://openbao.lab.example"],
"bound_claims": {
"project_id": "42",
"ref_protected": "true",
"environment": "production",
"environment_protected": "true"
},
"claim_mappings": {"project_path": "project_path", "pipeline_id": "pipeline_id",
"ref": "ref"},
"token_policies": ["ci-deploy"],
"token_ttl": "5m",
"token_explicit_max_ttl": "10m"
}
EOF
BAO_TOKEN= bao write auth/jwt-gitlab/login role=shop-deploy jwt="$(./mint-jwt.sh)"Expected:
Success! Enabled jwt auth method at: jwt-gitlab/
Success! Data written to: auth/jwt-gitlab/config
Success! Data written to: auth/jwt-gitlab/role/shop-deploy
Key Value
--- -----
token s.aQo7Yf5suEYOmKh7QQ3SaF8q
token_accessor 8F8MBOirhVnYLHzhtKQ0lev9
token_duration 5m
token_renewable true
token_policies ["ci-deploy" "default"]
identity_policies []
policies ["ci-deploy" "default"]
token_meta_pipeline_id 1234
token_meta_project_path acme/shop
token_meta_ref main
token_meta_role shop-deploy
Negative tests: unprotected branch, wrong environment, foreign project.
for a in ref_protected=false environment=staging project_id=43; do
echo "== $a"
BAO_TOKEN= bao write auth/jwt-gitlab/login role=shop-deploy \
jwt="$(./mint-jwt.sh $a)" 2>&1 | tail -1
doneExpected:
== ref_protected=false
* error validating claims: claim "ref_protected" does not match any associated bound
claim values
== environment=staging
* error validating claims: claim "environment" does not match any associated bound
claim values
== project_id=43
* error validating claims: claim "project_id" does not match any associated bound
claim values
Why project_id instead of project_path?
Paths become free when a project moves, and could be reassigned. Without
a project or namespace binding, every project on the instance would get
into the role.
Save your progress? Sign up for free
Drill 4: Variant A – secrets:
with vault: (Premium)
The runner fetches the secret before the script. Configuration via CI/CD variables in the project (not executed, checked against the GitLab docs):
cat > gitlab-ci-premium.yml <<'EOF'
variables:
VAULT_SERVER_URL: https://openbao.example.com
VAULT_AUTH_PATH: jwt-gitlab # the default would be "jwt"
VAULT_AUTH_ROLE: shop-deploy
deploy:
stage: deploy
environment: production
rules:
- if: $CI_COMMIT_BRANCH == "main"
id_tokens:
OPENBAO_ID_TOKEN:
aud: https://openbao.lab.example # = bound_audiences of the role (Drill 3)
secrets:
REGISTRY_PASSWORD:
vault: ci/deploy/registry_password@secret # KV v2: secret/data/ci/deploy
token: $OPENBAO_ID_TOKEN
KUBE_TOKEN:
vault:
engine:
name: kv-v2
path: secret
path: ci/deploy
field: kubeconfig_token
file: false
token: $OPENBAO_ID_TOKEN
script:
- docker login registry.example.com -u ci --password-stdin < "$REGISTRY_PASSWORD"
EOFThe aud must match the bound_audiences of
the role shop-deploy exactly, here the lab value.
https://openbao.example.com is only a placeholder for your
OpenBao address. In production you choose both to match (Enterprise
Note).
Without file: false, $REGISTRY_PASSWORD is
a file path, hence < "$REGISTRY_PASSWORD". That is the
safer default: the value does not show up in the process
environment.
Warning: GitLab documents the integration for HashiCorp Vault. The runner speaks the Vault HTTP API; against OpenBao this has not been tested live in the lab. Verify it in your environment before relying on it.
Save your progress? Sign up for free
Drill 5: Variant B – bao in the Job
Image
Works in every edition. The official image has a server entrypoint,
hence entrypoint: [""]. jq and
curl are not included; bao is enough.
cat > .gitlab-ci.yml <<'EOF'
deploy:
stage: deploy
image:
name: quay.io/openbao/openbao:2.7.1
entrypoint: [""]
environment: production
rules:
- if: $CI_COMMIT_BRANCH == "main"
id_tokens:
OPENBAO_ID_TOKEN:
aud: https://openbao.lab.example # = bound_audiences of the role (Drill 3)
variables:
BAO_ADDR: https://openbao.example.com
script:
- ./ci/bao-secrets.sh
EOF
mkdir -p ci
cat > ci/bao-secrets.sh <<'EOF'
#!/bin/sh
# GitLab job: redeem the ID token at OpenBao, store the secret as a file, revoke the token
set -eu
BAO_TOKEN=$(bao write -field=token auth/jwt-gitlab/login \
role=shop-deploy jwt="$OPENBAO_ID_TOKEN")
export BAO_TOKEN
umask 077
bao kv get -field=registry_password secret/ci/deploy > "${TMPDIR:-/tmp}/registry-pw"
echo "✔ Secret als Datei abgelegt"
bao token revoke -self >/dev/null && echo "✔ OpenBao-Token widerrufen"
EOF
chmod +x ci/bao-secrets.shYou try out the script locally with a minted GitLab JWT:
mkdir -p job-tmp
env -u BAO_TOKEN TMPDIR=$PWD/job-tmp OPENBAO_ID_TOKEN="$(./mint-jwt.sh)" \
./ci/bao-secrets.sh
ls -l job-tmp | awk 'NR>1 {print $1, $NF}'; cat job-tmp/registry-pw; echoExpected:
✔ Secret als Datei abgelegt
✔ OpenBao-Token widerrufen
-rw------- registry-pw
lab-reg-pw
GitLab only masks variables defined as “masked”. GitLab knows nothing
about values the script fetches itself. Hence a file instead of
echo, and never set -x.
Save your progress? Sign up for free
Drill 6: Jenkins with AppRole and Wrapping
The Jenkins controller holds two credentials: the role ID and a
short-lived orchestrator token with the policy
approle-issuer (Day 10). Per build, the agent gets only a
wrapped, single-use secret ID.
cat > ci/bao-login.sh <<'EOF'
#!/usr/bin/env bash
# Jenkins agent: fetch the secret ID wrapped, unwrap it, log in via AppRole.
# Expects ROLE_ID and ISSUER_TOKEN (from withCredentials). Loaded via "source".
set -euo pipefail
WRAP=$(BAO_TOKEN=$ISSUER_TOKEN bao write -wrap-ttl=60s -field=wrapping_token \
-f auth/approle/role/jenkins-deploy/secret-id)
path=$(BAO_TOKEN=$ISSUER_TOKEN bao write -field=creation_path sys/wrapping/lookup \
token="$WRAP")
[ "$path" = auth/approle/role/jenkins-deploy/secret-id ] \
|| { echo "✘ unerwarteter creation_path: $path" >&2; exit 1; }
SECRET_ID=$(BAO_TOKEN=$WRAP bao unwrap -field=secret_id)
BAO_TOKEN=$(BAO_TOKEN= bao write -field=token auth/approle/login \
role_id="$ROLE_ID" secret_id="$SECRET_ID")
export BAO_TOKEN
unset SECRET_ID WRAP
EOF
export ROLE_ID=$(bao read -field=role_id auth/approle/role/jenkins-deploy/role-id)
export ISSUER_TOKEN=$(bao token create -policy=approle-issuer -ttl=1h -field=token)
( source ci/bao-login.sh
bao token lookup -format=json | jq -c '.data | {meta, policies, ttl}'
bao kv get -field=registry_password secret/ci/deploy; echo
bao token revoke -self )Expected:
{"meta":{"role_name":"jenkins-deploy"},"policies":["ci-deploy","default"],"ttl":599}
lab-reg-pw
Success! Revoked token (if it existed)
The matching Jenkinsfile (not executed). Single quotes
in the sh step, so that Groovy does not interpolate any
secrets:
pipeline {
agent { label 'linux' }
environment {
BAO_ADDR = 'https://openbao.example.com'
}
stages {
stage('Deploy') {
steps {
withCredentials([
string(credentialsId: 'openbao-role-id', variable: 'ROLE_ID'),
string(credentialsId: 'openbao-issuer-token', variable: 'ISSUER_TOKEN')
]) {
sh '''#!/bin/bash
set +x
source ci/bao-login.sh
bao kv get -field=registry_password secret/ci/deploy \
| docker login registry.example.com -u ci --password-stdin
bao token revoke -self
'''
}
}
}
}
}Warning: Otherwise Jenkins runs
shwith/bin/sh. Forsourceandpipefail,#!/bin/bashmust come directly after the quotes, without a line break.
Save your progress? Sign up for free
Drill 7: Alternative – the HashiCorp Vault Plugin
The Jenkins plugin hashicorp-vault-plugin handles login
and reading itself. A credential of the type “Vault App Role Credential”
with role ID, secret ID and path approle (not executed,
checked against the plugin README):
def secrets = [
[path: 'secret/ci/deploy', engineVersion: 2, secretValues: [
[envVar: 'REGISTRY_PASSWORD', vaultKey: 'registry_password']]]
]
def configuration = [vaultUrl: 'https://openbao.example.com',
vaultCredentialId: 'openbao-approle',
engineVersion: 2]
node('linux') {
withVault([configuration: configuration, vaultSecrets: secrets]) {
sh '''echo "$REGISTRY_PASSWORD" \
| docker login registry.example.com -u ci --password-stdin'''
}
}The plugin speaks the Vault HTTP API and should therefore work with
OpenBao; it has not been tested in the lab. Downside: the secret ID sits
permanently in the credential store, and wrapping and single use are
lost. In that case, set at least secret_id_ttl and
secret_id_bound_cidrs, and rotate via a job.
Save your progress? Sign up for free
Checkpoint
cat > check.sh <<'EOF'
#!/usr/bin/env bash
cd ~/secrets-lab/tag12
export BAO_ADDR="${BAO_ADDR:-http://127.0.0.1:8200}" BASE=gitlab-claims.json
gl() { BAO_TOKEN= bao write -field=token auth/jwt-gitlab/login role=shop-deploy \
jwt="$(./mint-jwt.sh "$@")" >/dev/null 2>&1; }
gl && echo "✔ GitLab-Deploy-Job kommt rein" || echo "✘ GitLab-Login"
gl ref_protected=false && echo "✘ ungeschützter Branch kommt rein" \
|| echo "✔ ungeschützter Branch abgewiesen"
gl aud=https://gitlab.lab.example && echo "✘ falsche aud akzeptiert" \
|| echo "✔ falsche aud abgewiesen"
export ROLE_ID=$(BAO_TOKEN=root bao read -field=role_id \
auth/approle/role/jenkins-deploy/role-id)
export ISSUER_TOKEN=$(BAO_TOKEN=root bao token create -policy=approle-issuer \
-ttl=5m -field=token)
( source ci/bao-login.sh && bao kv get -field=registry_password secret/ci/deploy \
| grep -q lab-reg-pw ) && echo "✔ Jenkins-AppRole-Flow" || echo "✘ AppRole-Flow"
EOF
bash check.shExpected:
✔ GitLab-Deploy-Job kommt rein
✔ ungeschützter Branch abgewiesen
✔ falsche aud abgewiesen
✔ Jenkins-AppRole-Flow
Challenge
Releases are built from protected v* tags without an
environment. Create a role shop-release that accepts only
protected tags of project 42.
Hint: bound_claims_type=glob and
ref_type=tag; the environment claim is missing
in such jobs, so do not bind it.
Solution
export BAO_TOKEN=root
bao write auth/jwt-gitlab/role/shop-release - <<'EOF'
{
"role_type": "jwt", "user_claim": "user_login",
"bound_audiences": ["https://openbao.lab.example"],
"bound_claims_type": "glob",
"bound_claims": {"project_id": "42", "ref_type": "tag", "ref": "v*",
"ref_protected": "true"},
"token_policies": ["ci-deploy"], "token_ttl": "5m"
}
EOF
TAG="ref_type=tag ref=v1.4.0 environment= environment_protected="
for extra in "" "ref_protected=false" "ref_type=branch ref=v-test"; do
printf '%-30s ' "${extra:-geschützter Tag}"
BAO_TOKEN= bao write -field=token_policies auth/jwt-gitlab/login role=shop-release \
jwt="$(./mint-jwt.sh $TAG $extra)" 2>&1 | tail -1; echo
doneExpected:
geschützter Tag [ci-deploy default]
ref_protected=false * error validating claims: claim "ref_protected" does
not match any associated bound claim values
ref_type=branch ref=v-test * error validating claims: claim "ref_type" does not
match any associated bound claim values
Save your progress? Sign up for free
Enterprise Note
- Choose a unique
audper target (production e.g.https://openbao.example.com, identical inid_tokensandbound_audiences) and request per job only theid_tokensit needs. - Always bind
project_id/namespace_id; if a project path is reused, GitLab blocks issuance until you adjustci_id_token_sub_claim_componentswithproject_id. Then update roles withbound_subjectaccordingly. - Production deploys only via protected branches/tags and protected
environments; bind both as claims, not just in
.gitlab-ci.ymlviarules:. - Jenkins: orchestrator token periodic and narrow
(
approle-issuer), agents in fixed networks withsecret_id_bound_cidrs/token_bound_cidrs; move to OIDC in the medium term. - Pin runner images with
bao(digest) and scan them yourself; distinguish self-hosted runners viarunner_environment.