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 Package Registries 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 |
--claim value #
|
Claims to add to the OIDC token |
--aws-session-tag value #
|
Add claims as AWS Session Tags |
--agent-access-token value #
|
The access token used to identify the agent |
--endpoint value #
|
The Agent API endpoint (default: " |
--no-http2 #
|
Disable HTTP2 when communicating with the Agent API. |
--debug-http #
|
Enable HTTP debug mode, which dumps all request and response bodies to the log |
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--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") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
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
All of the following claims (with the exception of the aud claim, which is usually overridden by the --audience option) are automatically generated by the Buildkite Agent, and are based on metadata from the pipeline job it is currently building.
| Claim | Description |
|---|---|
iss |
Issuer Identifies the entity that issued the JWT. Example: |
sub |
Subject Identifies the subject of the JWT, typically representing the user or entity being authenticated. Format:
If the build has a tag, Otherwise, Example: |
aud |
Audience Identifies the intended audience for the JWT. Defaults to |
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 Example: |
nbf |
Not before Specifies the time before which the JWT must not be accepted for processing. Set to the current timestamp at generation. Example: |
iat |
Issued at Specifies the time at which the JWT was issued. Set to the current timestamp at generation. Example: |
organization_slug |
The organization's slug. Example: |
pipeline_slug |
The pipeline's slug. Example: |
build_number |
The build number. Example: |
build_branch |
The repository branch used in the build. Example: |
build_tag |
The tag of the build if enabled in Buildkite. This claim is only included if the tag is set. Example: |
build_commit |
The SHA commit from the repository. Example: |
step_key |
The Example: |
job_id |
The job UUID. Example: |
agent_id |
The agent UUID. Example: |
Optional claims
You can generate additional optional claims by adding --claims to the buildkite-agent oidc request-token command. The --claims option can also take multiple values.
For example, this command adds the Buildkite organization's UUID value as a claim to the OIDC token:
$ buildkite-agent oidc request-token ... --claim "organization_id"
This command adds both the Buildkite organization's UUID and pipeline's UUID values in their own additional claims to the OIDC token:
$ buildkite-agent oidc request-token ... --claim "organization_id,pipeline_id"
The following optional claims can be added, whose values are automatically generated by the Buildkite Agent, and are based on the pipeline job it is currently building.
| Claim | Description |
|---|---|
organization_id |
The organization UUID. Example: |
pipeline_id |
The pipeline UUID. Example: |
cluster_id |
The cluster UUID if using clusters. Example: |
cluster_name |
The cluster name if using clusters. Example: |
queue_id |
The cluster queue UUID if using clusters. Example: |
queue_key |
The cluster queue key if using clusters. Example: |
agent_tag:NAME |
An agent tag Example: |
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"
}