buildkite-agent oidc

The Buildkite Agent's oidc command allows you to request an OpenID Connect (OIDC) token from Buildkite, representing the current pipeline and its job. These tokens can be exchanged for specific roles on federated systems like AWS, GCP, Azure and many others.

Refer to the following documentation for more information:

The What is OpenID Connect overview on the OpenID web site for more details about how OIDC works.
The OpenID Connect Core documentation for more information about how OIDC tokens are constructed and how to extract and use claims.

Learn more about how to restrict your Buildkite Agents' access to deployment environments like AWS, from the OIDC in Buildkite Pipelines and with AWS documentation pages, as well as the Buildkite Packages documentation page.

Request OIDC token

Usage

buildkite-agent oidc request-token [options...]

Description

Requests and prints an OIDC token from Buildkite that claims the Job ID (amongst other things) and the specified audience. If no audience is specified, the endpoint's default audience will be claimed.

Example

$ buildkite-agent oidc request-token --audience sts.amazonaws.com

Requests and prints an OIDC token from Buildkite that claims the Job ID (amongst other things) and the audience "sts.amazonaws.com".

Options

`--audience value` #	The audience that will consume the OIDC token. The API will choose a default audience if it is omitted.
`--lifetime value` #	The time (in seconds) the OIDC token will be valid for before expiry. Must be a non-negative integer. If the flag is omitted or set to 0, the API will choose a default finite lifetime. (default: 0)
`--job value` #	Buildkite Job Id to claim in the OIDC token Environment variable: `$BUILDKITE_JOB_ID`
`--claim value` #	Claims to add to the OIDC token Environment variable: `$BUILDKITE_OIDC_TOKEN_CLAIMS`
`--agent-access-token value` #	The access token used to identify the agent Environment variable: `$BUILDKITE_AGENT_ACCESS_TOKEN`
`--endpoint value` #	The Agent API endpoint (default: "`https://agent.buildkite.com/v3`") Environment variable: `$BUILDKITE_AGENT_ENDPOINT`
`--no-http2` #	Disable HTTP2 when communicating with the Agent API. Environment variable: `$BUILDKITE_NO_HTTP2`
`--debug-http` #	Enable HTTP debug mode, which dumps all request and response bodies to the log Environment variable: `$BUILDKITE_AGENT_DEBUG_HTTP`
`--no-color` #	Don't show colors in logging Environment variable: `$BUILDKITE_AGENT_NO_COLOR`
`--debug` #	Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` Environment variable: `$BUILDKITE_AGENT_DEBUG`
`--log-level value` #	Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") Environment variable: `$BUILDKITE_AGENT_LOG_LEVEL`
`--experiment value` #	Enable experimental features within the buildkite-agent Environment variable: `$BUILDKITE_AGENT_EXPERIMENT`
`--profile value` #	Enable a profiling mode, either cpu, memory, mutex or block Environment variable: `$BUILDKITE_AGENT_PROFILE`

OIDC URLs

If using a plugin, such as the AWS assume-role-with-web-identity plugin, you'll need to provide an OpenID provider URL. You should set the provider URL to: https://agent.buildkite.com.

For specific endpoints for OpenID or JWKS, use:

OpenID Connect Discovery URL: https://agent.buildkite.com/.well-known/openid-configuration
JWKS URI: https://agent.buildkite.com/.well-known/jwks

Claims

Claim	Description
`iss`	Issuer Identifies the entity that issued the JWT. Example: `https://agent.buildkite.com`
`sub`	Subject Identifies the subject of the JWT, typically representing the user or entity being authenticated. Format: `organization:ORGANIZATION_SLUG:pipeline:PIPELINE_SLUG:ref:REF: commit:BUILD_COMMIT:step:STEP_KEY`. If the build has a tag, `REF` is `refs/tags/TAG`. Otherwise, `REF` is `refs/heads/BRANCH`. Example:`organization:acme-inc:pipeline:super-duper-app:ref:refs/heads/main:commit:9f3182061f1e2cca4702c368cbc039b7dc9d4485:step:build`
`aud`	Audience Identifies the intended audience for the JWT. Defaults to `https://buildkite.com/ORGANIZATION_SLUG` but can be overridden using the `--audience` flag
`exp`	Expiration time Specifies the expiration time of the JWT, after which the token is no longer valid. Defaults to 5 minutes in the future at generation, but can be overridden using the `--lifetime` flag. Example: `1669015898`
`nbf`	Not before Specifies the time before which the JWT must not be accepted for processing. Set to the current timestamp at generation. Example: `1669014898`
`iat`	Issued at Specifies the time at which the JWT was issued. Set to the current timestamp at generation. Example: `1669014898`
`organization_slug`	The organization's slug. Example: `acme-inc`
`pipeline_slug`	The pipeline's slug. Example: `super-duper-app`
`build_number`	The build number. Example: `1`
`build_branch`	The repository branch used in the build. Example: `main`
`build_tag`	The tag of the build if enabled in Buildkite. This claim is only included if the tag is set. Example: `1`
`build_commit`	The SHA commit from the repository. Example: `9f3182061f1e2cca4702c368cbc039b7dc9d4485`
`step_key`	The `key` attribute of the step from the pipeline. If the key is not set for the step, `nil` is returned. Example: `build_step`
`job_id`	The job UUID. Example: `0184990a-477b-4fa8-9968-496074483cee`
`agent_id`	The agent UUID. Example: `0184990a-4782-42b5-afc1-16715b10b8ff`

Optional claims

Generate these additional claims by adding --claims to the buildkite-agent oidc request-token command.

Claim Description

Claim	Description
`organization_id`	The organization UUID. Example: `0184990a-477b-4fa8-9968-496074483k77`
`pipeline_id`	The pipeline UUID. Example: `0184990a-4782-42b5-afc1-16715b10b1l0`

organization_id

The organization UUID.

Example: 0184990a-477b-4fa8-9968-496074483k77

pipeline_id

The pipeline UUID.

Example: 0184990a-4782-42b5-afc1-16715b10b1l0

Example token contents

OIDC tokens are JSON Web Tokens — JWTs — and the following is a complete example:

{
  "iss": "https://agent.buildkite.com",
  "sub": "organization:acme-inc:pipeline:super-duper-app:ref:refs/heads/main:commit:9f3182061f1e2cca4702c368cbc039b7dc9d4485:step:build",
  "aud": "https://buildkite.com/acme-inc",
  "iat": 1669014898,
  "nbf": 1669014898,
  "exp": 1669015198,
  "organization_slug": "acme-inc",
  "pipeline_slug": "super-duper-app",
  "build_number": 1,
  "build_branch": "main",
  "build_commit": "9f3182061f1e2cca4702c368cbc039b7dc9d4485",
  "step_key": "build",
  "job_id": "0184990a-477b-4fa8-9968-496074483cee",
  "agent_id": "0184990a-4782-42b5-afc1-16715b10b8ff"
}