GitLab Incident: OIDC Token Subject Claim Length Limitation

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Release notes

GitLab CI/CD OIDC tokens to support configurable subject claim formats to ensure compatibility with external identity providers that have character length restrictions, such as Google Cloud's Workload Identity Federation (127-byte limit). This enhancement enables seamless keyless authentication across all branch naming conventions and eliminates the need for less secure service account keys.

Problem to solve

GitLab CI/CD OIDC tokens contain subject claims that can exceed external identity providers' byte limits when branch names are long. Specifically, Google Cloud's Workload Identity Federation has a 127-byte limit for attribute mapping, but GitLab's current token format project_path:<namespace>/<project>:ref_type:<type>:ref:<branch_name> can generate subjects exceeding this limit.

Example of failing token (132 bytes):

project_path:media/retail-media-portal/deployments-test/nginx-demo:ref_type:branch:ref:develop/RMP-102762/GCP-Gitlab-WIF-integration

Example of working token (115 bytes):

project_path:media/retail-media-portal/deployments-test/nginx-demo:ref_type:branch:ref:feature/RMP-123/test-wif

This creates an inconsistent and unpredictable experience where some branches fail authentication while others succeed, solely based on branch name length. Teams are forced to either:

  1. Artificially limit branch naming conventions (impacting developer workflow)
  2. Fall back to less secure service account key-based authentication
  3. Abandon keyless authentication adoption entirely

This issue directly impacts organizations adopting zero-trust security models and modern cloud-native authentication patterns.

Proposal

  1. Acceptance for > 127 bytes tokens
  2. Add a configuration option (at project, group, or instance level) allowing administrators to customize the OIDC token subject claim format. Options could include:
  • Compact format: project_id:<id>:ref_type:<type>:ref:<branch> (using numeric project ID instead of full path)
  • Hash format: project_path:<namespace>/<project>:ref_type:<type>:ref_hash:<sha256_of_branch>
  • Custom format: Allow custom templates with available variables

Intended users

Developers

Feature Usage Metrics

  1. Configuration Adoption
    • oidc_subject_format_configured - Counter for projects/groups with custom subject format configured
    • oidc_subject_format_type - Distribution of format types chosen (compact, hash, custom)
  2. Token Generation
    • oidc_token_subject_length - Histogram of subject claim lengths
    • oidc_token_subject_truncated - Counter for tokens where truncation occurred
    • oidc_token_validation_warnings - Counter for pre-flight validation warnings issued
  3. Authentication Success
    • oidc_authentication_success_rate - Success rate before/after feature adoption
    • oidc_authentication_failure_by_reason - Track failures due to subject length issues
  4. User Behavior
    • Track branch name length distribution in projects using OIDC
    • Monitor reduction in service account key usage after feature adoption

Does this feature require an audit event?

No

Edited by 🤖 GitLab Bot 🤖