ID Tokens, OIDC Workload Identity, Cloud Federation, Vault Authentication, and Secretless Deployments: Configuration, Design Choices, and Tradeoffs

1. Start with authorization invariants, not provider syntax

A provider-specific JSON policy is implementation detail. First define the invariant in plain language: “Only jobs running in project 42001, from protected main, targeting staging, may assume role staging-writer, and that role may mutate only the staging namespace.” Then encode the same invariant using the provider's supported claims and policy language.

This keeps cloud migration possible. AWS, Azure, GCP and Vault use different federation mechanics, but they can all enforce a narrow trust relationship.

2. Static secret versus OIDC federation

Federation is preferable where supported, but “secretless” describes the absence of a stored long-lived provider secret in GitLab. The provider still issues a credential after exchange, and that temporary credential must be protected.

3. Broad project trust versus ref/environment-specific trust

Too broad:
  issuer = GitLab
  subject starts with project_path:academy/app
  => every branch may assume deployment role

Narrower invariant:
  issuer = GitLab
  audience = deployment STS
  project/job_project ID = expected project
  ref = main
  ref_protected = true
  environment = production
  deployment_tier = production
  => only the intended deployment context can exchange

Do not assume every provider supports every GitLab custom claim in exactly the same way. GitLab's current docs explicitly note that AWS on GitLab.com exposes additional GitLab condition keys, whereas self-managed/Dedicated AWS federation supports only sub as an AWS condition key. Design to the actual provider/offering capability and document the limitation.

4. One broad audience versus service-specific audiences

deploy_cloud:
  id_tokens:
    CLOUD_ID_TOKEN:
      aud: https://sts.cloud.example
  script:
    - ./cloud-exchange "$CLOUD_ID_TOKEN"

read_vault:
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  script:
    - ./vault-exchange "$VAULT_ID_TOKEN"

Separate audiences make accidental token reuse visible. GitLab also permits an audience array, but granting one token multiple relying parties increases the surface in which that assertion might be accepted. Use multiple audiences only when the relying-party design truly requires it.

5. Direct provider federation versus Vault broker

Vault can reduce provider-specific logic in application pipelines, but it is not automatically safer. A broad Vault role that returns powerful credentials simply centralizes the same authorization flaw.

6. Subject design and stable identifiers

The default sub is project-path/ref-oriented. Current GitLab also offers stable project/namespace IDs and job-project variants. Prefer trust rules that cannot silently follow a renamed group/project into unintended authority. On providers with only sub support, keep the subject exact and pair it with branch/tag protections and careful project administration.

7. Environments make deployment intent observable

If a job declares an environment, current ID tokens can carry environment name, protection state, deployment tier and action. This lets a provider distinguish a staging job from a production job even when both run from the same project/ref. That is useful defense in depth, but only if the environment declaration itself is governed and the provider checks it.

8. Token lifetime versus job timeout

Because ID-token expiry follows the job timeout when specified, very long deployment timeouts also lengthen the assertion lifetime. Set realistic job timeouts and design provider credential sessions separately. Do not increase job timeouts merely to “fix” an exchange that fails for an unrelated audience or trust-condition problem.

9. Keep repository, GitLab, runner and provider state distinct

10. Worked design: production deployment

Suppose a team deploys one artifact to staging and production. The production role may write only one namespace. The project is private and the production environment is protected. A safe design can require: exact job project ID, main, protected ref, production environment/tier, a production-only audience, and a provider role whose permissions cover only the production namespace. The pipeline rule and protected environment control reduce accidental job creation; the provider policy independently limits credential issuance.

11. Tier/offering and trust prerequisites

• ID tokens: Free/Premium/Ultimate on GitLab.com, Self-Managed, Dedicated.
• Native GitLab external-secrets/Vault keyword flows: currently Premium/Ultimate.
• AWS/Azure/GCP federation: GitLab side is available on Free; the provider account and IAM privileges needed to configure federation are external prerequisites.
• Self-managed GitLab: the relying party generally needs reachable OIDC discovery/signing metadata; do not weaken TLS to work around reachability.

12. Migration from static keys

Migrate one role/action at a time. First establish federation and prove allowed + denied cases. Then run read-only or no-op operations. Next grant the narrow mutation. Only after the federated path is verified should you revoke the old long-lived key. Preserve evidence of the revocation and ensure rollback does not mean silently reintroducing a forgotten administrator key.

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. GitLab documents explicit id_tokens as available on Free, Premium, and Ultimate across GitLab.com, Self-Managed, and Dedicated. CI_JOB_JWT/CI_JOB_JWT_V2 were removed in GitLab 17.0; use explicit ID tokens instead. ID tokens are RS256-signed. Their expiry is the job timeout when one is specified, otherwise five minutes. Current custom claims include project/namespace identity, job identity, ref/ref protection, pipeline source, runner identity, source SHA, CI configuration identity, and—when the job declares an environment—environment name/protection/tier/action. GitLab recommends stable IDs such as project/namespace IDs in trust policy conditions where the target provider supports them. Native secrets:vault integration is Premium/Ultimate, while ID-token federation itself is Free. Provider claim support is not uniform. Always verify the exact provider/offering guidance before translating a conceptual condition into AWS IAM, Entra federated credentials, Google CEL/attribute conditions, or Vault bound claims.

• OIDC authentication using ID tokens — official reference.
• Connect to cloud services — official reference.
• CI/CD YAML — id_tokens — official reference.
• AWS OIDC tutorial — official reference.
• Azure OIDC tutorial — official reference.
• Google Cloud workload identity federation — official reference.
• Use HashiCorp Vault secrets — official reference.
• Vault authentication tutorial — official reference.
• External secrets in CI/CD — official reference.
• GitLab deprecations and removals — official reference.
• OpenID Connect Core 1.0 — official reference.
• RFC 7519 — JSON Web Token — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.