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:

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:

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
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"
}