Text of docs.gitlab.com › ci › secrets › id_token_authentication as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

OpenID Connect (OIDC) Authentication Using ID Tokens | GitLab Docs

/ OpenID Connect (OIDC) Authentication Using ID Tokens Tier : Free, Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated ID tokens are JSON web tokens (JWT) generated by GitLab CI/CD. CI/CD jobs can use ID tokens for OIDC authentication with third-party services, including: Secrets providers Cloud services For example, the flow for using ID tokens to authenticate with HashiCorp Vault is summarized by this diagram: sequenceDiagram participant GitLab as GitLab CI/CD participant Runner as GitLab Runner participant Vault as HashiCorp Vault GitLab->>Runner: Generates an ID token (JWT) for the CI/CD job Runner->>Vault: Runner authenticates with HashiCorp Vault using the token Vault->>Vault: HashiCorp Vault verifies the token Vault->>Vault: HashiCorp Vault checks bounded claims and attaches policies Vault->>Runner: HashiCorp Vault returns the token Runner->>Vault: Runner requests secrets from HashiCorp Vault Vault->>Runner: Returns secrets ID tokens are also used by the secrets keyword.

GitLab Duo Agent Platform flows and external agents can also declare id_tokens to authenticate with third-party services during execution. Configure ID tokens in a CI/CD job To use ID tokens, configure a CI/CD job with the id_tokens keyword. Then you can use the token in a script , before_script , or after_script section. For example: yaml job_with_id_tokens : id_tokens : FIRST_ID_TOKEN : aud : https://first.service.com SECOND_ID_TOKEN : aud : https://second.service.com script : - first-service-authentication-script.sh $FIRST_ID_TOKEN - second-service-authentication-script.sh $SECOND_ID_TOKEN In this example, the two tokens have different aud claims.

Third party services can be configured to reject tokens that do not have an aud claim matching their bound audience. Use this functionality to reduce the number of services with which a token can authenticate. This reduces the severity of having a token compromised. Token payload The following standard claims are included in each ID token: Field Description iss Issuer of the token, which is the domain of the GitLab instance (“issuer” claim). sub Subject of the token (“subject” claim).

Defaults to project_path:{group}/{project}:ref_type:{type}:ref:{branch_name} . Can be configured for the project with the projects API . The sub claim can include additional fields such as ref_protected , and environment-related fields such as environment_protected and deployment_tier when jobs specify an environment. Introduced in GitLab 18.7. aud Intended audience for the token (“audience” claim). Specified in the ID tokens configuration.

The domain of the GitLab instance by default. exp The expiration time (“expiration time” claim). nbf The time after which the token becomes valid (“not before” claim). iat The time the JWT was issued (“issued at” claim). jti Unique identifier for the token (“JWT ID” claim). The token also includes custom claims provided by GitLab: Field When Description project_id Always ID of the project running the job.

In a merge request pipeline, this is the ID of the source project. project_path Always Path of the project running the job. In a merge request pipeline, this is the path of the source project. namespace_id Always Namespace ID of the project running the job. In a merge request pipeline, this is the namespace ID of the source project. namespace_path Always Namespace path of the project running the job. In a merge request pipeline, this is the namespace path of the source project. user_id Always ID of the user executing the job. user_login Always Username of the user executing the job. user_email Always Email of the user executing the job. user_access_level Always Access level of the user executing the job. job_project_id Always ID of the project running the job.

Use this to scope to the project by ID. Introduced in GitLab 18.4. job_project_path Always Path of the project running the job. Use this to scope to the project by path. Introduced in GitLab 18.4. job_namespace_id Always Namespace ID of the project running the job. Use this to scope to group or user level namespace by ID. Introduced in GitLab 18.4. job_namespace_path Always Namespace path of the project running the job.

Use this to scope to group or user level namespace by path. Introduced in GitLab 18.4. source_project_id Always ID of the project that contains the source code. In a merge request pipeline, this is the ID of the source project of the merge request. Introduced in GitLab 19.5. source_project_path Always Path of the project that contains the source code. In a merge request pipeline, this is the path of the source project of the merge request.

Introduced in GitLab 19.5. source_namespace_id Always Namespace ID of the project that contains the source code. In a merge request pipeline, this is the namespace ID of the source project of the merge request. Introduced in GitLab 19.5. source_namespace_path Always Namespace path of the project that contains the source code. In a merge request pipeline, this is the namespace path of the source project of the merge request.

Introduced in GitLab 19.5. user_identities User Preference setting List of the user’s external identities. pipeline_id Always ID of the pipeline. pipeline_source Always Pipeline source . job_id Always ID of the job. ref Always Git ref for the job. In a merge request pipeline, this is the source branch ref. ref_type Always Git ref type, either branch or tag . ref_path Always Fully qualified ref for the job. For example, refs/heads/main .

In a merge request pipeline, this is the source branch ref path. ref_protected Always true if the Git ref is protected, false otherwise. groups_direct User is a direct member of 0 to 200 groups The paths of the user’s direct membership groups. Omitted if the user is a direct member of more than 200 groups. Feature flag ci_jwt_groups_direct added in GitLab 17.3. Disabled by default. environment Job specifies an environment Environment this job deploys to. environment_protected Job specifies an environment true if deployed environment is protected, false otherwise. deployment_tier Job specifies an environment Deployment tier of the environment the job specifies. environment_action Job specifies an environment Environment action ( environment:action ) specified in the job. runner_id Always ID of the runner executing the job. runner_environment Always The type of runner used by the job.

Can be either gitlab-hosted or self-hosted . sha Always The commit SHA for the job. ci_config_ref_uri Always The ref path to the top-level pipeline definition, for example, gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main . This claim is null unless the pipeline definition is located in the same project. ci_config_sha Always Git commit SHA for the ci_config_ref_uri . This claim is null unless the pipeline definition is located in the same project. project_visibility Always The visibility of the project where the pipeline is running.

Can be internal , private , or public . job_source Always Job source . Introduced in GitLab 18.9. job_config Job triggered by a policy Metadata about the origin of the job. For policy jobs, includes sha and url for the policy configuration. Introduced in GitLab 18.9. target_audience Token specifies a target audience Service the token exchange API issues a credential for. Specified with id_tokens:target_audience . Introduced in GitLab 19.7. json { "namespace_id" : "72" , "namespace_path" : "my-group" , "project_id" : "20" , "project_path" : "my-group/my-project" , "user_id" : "1" , "user_login" : "sample-user" , "user_email" : "sample-user@example.com" , "user_identities" : [ { "provider" : "github" , "extern_uid" : "2435223452345" }, { "provider" : "bitbucket" , "extern_uid" : "john.smith" } ], "pipeline_id" : "574" , "pipeline_source" : "push" , "job_id" : "302" , "ref" : "feature-branch-1" , "ref_type" : "branch" , "ref_path" : "refs/heads/feature-branch-1" , "re

The rest of this page is on the live site.