buildkite-agent oidc

The Buildkite Agent's oidc command allows you to request an OIDC token representing the current job. These tokens can be exchanged with federated systems like AWS.

See the OpenID Connect Core documentation for more information about how OIDC tokens are constructed and how to extract and use claims.

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