Skip to content
Hands-on IT IT Drills

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 own aud. 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: with vault: (Premium/Ultimate, the runner fetches the secret) or bao in 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-com

Expected:

{
  "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_pem or jwks_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
done

Expected:

== 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"
EOF

The 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.sh

You 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; echo

Expected:

✔ 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 sh with /bin/sh. For source and pipefail, #!/bin/bash must 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.sh

Expected:

✔ 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
done

Expected:

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 aud per target (production e.g. https://openbao.example.com, identical in id_tokens and bound_audiences) and request per job only the id_tokens it needs.
  • Always bind project_id/namespace_id; if a project path is reused, GitLab blocks issuance until you adjust ci_id_token_sub_claim_components with project_id. Then update roles with bound_subject accordingly.
  • Production deploys only via protected branches/tags and protected environments; bind both as claims, not just in .gitlab-ci.yml via rules:.
  • Jenkins: orchestrator token periodic and narrow (approle-issuer), agents in fixed networks with secret_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 via runner_environment.