From 605a36563b9317fdca34739ce7c89a7cdc02c463 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 16 Aug 2022 16:57:35 +0100 Subject: [PATCH 01/26] Add architecture guide for Machine ID --- docs/config.json | 4 +++ docs/pages/machine-id/architecture.mdx | 46 ++++++++++++++++++++++++++ docs/pages/machine-id/introduction.mdx | 1 + 3 files changed, 51 insertions(+) create mode 100644 docs/pages/machine-id/architecture.mdx diff --git a/docs/config.json b/docs/config.json index 8489d6445f511..c78561d8657b8 100644 --- a/docs/config.json +++ b/docs/config.json @@ -824,6 +824,10 @@ "title": "Getting Started", "slug": "/machine-id/getting-started/" }, + { + "title": "Architecture", + "slug": "/machine-id/architecture/" + }, { "title": "Troubleshooting", "slug": "/machine-id/troubleshooting/" diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx new file mode 100644 index 0000000000000..ecce8a8ff1904 --- /dev/null +++ b/docs/pages/machine-id/architecture.mdx @@ -0,0 +1,46 @@ +--- +title: Machine ID Architecture +description: How Teleport Machine ID works. +--- + +This section provides an overview of Teleport Machine ID's inner workings. + +A more in-depth specification of the workings of Machine ID can be found in +[the Request For Discussion.](https://github.com/gravitational/teleport/blob/master/rfd/0064-bot-for-cert-renewals.md) + +## Role Impersonation + +At the core of Machine ID is the concept of role impersonation. + +Role Impersonation allows a user to generate credentials with a set of requested +roles. The user does not have to hold these roles, but must have been granted +permission to impersonate them. The role impersonated credentials still includes +the username of the user that generated them, so actions can be attributed to +the user. + +These credentials can then be used to complete any action that is allowed by the +role's configured permissions. + +In the case of Machine ID, the bot user is assigned a bot role, which includes +permissions to impersonate the roles that the user has configured. + +## `tbot` + +`tbot` is the binary that acts as the agent for Machine ID. + +On initial load, `tbot` uses the configured join method to obtain a set of +credentials for the bot user from the Teleport auth service. It can then use +these credentials to communicate with the Teleport auth service as the bot. + +On a configured regular period `tbot` then: + +- Renews these bot user credentials +- For each configured destination: + - Obtains role impersonated credentials from the auth service using its + bot user credentials. + - Outputs these role impersonated credentials in the configured formats. + +Concurrently to this, `tbot` monitors the Teleport certificate authorities to +detect certificate rotations. When this occurs, it triggers additional renewals +to ensure that `tbot` has certificates signed by the newly rotated certificate +authority. \ No newline at end of file diff --git a/docs/pages/machine-id/introduction.mdx b/docs/pages/machine-id/introduction.mdx index 39ddcbcb1e7d6..8b57daa3eb1b1 100644 --- a/docs/pages/machine-id/introduction.mdx +++ b/docs/pages/machine-id/introduction.mdx @@ -60,6 +60,7 @@ Let's create a bot and use the machine identity to connect to a server. ## Getting started - [Getting started](./getting-started.mdx): Getting started with Teleport Machine ID +- [Architecture](./architecture.mdx): A technical overview of how Machine ID works ## Guides From ca1b76b0e67ea7f6fa9b3f23fa297a2c4ccaa1e0 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Thu, 18 Aug 2022 11:25:12 +0100 Subject: [PATCH 02/26] Adjust indentation per linter rule --- docs/pages/machine-id/architecture.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index ecce8a8ff1904..45258f369af50 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -36,9 +36,9 @@ On a configured regular period `tbot` then: - Renews these bot user credentials - For each configured destination: - - Obtains role impersonated credentials from the auth service using its + - Obtains role impersonated credentials from the auth service using its bot user credentials. - - Outputs these role impersonated credentials in the configured formats. + - Outputs these role impersonated credentials in the configured formats. Concurrently to this, `tbot` monitors the Teleport certificate authorities to detect certificate rotations. When this occurs, it triggers additional renewals From a32768833075d5c91fcbbc57d1533e75da23e5c7 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 10:31:09 +0100 Subject: [PATCH 03/26] Update docs/pages/machine-id/architecture.mdx Co-authored-by: Paul Gottschling --- docs/pages/machine-id/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 45258f369af50..76a2ae235e815 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -14,7 +14,7 @@ At the core of Machine ID is the concept of role impersonation. Role Impersonation allows a user to generate credentials with a set of requested roles. The user does not have to hold these roles, but must have been granted -permission to impersonate them. The role impersonated credentials still includes +permission to impersonate them. The impersonated credentials still include the username of the user that generated them, so actions can be attributed to the user. From 142ee324f1ed822145833eb0346d974675b490e7 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 10:31:56 +0100 Subject: [PATCH 04/26] Update docs/pages/machine-id/architecture.mdx Co-authored-by: Paul Gottschling --- docs/pages/machine-id/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 76a2ae235e815..b753d9afa2ace 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -29,7 +29,7 @@ permissions to impersonate the roles that the user has configured. `tbot` is the binary that acts as the agent for Machine ID. On initial load, `tbot` uses the configured join method to obtain a set of -credentials for the bot user from the Teleport auth service. It can then use +credentials for the bot user from the Teleport Auth Service. It can then use these credentials to communicate with the Teleport auth service as the bot. On a configured regular period `tbot` then: From 63a3114f7327da084a6c0b8963ebba304c005a4c Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 10:32:03 +0100 Subject: [PATCH 05/26] Update docs/pages/machine-id/architecture.mdx Co-authored-by: Paul Gottschling --- docs/pages/machine-id/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index b753d9afa2ace..7e57982eb913c 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -30,7 +30,7 @@ permissions to impersonate the roles that the user has configured. On initial load, `tbot` uses the configured join method to obtain a set of credentials for the bot user from the Teleport Auth Service. It can then use -these credentials to communicate with the Teleport auth service as the bot. +these credentials to communicate with the Teleport Auth Service as the bot. On a configured regular period `tbot` then: From f032cbc946ee90374a7d3c35d43c6ee30ce3cac6 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 10:32:08 +0100 Subject: [PATCH 06/26] Update docs/pages/machine-id/architecture.mdx Co-authored-by: Paul Gottschling --- docs/pages/machine-id/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 7e57982eb913c..dad752a047587 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -36,7 +36,7 @@ On a configured regular period `tbot` then: - Renews these bot user credentials - For each configured destination: - - Obtains role impersonated credentials from the auth service using its + - Obtains role impersonated credentials from the Auth Service using its bot user credentials. - Outputs these role impersonated credentials in the configured formats. From 06acca380404b3a8dedb450d8e30a6bcb7278d01 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 11:20:57 +0100 Subject: [PATCH 07/26] Add section on joining and renewable certificates --- docs/pages/machine-id/architecture.mdx | 83 +++++++++++++++++++++----- 1 file changed, 68 insertions(+), 15 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index dad752a047587..039d0849b57ad 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -8,6 +8,28 @@ This section provides an overview of Teleport Machine ID's inner workings. A more in-depth specification of the workings of Machine ID can be found in [the Request For Discussion.](https://github.com/gravitational/teleport/blob/master/rfd/0064-bot-for-cert-renewals.md) +## `tbot` + +`tbot` is the binary that acts as the agent for Machine ID. + +On initial load, `tbot` uses the [configured join method](#onboarding) to obtain +a set of credentials for the bot user from the Teleport Auth Service. It can +then use these credentials to communicate with the Teleport Auth Service as the +bot. + +On a configured regular period `tbot` then: + +- Renews these bot user credentials +- For each configured destination: + - Obtains [role impersonated](#role-impersonation) credentials from the Auth + Service using its bot user credentials. + - Outputs these role impersonated credentials in the configured formats. + +Concurrently to this, `tbot` monitors the Teleport certificate authorities to +detect certificate rotations. When this occurs, it triggers additional renewals +to ensure that `tbot` has certificates signed by the newly rotated certificate +authority. + ## Role Impersonation At the core of Machine ID is the concept of role impersonation. @@ -24,23 +46,54 @@ role's configured permissions. In the case of Machine ID, the bot user is assigned a bot role, which includes permissions to impersonate the roles that the user has configured. -## `tbot` +## Onboarding -`tbot` is the binary that acts as the agent for Machine ID. +Onboarding is the process by which `tbot` initially authenticates with the +Teleport auth service in order to receive credentials. -On initial load, `tbot` uses the configured join method to obtain a set of -credentials for the bot user from the Teleport Auth Service. It can then use -these credentials to communicate with the Teleport Auth Service as the bot. +Machine ID leverages the existing Token resource within Teleport, with the +Token containing an additional `botName` field that identifies the bot user +associated with the token. -On a configured regular period `tbot` then: +Machine ID currently supports two methods of joining that have some key +differences. -- Renews these bot user credentials -- For each configured destination: - - Obtains role impersonated credentials from the Auth Service using its - bot user credentials. - - Outputs these role impersonated credentials in the configured formats. +Static Token: +- The name of the token is the only value needed to join. This value is a + secret and must be handled securely. +- Once used, the Token resource self-deletes. This means it can only be used to + join a single bot to a Teleport cluster. +- The certificates exchanged for the token are + [renewable](#renewable-certificates). -Concurrently to this, `tbot` monitors the Teleport certificate authorities to -detect certificate rotations. When this occurs, it triggers additional renewals -to ensure that `tbot` has certificates signed by the newly rotated certificate -authority. \ No newline at end of file + +Dynamic join tokens (e.g AWS IAM): +- These tokens rely on some kind of external system that allows the bot to + prove it is allowed to join the cluster. The name of the token identifies the + Token resource in Teleport that contains the configuration. +- The token can be used to join as many bots as you want. +- The certificates exchanged for the token are not renewable. When the bot wants + to renew its certificates, it simply repeats the original join steps. + +Where possible, you should prefer to use a dynamic join token over a static +token as this eliminates the need to handle a secret. + +## Renewable certificates + +Human Teleport users are not able to renew their credentials without +re-authenticating. As Machine ID must work without manual human intervention, +bots that have joined using static tokens are granted credentials that are +marked as renewable. This means that the bot can use these credentials to +fetch a new set of credentials, with an expiry date further in the future. + +In order to mitigate the risk of bot user credentials being stolen, and then +continually renewed by a malicious actor, renewable bot user certificates +include a **generation counter**. + +The generation counter is stored against the user in the database and within the +certificate. This counter is incremented each time the user renews their +certificate. When a bot attempts to renew, the Auth Server ensures that the +value within the certificate and in the database match. If they do not match, +then the bot user is automatically locked. This means that if certificates are +stolen, and attempted to be renewed whilst the bot is still running, the next +renewal will render them useless. From 8f1e896a5e8fa8bfcecf88fb8166094229f0a40e Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 11:31:30 +0100 Subject: [PATCH 08/26] spag --- docs/pages/machine-id/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 039d0849b57ad..200cc8f6b5ced 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -84,7 +84,7 @@ Human Teleport users are not able to renew their credentials without re-authenticating. As Machine ID must work without manual human intervention, bots that have joined using static tokens are granted credentials that are marked as renewable. This means that the bot can use these credentials to -fetch a new set of credentials, with an expiry date further in the future. +fetch a new set of credentials with an expiry date further in the future. In order to mitigate the risk of bot user credentials being stolen, and then continually renewed by a malicious actor, renewable bot user certificates From bc6a59d9c5587c304d23c2dd4d3a2b312a2fc07f Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 12:41:06 +0100 Subject: [PATCH 09/26] Add notes on bot creation, user and token. --- docs/pages/machine-id/architecture.mdx | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 200cc8f6b5ced..47027daa91c8d 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -8,6 +8,20 @@ This section provides an overview of Teleport Machine ID's inner workings. A more in-depth specification of the workings of Machine ID can be found in [the Request For Discussion.](https://github.com/gravitational/teleport/blob/master/rfd/0064-bot-for-cert-renewals.md) +## Bot creation + +When creating a bot via `tctl`, up to three resources are created: + +- Bot user: this will be the user that the Machine ID agent authenticates as. +- Bot role: the bot user is assigned the bot role, and the bot role contains + various permissions that the bot will need to function. For example, the + ability to watch the certificate authorities and the ability to + [impersonate roles](#role-impersonation). +- Token: for [onboarding](#onboarding), a token must exist that allows the + Machine ID agent to initially authenticate as the bot user. If an existing + token is not specified, then a static single-use token will be created by the + Auth Server. + ## `tbot` `tbot` is the binary that acts as the agent for Machine ID. @@ -23,7 +37,7 @@ On a configured regular period `tbot` then: - For each configured destination: - Obtains [role impersonated](#role-impersonation) credentials from the Auth Service using its bot user credentials. - - Outputs these role impersonated credentials in the configured formats. + - Outputs these role impersonated credentials in various formats. Concurrently to this, `tbot` monitors the Teleport certificate authorities to detect certificate rotations. When this occurs, it triggers additional renewals @@ -52,7 +66,7 @@ Onboarding is the process by which `tbot` initially authenticates with the Teleport auth service in order to receive credentials. Machine ID leverages the existing Token resource within Teleport, with the -Token containing an additional `botName` field that identifies the bot user +token containing an additional `botName` field that identifies the bot user associated with the token. Machine ID currently supports two methods of joining that have some key @@ -61,8 +75,8 @@ differences. Static Token: - The name of the token is the only value needed to join. This value is a secret and must be handled securely. -- Once used, the Token resource self-deletes. This means it can only be used to - join a single bot to a Teleport cluster. +- Once used, the token resource self-destructs. This means it can only be used + to join a single bot to a Teleport cluster. - The certificates exchanged for the token are [renewable](#renewable-certificates). From 847a961b581b383688e55e3d9d6c596e99a2f08c Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 14:51:43 +0100 Subject: [PATCH 10/26] Clarify bot destination configuration --- docs/pages/machine-id/architecture.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 47027daa91c8d..485c64d0b3e6f 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -33,11 +33,12 @@ bot. On a configured regular period `tbot` then: -- Renews these bot user credentials -- For each configured destination: - - Obtains [role impersonated](#role-impersonation) credentials from the Auth - Service using its bot user credentials. - - Outputs these role impersonated credentials in various formats. +1. Renews these bot user credentials +2. For each destination provided in `tbot`'s configuration: + 1. Obtains [role impersonated](#role-impersonation) credentials for the roles + specified in the destination configuration from the Auth Service using the + bot user credentials. + 2. Outputs these role impersonated credentials in various formats. Concurrently to this, `tbot` monitors the Teleport certificate authorities to detect certificate rotations. When this occurs, it triggers additional renewals From 75fe6353747e633693497733c847c5b1dcbedd5e Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 15:15:19 +0100 Subject: [PATCH 11/26] Adjust indentation --- docs/pages/machine-id/architecture.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 485c64d0b3e6f..0b5aa545f2d53 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -35,10 +35,10 @@ On a configured regular period `tbot` then: 1. Renews these bot user credentials 2. For each destination provided in `tbot`'s configuration: - 1. Obtains [role impersonated](#role-impersonation) credentials for the roles + 1. Obtains [role impersonated](#role-impersonation) credentials for the roles specified in the destination configuration from the Auth Service using the bot user credentials. - 2. Outputs these role impersonated credentials in various formats. + 2. Outputs these role impersonated credentials in various formats. Concurrently to this, `tbot` monitors the Teleport certificate authorities to detect certificate rotations. When this occurs, it triggers additional renewals From d558fe8c1bb6f892459f4a4abac1255309dd7fc3 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 16:49:04 +0100 Subject: [PATCH 12/26] Start fleshing out notes on file permissions --- docs/pages/machine-id/architecture.mdx | 35 ++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 0b5aa545f2d53..1240f2f1093ac 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -74,6 +74,7 @@ Machine ID currently supports two methods of joining that have some key differences. Static Token: + - The name of the token is the only value needed to join. This value is a secret and must be handled securely. - Once used, the token resource self-destructs. This means it can only be used @@ -83,6 +84,7 @@ Static Token: Dynamic join tokens (e.g AWS IAM): + - These tokens rely on some kind of external system that allows the bot to prove it is allowed to join the cluster. The name of the token identifies the Token resource in Teleport that contains the configuration. @@ -112,3 +114,36 @@ value within the certificate and in the database match. If they do not match, then the bot user is automatically locked. This means that if certificates are stolen, and attempted to be renewed whilst the bot is still running, the next renewal will render them useless. + +## File permissions + +There are two types of folder in use by `tbot`: + +- The bot's own files: these store sensitive credentials belonging to the bot + user itself. This is by default stored at `/var/lib/teleport/bot/`. +- Directory destinations: when a directory destination is configured, the bot + outputs the role impersonated credentials as files in the specified directory. + +It is important that we ensure that these files can only be accessed by the +fewest number of users on the system as is necessary. + +In the case of the bot's own files, this should only be the user that the bot +runs as. Running `tbot init` as shown in the documentation should create and +correctly configure the permissions for this. + +In the case of directory destinations, the user the bot runs as requires read +and write permissions, and users that will need to use the credentials output +by the bot require read permissions. In most cases, this user that needs to read +the credentials should be specifically created for your application to run as. + +In addition to basic POSIX filesystem permissions, `tbot` also sets up Linux +ACLs if the system supports it. This allows more granular control by granting +individual users access. +// TODO: Explain more + +Finally, on systems that support it, `tbot` will by default attempt to prevent +the resolution of symbolic links when reading and writing files. This prevents a +class of attacks sometimes known as +[symlink attacks](https://capec.mitre.org/data/definitions/132.html). This +behaviour can be disabled using the `insecure` symlink option when configuring +your destination. \ No newline at end of file From 0bd4531f0a6d2159d637e5055a865ff9fa7b2ded Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 22 Aug 2022 21:27:17 +0100 Subject: [PATCH 13/26] Finish filesystem permissions section --- docs/pages/machine-id/architecture.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 1240f2f1093ac..0a8b2c12bae2f 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -139,7 +139,6 @@ the credentials should be specifically created for your application to run as. In addition to basic POSIX filesystem permissions, `tbot` also sets up Linux ACLs if the system supports it. This allows more granular control by granting individual users access. -// TODO: Explain more Finally, on systems that support it, `tbot` will by default attempt to prevent the resolution of symbolic links when reading and writing files. This prevents a From a5c2fd55ddd73107b2df49ea04c76416d43861c3 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Wed, 24 Aug 2022 07:36:40 +0100 Subject: [PATCH 14/26] Update docs/pages/machine-id/architecture.mdx Co-authored-by: Tim Buckley --- docs/pages/machine-id/architecture.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 0a8b2c12bae2f..9de00cacb6a56 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -136,9 +136,9 @@ and write permissions, and users that will need to use the credentials output by the bot require read permissions. In most cases, this user that needs to read the credentials should be specifically created for your application to run as. -In addition to basic POSIX filesystem permissions, `tbot` also sets up Linux -ACLs if the system supports it. This allows more granular control by granting -individual users access. +In addition to basic POSIX filesystem permissions, `tbot init` also sets up +Linux ACLs if the system supports it. This allows more granular control by +granting individual users access. Finally, on systems that support it, `tbot` will by default attempt to prevent the resolution of symbolic links when reading and writing files. This prevents a From 9da37b10f19a9f02127f30781f7eb0ebfd406bbc Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Wed, 24 Aug 2022 08:01:00 +0100 Subject: [PATCH 15/26] Address Tim's PR comments --- docs/pages/machine-id/architecture.mdx | 36 +++++++++++++++----------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 9de00cacb6a56..7cd7406d0bf4f 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -75,8 +75,8 @@ differences. Static Token: -- The name of the token is the only value needed to join. This value is a - secret and must be handled securely. +- The name of the token is used as an opaque secret needed to join the Teleport + cluster. This means it must be stored and communicated securely. - Once used, the token resource self-destructs. This means it can only be used to join a single bot to a Teleport cluster. - The certificates exchanged for the token are @@ -88,7 +88,8 @@ Dynamic join tokens (e.g AWS IAM): - These tokens rely on some kind of external system that allows the bot to prove it is allowed to join the cluster. The name of the token identifies the Token resource in Teleport that contains the configuration. -- The token can be used to join as many bots as you want. +- The token can be used to join as many bots as you want, and do not self + destruct in the same way that static tokens do. - The certificates exchanged for the token are not renewable. When the bot wants to renew its certificates, it simply repeats the original join steps. @@ -119,22 +120,27 @@ renewal will render them useless. There are two types of folder in use by `tbot`: -- The bot's own files: these store sensitive credentials belonging to the bot - user itself. This is by default stored at `/var/lib/teleport/bot/`. +- The bot's own files: these store credentials belonging to the `tbot` process + itself. As this credentials are potentially renewable, and will allow the + impersonation of any roles you have allowed for the bot user, they should be + treated as exceptionally senstive. This is by default stored at + `/var/lib/teleport/bot/`. - Directory destinations: when a directory destination is configured, the bot outputs the role impersonated credentials as files in the specified directory. It is important that we ensure that these files can only be accessed by the -fewest number of users on the system as is necessary. - -In the case of the bot's own files, this should only be the user that the bot -runs as. Running `tbot init` as shown in the documentation should create and -correctly configure the permissions for this. - -In the case of directory destinations, the user the bot runs as requires read -and write permissions, and users that will need to use the credentials output -by the bot require read permissions. In most cases, this user that needs to read -the credentials should be specifically created for your application to run as. +fewest number of Linux processes and users on the system as is necessary. + +In the case of the bot's own files, it is best practice to create a Linux user +specifically for running `tbot` as and to ensure that only this user has access +to this directory. + +In the case of directory destinations, the process the bot runs as requires read +and write permissions, and processes that will need the credentials output by +the bot require read permissions. We recommend that you create a Linux user +specific to the process that needs to access these files. When using +`tbot init`, specify this Linux user as the "reader" to grant it access to the +destination. In addition to basic POSIX filesystem permissions, `tbot init` also sets up Linux ACLs if the system supports it. This allows more granular control by From f77b78a6ba68489a389eed3b45b74698cb7c0edd Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Wed, 24 Aug 2022 08:02:05 +0100 Subject: [PATCH 16/26] spelling correction --- docs/pages/machine-id/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 7cd7406d0bf4f..a271dfd38b15e 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -123,7 +123,7 @@ There are two types of folder in use by `tbot`: - The bot's own files: these store credentials belonging to the `tbot` process itself. As this credentials are potentially renewable, and will allow the impersonation of any roles you have allowed for the bot user, they should be - treated as exceptionally senstive. This is by default stored at + treated as exceptionally sensitive. This is by default stored at `/var/lib/teleport/bot/`. - Directory destinations: when a directory destination is configured, the bot outputs the role impersonated credentials as files in the specified directory. From 0d3bf0254bdef3323b6cb591802f4abdf1c7f849 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 13:11:44 +0100 Subject: [PATCH 17/26] Apply suggestions from code review Co-authored-by: Paul Gottschling --- docs/pages/machine-id/architecture.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index a271dfd38b15e..20ee92afb32a6 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -64,7 +64,7 @@ permissions to impersonate the roles that the user has configured. ## Onboarding Onboarding is the process by which `tbot` initially authenticates with the -Teleport auth service in order to receive credentials. +Teleport Auth Service in order to receive credentials. Machine ID leverages the existing Token resource within Teleport, with the token containing an additional `botName` field that identifies the bot user @@ -73,17 +73,17 @@ associated with the token. Machine ID currently supports two methods of joining that have some key differences. -Static Token: +### Static token - The name of the token is used as an opaque secret needed to join the Teleport cluster. This means it must be stored and communicated securely. - Once used, the token resource self-destructs. This means it can only be used to join a single bot to a Teleport cluster. - The certificates exchanged for the token are - [renewable](#renewable-certificates). + renewable, as we will explain in the next section. -Dynamic join tokens (e.g AWS IAM): +### Dynamic join tokens (e.g AWS IAM): - These tokens rely on some kind of external system that allows the bot to prove it is allowed to join the cluster. The name of the token identifies the @@ -121,9 +121,9 @@ renewal will render them useless. There are two types of folder in use by `tbot`: - The bot's own files: these store credentials belonging to the `tbot` process - itself. As this credentials are potentially renewable, and will allow the - impersonation of any roles you have allowed for the bot user, they should be - treated as exceptionally sensitive. This is by default stored at + itself. As these credentials are potentially renewable, and will allow the + impersonation of any roles you have assigned to the bot user, they should be + treated as exceptionally sensitive. The bot's own files are stored by default at `/var/lib/teleport/bot/`. - Directory destinations: when a directory destination is configured, the bot outputs the role impersonated credentials as files in the specified directory. @@ -132,7 +132,7 @@ It is important that we ensure that these files can only be accessed by the fewest number of Linux processes and users on the system as is necessary. In the case of the bot's own files, it is best practice to create a Linux user -specifically for running `tbot` as and to ensure that only this user has access +specifically for running `tbot` and to ensure that only this user has access to this directory. In the case of directory destinations, the process the bot runs as requires read From 1db0438be7ad7b729b1e125a660ac31560b9a1c0 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 13:32:04 +0100 Subject: [PATCH 18/26] Address a few docs structure comments --- docs/pages/machine-id/architecture.mdx | 42 +++++++++++++------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 20ee92afb32a6..689e4cebfc32d 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -22,6 +22,22 @@ When creating a bot via `tctl`, up to three resources are created: token is not specified, then a static single-use token will be created by the Auth Server. +## Role Impersonation + +At the core of Machine ID is the concept of role impersonation. + +Role Impersonation allows a user to generate credentials with a set of requested +roles. The user does not have to hold these roles, but must have been granted +permission to impersonate them. The impersonated credentials still include +the username of the user that generated them, so actions can be attributed to +the user. + +These credentials can then be used to complete any action that is allowed by the +role's configured permissions. + +In the case of Machine ID, the bot user is assigned a bot role, which includes +permissions to impersonate the roles that the user has configured. + ## `tbot` `tbot` is the binary that acts as the agent for Machine ID. @@ -45,35 +61,19 @@ detect certificate rotations. When this occurs, it triggers additional renewals to ensure that `tbot` has certificates signed by the newly rotated certificate authority. -## Role Impersonation - -At the core of Machine ID is the concept of role impersonation. - -Role Impersonation allows a user to generate credentials with a set of requested -roles. The user does not have to hold these roles, but must have been granted -permission to impersonate them. The impersonated credentials still include -the username of the user that generated them, so actions can be attributed to -the user. - -These credentials can then be used to complete any action that is allowed by the -role's configured permissions. - -In the case of Machine ID, the bot user is assigned a bot role, which includes -permissions to impersonate the roles that the user has configured. - ## Onboarding Onboarding is the process by which `tbot` initially authenticates with the Teleport Auth Service in order to receive credentials. -Machine ID leverages the existing Token resource within Teleport, with the +Machine ID leverages the existing token resource within Teleport, with the token containing an additional `botName` field that identifies the bot user associated with the token. Machine ID currently supports two methods of joining that have some key differences. -### Static token +### Static token: - The name of the token is used as an opaque secret needed to join the Teleport cluster. This means it must be stored and communicated securely. @@ -85,9 +85,9 @@ differences. ### Dynamic join tokens (e.g AWS IAM): -- These tokens rely on some kind of external system that allows the bot to - prove it is allowed to join the cluster. The name of the token identifies the - Token resource in Teleport that contains the configuration. +- These tokens rely on an external authority that allows the bot to prove it is + allowed to join the cluster. The name of the token identifies the Token + resource in Teleport that contains the configuration. - The token can be used to join as many bots as you want, and do not self destruct in the same way that static tokens do. - The certificates exchanged for the token are not renewable. When the bot wants From f8836b68a05915302ea434fdefbf1851c402f6bb Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 13:45:16 +0100 Subject: [PATCH 19/26] Furth restructure architectural guide --- docs/pages/machine-id/architecture.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 689e4cebfc32d..0f1ff3a24ee68 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -10,7 +10,11 @@ A more in-depth specification of the workings of Machine ID can be found in ## Bot creation -When creating a bot via `tctl`, up to three resources are created: +In order to use the Machine ID agent (`tbot`), a bot must first be created using +the `tctl bots add`. + +A "bot" within Teleport is comprised of three resources, which are created by +the Auth Service when `tctl bots add` is executed: - Bot user: this will be the user that the Machine ID agent authenticates as. - Bot role: the bot user is assigned the bot role, and the bot role contains @@ -51,10 +55,9 @@ On a configured regular period `tbot` then: 1. Renews these bot user credentials 2. For each destination provided in `tbot`'s configuration: - 1. Obtains [role impersonated](#role-impersonation) credentials for the roles - specified in the destination configuration from the Auth Service using the - bot user credentials. - 2. Outputs these role impersonated credentials in various formats. + 1. Uses impersonation to obtain credentials from the Auth Service for the + roles specified in the destination's configuration. + 2. Outputs these credentials in various formats. Concurrently to this, `tbot` monitors the Teleport certificate authorities to detect certificate rotations. When this occurs, it triggers additional renewals From 2e53a4227790c0f42327c6d3759e29f49356fd95 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 13:46:59 +0100 Subject: [PATCH 20/26] spag --- docs/pages/machine-id/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 0f1ff3a24ee68..77d09c659b10f 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -11,7 +11,7 @@ A more in-depth specification of the workings of Machine ID can be found in ## Bot creation In order to use the Machine ID agent (`tbot`), a bot must first be created using -the `tctl bots add`. +`tctl bots add`. A "bot" within Teleport is comprised of three resources, which are created by the Auth Service when `tctl bots add` is executed: From b5fc9717a830176764c9ab8e6e6c7e6aee142139 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 13:55:47 +0100 Subject: [PATCH 21/26] Avoid using the "static" terminology in reference to tokens. --- docs/pages/machine-id/architecture.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 77d09c659b10f..5cca7d33ae12f 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -23,8 +23,8 @@ the Auth Service when `tctl bots add` is executed: [impersonate roles](#role-impersonation). - Token: for [onboarding](#onboarding), a token must exist that allows the Machine ID agent to initially authenticate as the bot user. If an existing - token is not specified, then a static single-use token will be created by the - Auth Server. + token is not specified, then a single-use token will be created by the Auth + Server. ## Role Impersonation @@ -76,7 +76,7 @@ associated with the token. Machine ID currently supports two methods of joining that have some key differences. -### Static token: +### Ephemeral token: - The name of the token is used as an opaque secret needed to join the Teleport cluster. This means it must be stored and communicated securely. @@ -96,14 +96,14 @@ differences. - The certificates exchanged for the token are not renewable. When the bot wants to renew its certificates, it simply repeats the original join steps. -Where possible, you should prefer to use a dynamic join token over a static +Where possible, you should prefer to use a dynamic join token over an emphemeral token as this eliminates the need to handle a secret. ## Renewable certificates Human Teleport users are not able to renew their credentials without re-authenticating. As Machine ID must work without manual human intervention, -bots that have joined using static tokens are granted credentials that are +bots that have joined using ephemeral tokens are granted credentials that are marked as renewable. This means that the bot can use these credentials to fetch a new set of credentials with an expiry date further in the future. From 0dd80fef238bf8db3a2016368a0787d3e38f0b87 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 13:57:52 +0100 Subject: [PATCH 22/26] appease linter no-heading-punctuation --- docs/pages/machine-id/architecture.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 5cca7d33ae12f..4aca4eeeee1ac 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -76,7 +76,7 @@ associated with the token. Machine ID currently supports two methods of joining that have some key differences. -### Ephemeral token: +### Ephemeral token - The name of the token is used as an opaque secret needed to join the Teleport cluster. This means it must be stored and communicated securely. @@ -86,13 +86,13 @@ differences. renewable, as we will explain in the next section. -### Dynamic join tokens (e.g AWS IAM): +### Dynamic join tokens (e.g AWS IAM) - These tokens rely on an external authority that allows the bot to prove it is allowed to join the cluster. The name of the token identifies the Token resource in Teleport that contains the configuration. - The token can be used to join as many bots as you want, and do not self - destruct in the same way that static tokens do. + destruct in the same way that ephemeral tokens do. - The certificates exchanged for the token are not renewable. When the bot wants to renew its certificates, it simply repeats the original join steps. From 81b1e374fe141ad0b3ade2ad16000ff245ab1b1b Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 14:38:50 +0100 Subject: [PATCH 23/26] Use paragraphs rather than ordered list for tbot actions --- docs/pages/machine-id/architecture.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 4aca4eeeee1ac..6ef4b9ab607ce 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -51,13 +51,15 @@ a set of credentials for the bot user from the Teleport Auth Service. It can then use these credentials to communicate with the Teleport Auth Service as the bot. -On a configured regular period `tbot` then: - -1. Renews these bot user credentials -2. For each destination provided in `tbot`'s configuration: - 1. Uses impersonation to obtain credentials from the Auth Service for the - roles specified in the destination's configuration. - 2. Outputs these credentials in various formats. +On a configured regular period `tbot` begins its renewal process. It begins by +refreshing the bot's own credentials, by renewing them or fetching a fresh set +of credentials depending on the configured onboarding method. + +Then, for each destination provided in `tbot`'s configuration, `tbot` uses +impersonation to obtain credentials from the Auth Service for the roles +specified in the destination's configuration. Once these are fetched, these are +then persisted to the destination in various formats along with other useful +matter such as the current certificate authority certificates. Concurrently to this, `tbot` monitors the Teleport certificate authorities to detect certificate rotations. When this occurs, it triggers additional renewals From 40d3a02bdaed63e5ad5cf972e996af6327a0e13d Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 15:04:30 +0100 Subject: [PATCH 24/26] Add notes on "destinations" --- docs/pages/machine-id/architecture.mdx | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 6ef4b9ab607ce..3bdf9dd97b635 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -46,10 +46,23 @@ permissions to impersonate the roles that the user has configured. `tbot` is the binary that acts as the agent for Machine ID. -On initial load, `tbot` uses the [configured join method](#onboarding) to obtain -a set of credentials for the bot user from the Teleport Auth Service. It can -then use these credentials to communicate with the Teleport Auth Service as the -bot. +Before `tbot` can be started, at least two parts of configuration will need to +be provided via the configuration file or as arguments provided to `tbot` when +it is executed. This consists of: + +- [A join method](#onboarding) that the bot can use to prove that it should be + allowed to join the Teleport cluster. +- A series of "destinations". A destination is a set of configuration that + specifies where a set of credentials should be output, and any options that + should be applied to those credentials (for example, what roles should be + impersonated). + +For more detail about the configuration options, see +[the reference.](./reference.mdx) + +On initial load, `tbot` uses the configured join method to obtain a set of +credentials for the bot user from the Teleport Auth Service. It can then use +these credentials to communicate with the Teleport Auth Service as the bot. On a configured regular period `tbot` begins its renewal process. It begins by refreshing the bot's own credentials, by renewing them or fetching a fresh set From e9ff2fd5bbf8016ad4d51b1d9d7d823ccd746791 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 15:10:50 +0100 Subject: [PATCH 25/26] Improve the way that the tbot section reads --- docs/pages/machine-id/architecture.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 3bdf9dd97b635..8ed6d92ee328f 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -64,11 +64,11 @@ On initial load, `tbot` uses the configured join method to obtain a set of credentials for the bot user from the Teleport Auth Service. It can then use these credentials to communicate with the Teleport Auth Service as the bot. -On a configured regular period `tbot` begins its renewal process. It begins by -refreshing the bot's own credentials, by renewing them or fetching a fresh set -of credentials depending on the configured onboarding method. +Then on a configured regular period `tbot` begins its renewal process. It begins +by refreshing the bot's own credentials, by renewing them or fetching a fresh +set of credentials depending on the configured onboarding method. -Then, for each destination provided in `tbot`'s configuration, `tbot` uses +For each destination provided in `tbot`'s configuration, `tbot` then uses impersonation to obtain credentials from the Auth Service for the roles specified in the destination's configuration. Once these are fetched, these are then persisted to the destination in various formats along with other useful @@ -76,8 +76,8 @@ matter such as the current certificate authority certificates. Concurrently to this, `tbot` monitors the Teleport certificate authorities to detect certificate rotations. When this occurs, it triggers additional renewals -to ensure that `tbot` has certificates signed by the newly rotated certificate -authority. +to ensure that destination's continue to have certificates that are signed by +the latest certificate authority. ## Onboarding From e653aca3d17063579f5a1492e6a93a8c126114c5 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Tue, 30 Aug 2022 16:04:44 +0100 Subject: [PATCH 26/26] Add notes on daemon vs oneshot. --- docs/pages/machine-id/architecture.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/pages/machine-id/architecture.mdx b/docs/pages/machine-id/architecture.mdx index 8ed6d92ee328f..b07c04e116bd2 100644 --- a/docs/pages/machine-id/architecture.mdx +++ b/docs/pages/machine-id/architecture.mdx @@ -44,7 +44,13 @@ permissions to impersonate the roles that the user has configured. ## `tbot` -`tbot` is the binary that acts as the agent for Machine ID. +`tbot` is the binary that acts as the agent for Machine ID on your machines that +need access to resources protected by Teleport. It is typically ran in one of +two modes. By default, it is a daemon-like long-running process. This is +suitable for situations where your machine is long running and will need +continous access to resources. `tbot` can also run in "oneshot" mode where it +will fetch credentials for your machine once before exiting. This is ideal for +short-lived environments such as CI/CD workflows. Before `tbot` can be started, at least two parts of configuration will need to be provided via the configuration file or as arguments provided to `tbot` when