OIDC in Buildkite Pipelines

Open ID Connect (OIDC) is an authentication protocol based on the OAuth 2.0 framework. With OIDC, one system or service issues an OIDC token containing signed metadata (or claims) about a user or object. This token can be consumed by another service (which may be offered by a third-party or by the same organization) to authenticate the user or object. An OIDC policy configured on this other service defines which OIDC tokens (based on their claims) are permitted to perform the actions. If the OIDC token's claims match those of the OIDC policy configured in the other service, the token is authenticated and the service issuing the token is permitted to perform its actions on the other service.

You can configure third-party products and services, such as AWS, GCP, Azure and many others, as well as Buildkite products, such as Packages, with OIDC policies that only permit Buildkite Agent interactions from specific Buildkite organizations, pipelines, jobs, and agents, associated with a pipeline's job.

A Buildkite OIDC token is a signed JSON Web Token (JWT) provided by a Buildkite Agent, containing metadata claims about a pipeline and its job, including the pipeline and organization slugs, as well as job-specific data, such as the branch, the commit SHA, the job ID, and the agent ID. Such a token is associated with a Buildkite Agent interaction to perform one or more actions within the third-party service. If the token's claims do not match or comply with the service's OIDC policy, the OIDC token and subsequent pipeline jobs' interactions are rejected.

The Buildkite Agent's oidc command allows you to request an OIDC token from Buildkite containing claims about the pipeline's current job. These tokens are then consumed by federated systems like AWS, and exchanged for authenticated role-based access with specific permissions to interact with your cloud environments.

This section of the Buildkite Docs covers Buildkite's OIDC implementation with other federated systems, such as AWS.