3. Auth & identity: variables, OIDC, and keyless cloud access¶
Why this matters¶
The most common pipeline security failure is a long-lived credential checked into CI settings — or worse, into the repo. Modern pipelines authenticate with identity, not secrets: short-lived tokens the platform issues per job. Understand both layers and you'll never need a service-account JSON key again.
Layer 1: CI/CD variables¶
Settings → CI/CD → Variables. Three dimensions matter:
| Flag | Effect |
|---|---|
| Masked | redacted in job logs (***); requires a log-safe value format |
| Protected | only exposed to pipelines on protected branches/tags — your deploy:prod credential should be both |
| File vs Variable | File type writes the value to a temp file and sets the var to its path — ideal for kubeconfigs/JSON |
| Scope | project vs group vs instance — group vars let all projects inherit shared config |
This repo needs exactly one variable to deploy:
.gitlab/ci/deploy.yml decodes it in before_script. Nothing credential
shaped ever appears in the repo or the logs.
Layer 2: OIDC federation (the keyless pattern)¶
GitLab can issue each job a signed JWT (id_tokens) that a cloud provider
trusts — the job exchanges it for a short-lived cloud credential. No stored
key to leak or rotate.
gcp-auth:
id_tokens:
GCP_AUD: # claim baked into the token
aud: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
script:
# exchange the JWT for a federated token, then docker/helm/gcloud auth
- gcloud iam workload-identity-pools create-cred-config ...
GCP twin: this is Workload Identity Federation — the pipeline-side mirror of the in-cluster Workload Identity already used in
terraform-concepts/acme-sampleapp-multirepo(KSA ↔ GSA binding). Same principle: an identity you are, not a key you hold.
The hierarchy, memorized¶
best → OIDC id_token → short-lived federated cred (nothing stored)
better → masked+protected CI var holding a scoped cred (rotated regularly)
ok → CI variable (never logged, low privilege)
never → secrets in the repo, echo'd in logs, or in Docker image layers
GitLab's secret-detection template (added in the security phase) fails pipelines on the bottom row automatically.
Hands-on¶
- Create
KUBECONFIG_DATAas above; rundeploy:dev; search the job log forkube— confirm nothing sensitive printed. - Unmask it (temporary!) and re-run — the raw kubeconfig base64 scrolls by. Re-mask. That is the drill.
- Push a branch, run
deploy:prod— the job fails: the variable isn't available outside the protectedmainbranch. That's protected vars doing their job.
Deliberate break & triage¶
- Break 1:
echo $KUBECONFIG_DATA | base64 -din a job on a feature branch → empty output. Protected vars don't leak to unprotected refs. - Break 2: forget
base64 -d(use the var directly as kubeconfig) →error: couldn't get version/kind; json parse error. The encode/decode round-trip exists to dodge newline-mangling in CI vars. - Break 3: commit a
kubeconfigfile to the repo → now imagine it ingit logforever. Rotate it, scrub it, add the rule to.gitignore+ a gitleaks job (Phase 2).
Verify¶
- Deploy works with zero secrets in the repo
- You can explain masked vs protected vs file-type in one line each
- You can sketch the OIDC trust flow (job → JWT → cloud cred → API call)