diff --git a/pages/agent/v3/tokens.md.erb b/pages/agent/v3/tokens.md.erb index 14d9caf694..57ab88f26e 100644 --- a/pages/agent/v3/tokens.md.erb +++ b/pages/agent/v3/tokens.md.erb @@ -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 -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. + +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. ## Using and storing tokens @@ -48,7 +62,7 @@ query GetOrgID { -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. @@ -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. + +## 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. + ## Session tokens -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.