From 2dc077e3bdaedbeda4a690a563634d3717d7b9f8 Mon Sep 17 00:00:00 2001 From: Karen Sawrey Date: Thu, 18 Aug 2022 12:20:44 +0200 Subject: [PATCH 1/5] Adds a missing Oxford comma & removes trailing space --- pages/agent/v3/tokens.md.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/agent/v3/tokens.md.erb b/pages/agent/v3/tokens.md.erb index 14d9caf694..732dde62f3 100644 --- a/pages/agent/v3/tokens.md.erb +++ b/pages/agent/v3/tokens.md.erb @@ -48,7 +48,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. @@ -99,4 +99,4 @@ Agent tokens are specific to each Buildkite organization, and can be used to reg ## 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. From 8e0e23a2f02b665a2e8a3e7f32c41849db53c5b9 Mon Sep 17 00:00:00 2001 From: Karen Sawrey Date: Thu, 18 Aug 2022 13:01:33 +0200 Subject: [PATCH 2/5] Expand info on the default tokens and session tokens --- pages/agent/v3/tokens.md.erb | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/pages/agent/v3/tokens.md.erb b/pages/agent/v3/tokens.md.erb index 732dde62f3..512153bc2b 100644 --- a/pages/agent/v3/tokens.md.erb +++ b/pages/agent/v3/tokens.md.erb @@ -6,7 +6,17 @@ The Buildkite Agent requires an agent token to connect to Buildkite and register ## 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. This token is used to start an agent, and it can be used for testing and development. They cannot be used with the artifacts or meta-data. 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 is used by all agent operations once the agent is [started](/docs/agent/v3/cli-start). + +Access tokens are exposed within the job environment. ## Using and storing tokens From 31e27bb3f0b3b353454c0a58bf93a48ad4357976 Mon Sep 17 00:00:00 2001 From: Karen Sawrey Date: Thu, 18 Aug 2022 15:28:21 +0200 Subject: [PATCH 3/5] Token exchange and log security --- pages/agent/v3/tokens.md.erb | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/pages/agent/v3/tokens.md.erb b/pages/agent/v3/tokens.md.erb index 512153bc2b..fbb7a49663 100644 --- a/pages/agent/v3/tokens.md.erb +++ b/pages/agent/v3/tokens.md.erb @@ -18,6 +18,10 @@ Agent access token only works as long as the agent that created it is running, a Access tokens are exposed within the job environment. +## Exchanging tokens + +Agent registration token (adefault 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 The token is used by the Buildkite Agent's [start](/docs/agent/v3/cli-start#starting-an-agent) command, and can be provided on the command line, set in the [configuration file](/docs/agent/v3/configuration), or provided using the [environment variable](/docs/pipelines/environment-variables) `BUILDKITE_AGENT_TOKEN`. @@ -107,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. From f2dc14a31af5ff7c52b362ac3a53571900784f91 Mon Sep 17 00:00:00 2001 From: Karen Sawrey Date: Thu, 18 Aug 2022 15:30:12 +0200 Subject: [PATCH 4/5] Stray typo --- pages/agent/v3/tokens.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/agent/v3/tokens.md.erb b/pages/agent/v3/tokens.md.erb index fbb7a49663..cd8e2c792b 100644 --- a/pages/agent/v3/tokens.md.erb +++ b/pages/agent/v3/tokens.md.erb @@ -20,7 +20,7 @@ Access tokens are exposed within the job environment. ## Exchanging tokens -Agent registration token (adefault 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. +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 From 28069219941fb4ac771575d34637088d2b70c0ac Mon Sep 17 00:00:00 2001 From: Karen Sawrey Date: Tue, 23 Aug 2022 16:37:12 +0200 Subject: [PATCH 5/5] Reworded --- pages/agent/v3/tokens.md.erb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/agent/v3/tokens.md.erb b/pages/agent/v3/tokens.md.erb index cd8e2c792b..57ab88f26e 100644 --- a/pages/agent/v3/tokens.md.erb +++ b/pages/agent/v3/tokens.md.erb @@ -1,12 +1,12 @@ # 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 (agent registration token) is created. This token is used to start an agent, and it can be used for testing and development. They cannot be used with the artifacts or meta-data. 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. @@ -14,7 +14,7 @@ Agent registration tokens are not exposed within the job environment. 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 is used by all agent operations once the agent is [started](/docs/agent/v3/cli-start). +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.