Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Expanding info on the agent access token & registration token scopes #1709

Closed
wants to merge 5 commits into from
Closed

Expanding info on the agent access token & registration token scopes #1709

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2dc077e
Adds a missing Oxford comma & removes trailing space
karensawrey Aug 18, 2022
8e0e23a
Expand info on the default tokens and session tokens
karensawrey Aug 18, 2022
31e27bb
Token exchange and log security
karensawrey Aug 18, 2022
f2dc14a
Stray typo
karensawrey Aug 18, 2022
2806921
Reworded
karensawrey Aug 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions pages/agent/v3/tokens.md.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,26 @@
# Agent Tokens

The Buildkite Agent requires an agent token to connect to Buildkite and register for work. If you are an admin of your Buildkite organization, you can view the tokens on your [Agents page](https://buildkite.com/organizations/-/agents).
The Buildkite agent requires an agent token to connect to Buildkite and register for work. If you are an admin of your Buildkite organization, you can view the tokens on your [Agents page](https://buildkite.com/organizations/-/agents).

{:toc}

## The default token
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's call this

Agent registration token (default token)


When you create a new organization in Buildkite, a default agent token is created. This token can be used for testing and development, but it's recommended to [create new, specific tokens](#creating-tokens) for each new environment.
When you create a new organization in Buildkite, a default agent token (agent registration token) is created to start an agent. This token but cannot be used with the artifacts or meta-data. While it can be used for testing and development, it's recommended to [create new, specific tokens](#creating-tokens) for each new environment.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This token but cannot be used with the artifacts or meta-data.

this needs more words :-p

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When you create a new organization in Buildkite, a default agent token (agent registration token) is created to start an agent. This token but cannot be used with the artifacts or meta-data. While it can be used for testing and development, it's recommended to [create new, specific tokens](#creating-tokens) for each new environment.
When you create a new organization in Buildkite, a default agent token (agent registration token) is created to start an agent. This token but cannot be used with the artifacts or meta-data. The default token can be used for testing and development, but you should [create new, specific tokens](#creating-tokens) for each new production environment.


Agent registration tokens are not exposed within the job environment.

## Agent access token

Agent access tokens (agent session tokens) are created when an agent is registered with Buildkite, and are unique for every registered agent.

Agent access token only works as long as the agent that created it is running, and it is used by all agent operations once the agent is [started](/docs/agent/v3/cli-start).

Access tokens are exposed within the job environment.

## Exchanging tokens

Agent registration token (default token) can be exchanged for an agent session token without any additional checks. To do it, the agent needs to call the `https://agent.buildkite.com/v3/register` endpoint with its registration token in the authorization header. The API response to this query is a regular agent access token that is next ingested and used by the agent.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this happen automatically? Or do you need to save the agent access token


## Using and storing tokens

Expand Down Expand Up @@ -48,7 +62,7 @@ query GetOrgID {

<!--alex ignore clearly-->

The token description should clearly identify the environment the token is intended to be used for, and is shown on your [Agents page](https://buildkite.com/organizations/-/agents) (for example, `Read-only token for static site generator`).
The token description should clearly identify the environment the token is intended to be used for, and is shown on your [Agents page](https://buildkite.com/organizations/-/agents) (for example, `Read-only token for static site generator`).

It is possible to create multiple agent tokens using the GraphQL API. These tokens will show up on the [Agents page](https://buildkite.com/organizations/-/agents) in the UI, but can only be managed (created or revoked) using the API.

Expand Down Expand Up @@ -97,6 +111,12 @@ Once a token is revoked, no new agents will be able to start with that token. Re

Agent tokens are specific to each Buildkite organization, and can be used to register an agent with any [queue](/docs/agent/v3/queues). Agent tokens can not be shared between organizations.

Agent tokens define the access permissions (`read` and/or `write`) for actions to be performed on all jobs and pipelines. This is necessary as Buildkite agents can run for extended periods of time. An agent might get launched to service one pipeline and then pick up work for another one after. This means that the access tokens for agents need the access to all pipelines and jobs.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent tokens define the access permissions

I'm not sure what this means either


## Log security considerations

Agent access token can allow writing to the stdout of a job as job log streaming happens on the `https://agent.buildkite.com/v3/jobs/chunks` agent API endpoint authenticated by the agent access token. If a bad actor gains access to your agent access token, they would be able to falsify new logs, but they wouldn’t be able to remove any existing logs as the endpoint is append-only.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Agent access token can allow writing to the stdout of a job as job log streaming happens on the `https://agent.buildkite.com/v3/jobs/chunks` agent API endpoint authenticated by the agent access token. If a bad actor gains access to your agent access token, they would be able to falsify new logs, but they wouldn’t be able to remove any existing logs as the endpoint is append-only.
Agent access token allow writing to the stdout of a job as job log streaming happens on the `https://agent.buildkite.com/v3/jobs/chunks` agent API endpoint authenticated by the agent access token. If a bad actor gains access to your agent access token, they would be able to falsify new logs, but they wouldn’t be able to remove any existing logs as the endpoint is append-only.


## Session tokens
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an agent session token, right? as in

Agent access tokens (agent session tokens) are created when an agent is registered with Buildkite, and are unique for every registered agent.

So let's be consistent how we talk about them


During registration, the agent exchanges the agent token for a session token. The session token is exposed to the job as the [environment variable](/docs/pipelines/environment-variables) `BUILDKITE_AGENT_ACCESS_TOKEN`, and is used by the [annotate](/docs/agent/v3/cli-annotate), [artifact](/docs/agent/v3/cli-artifact), [meta-data](/docs/agent/v3/cli-meta-data) and [pipeline](/docs/agent/v3/cli-pipeline) commands. Session tokens are scoped to a specific agent, and are valid for the duration the agent is connected.
During registration, the agent exchanges the agent token for a session token. The session token is exposed to the job as the [environment variable](/docs/pipelines/environment-variables) `BUILDKITE_AGENT_ACCESS_TOKEN`, and is used by the [annotate](/docs/agent/v3/cli-annotate), [artifact](/docs/agent/v3/cli-artifact), [meta-data](/docs/agent/v3/cli-meta-data), and [pipeline](/docs/agent/v3/cli-pipeline) commands. Session tokens are scoped to a specific agent, and are valid for the duration the agent is connected.