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, which is a signed JSON Web Token (JWT) containing 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 (also known as asserted claims) are permitted to perform the actions. If the OIDC token's asserted claims comply with 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 Package Registries, with OIDC policies that only permit Buildkite Agent interactions from specific Buildkite organizations, pipelines, agents, and other metadata associated with the pipeline's job.

A Buildkite OIDC token can be issued by a Buildkite Agent, asserting claims about the slugs of the pipeline it is building and organization that contains this pipeline, the ID of the job that created the token, as well as other claims, such as the name of the branch used in the build, the SHA of the commit that triggered the build, 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 comply with the service's OIDC policy, the token is rejected 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 can then be 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.