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

karensawrey · 2022-08-18T11:03:11Z

Regarding the Issue #1413.

render · 2022-08-18T11:03:16Z

Your Render PR Server URL is https://bk-docs-pr-1709.onrender.com.

Follow its progress at https://dashboard.render.com/web/srv-cbv1os82i3mvqpikiopg.

karensawrey · 2022-08-18T13:40:15Z

The PR is out of its draft stage but needs a fresh re-read before an actual human being will be kindly asked to give it a go.

plaindocs

This is a good start to addressesing a thorny topic. Let me know when you've had a second pass to address these nits and I'll take another look.

plaindocs · 2022-08-30T14:06:14Z

pages/agent/v3/tokens.md.erb


 {: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.


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

this needs more words :-p

plaindocs · 2022-08-30T14:07:01Z

pages/agent/v3/tokens.md.erb


 {: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.


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.

plaindocs · 2022-08-30T14:07:38Z

pages/agent/v3/tokens.md.erb

+
+## 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.


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

plaindocs · 2022-08-30T14:08:16Z

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


Let's call this

Agent registration token (default token)

plaindocs · 2022-08-30T14:09:18Z

pages/agent/v3/tokens.md.erb

@@ -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.


Agent tokens define the access permissions

I'm not sure what this means either

plaindocs · 2022-08-30T14:09:52Z

pages/agent/v3/tokens.md.erb

+
+## 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.


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.

plaindocs · 2022-08-30T14:12:19Z

pages/agent/v3/tokens.md.erb

+## 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


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

karensawrey added 2 commits August 18, 2022 12:20

Adds a missing Oxford comma & removes trailing space

2dc077e

Expand info on the default tokens and session tokens

8e0e23a

karensawrey added 2 commits August 18, 2022 15:28

Token exchange and log security

31e27bb

Stray typo

f2dc14a

karensawrey marked this pull request as ready for review August 18, 2022 13:39

Reworded

2806921

karensawrey requested a review from plaindocs August 23, 2022 14:39

plaindocs suggested changes Aug 30, 2022

View reviewed changes

karensawrey closed this Sep 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

karensawrey commented Aug 18, 2022

render bot commented Aug 18, 2022

karensawrey commented Aug 18, 2022

plaindocs left a comment

plaindocs Aug 30, 2022

plaindocs Aug 30, 2022

plaindocs Aug 30, 2022

plaindocs Aug 30, 2022

plaindocs Aug 30, 2022

plaindocs Aug 30, 2022

plaindocs Aug 30, 2022

	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.


		## 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.

		@@ -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.

	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.

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

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

Conversation

karensawrey commented Aug 18, 2022

render bot commented Aug 18, 2022

karensawrey commented Aug 18, 2022

plaindocs left a comment

Choose a reason for hiding this comment

plaindocs Aug 30, 2022

Choose a reason for hiding this comment

plaindocs Aug 30, 2022

Choose a reason for hiding this comment

plaindocs Aug 30, 2022

Choose a reason for hiding this comment

plaindocs Aug 30, 2022

Choose a reason for hiding this comment

Agent registration token (default token)

plaindocs Aug 30, 2022

Choose a reason for hiding this comment

plaindocs Aug 30, 2022

Choose a reason for hiding this comment

plaindocs Aug 30, 2022

Choose a reason for hiding this comment