Include Machine ID instructions in plugin guides (gravitational#35429)

* Include Machine ID instructions in plugin guides Closes gravitational#15062 This change incorporates Machine ID instructions into how-to guides for Teleport plugins. The alternative was to write a separate guide for using Machine ID with plugins. However, the current how-to guides assume that the user is providing long-lived credentials via `tctl`, so it makes sense to modify the instructions in these guides. Otherwise, a user would need to get familiar with the Machine ID guide, then work out for themselves which parts of the how-to guides are relevant or not. - Use a partial for the initial plugin config as well as for a Machine ID prerequisite. - Add partial for providing identity files via Machine ID. - Edit impersonation partials to mention Machine ID. - Add a `refresh-plugin-identity.mdx` partial for configuring plugins to periodically refresh their identities. - Make Access Request plugin guides more consistent with how they use the identity-export.mdx partial. * Fix "susceptible" usage Responds to zmb3 feedback * Respond to strideynet feedback Change Event Handler instructions to mention the `teleport-refresh-enabled` flag instead of a config option. * Fix spelling issue
ean · Dec 11, 2023 · 5f26498 · 5f26498
1 parent 49477f2
commit 5f26498
Show file tree

Hide file tree

Showing 17 changed files with 220 additions and 126 deletions.
diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx
@@ -21,6 +21,8 @@ compromising productivity.
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
+(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
+
 - Admin account on your Discord server. Installing a bot requires at least the
   "manager server" permission.
 - Either a Linux host or Kubernetes cluster where you will run the Discord plugin.
@@ -45,29 +47,17 @@ in your Teleport cluster.
 
 ## Step 4/8. Export the access plugin identity
 
-(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)
+Give the plugin access to a Teleport identity file. We recommend using Machine
+ID for this in order to produce short-lived identity files that are less
+dangerous if exfiltrated, though in demo deployments, you can generate
+longer-lived identity files with `tctl`:
 
 <Tabs>
-<TabItem label="Virtual Machine">
-
-The rest of this guide assumes that you have placed any files generated by this
-command into `/var/lib/teleport/plugins/discord` for later reference when
-configuring the plugin:
-
-```code
-# create a data directory to hold certificate files for the plugin.
-$ sudo mkdir -p /var/lib/teleport/plugins/discord
-$ sudo mv auth.* /var/lib/teleport/plugins/discord
-```
+<TabItem label="Machine ID">
+(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-plugin-discord-identity"!)
 </TabItem>
-<TabItem label="Kubernetes">
-
-Create a Kubernetes secret that contains the Teleport identity file:
-
-```code
-$ kubectl -n teleport create secret generic --from-file=auth.pem teleport-plugin-discord-identity
-```
-
+<TabItem label="Long-lived identity files">
+(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin" secret="teleport-plugin-discord-identity"!)
 </TabItem>
 </Tabs>
 
@@ -159,6 +149,8 @@ The Discord plugin uses this section to connect to the Teleport Auth Service.
 
 (!docs/pages/includes/plugins/config-toml-teleport.mdx!)
 
+(!docs/pages/includes/plugins/refresh-plugin-identity.mdx!)
+
 **`[discord]`**
 
 `token`: Paste the bot token saved previously in this field.

diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx
@@ -15,6 +15,8 @@ letting you implement security best practices without compromising productivity.
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
+(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
+
 - Access to an SMTP service. The Teleport email plugin supports either Mailgun
   or a generic SMTP service that authenticates via username and password.
 - Either a Linux host or Kubernetes cluster where you will run the email plugin.
@@ -59,29 +61,17 @@ because the plugin dials out to the Teleport Proxy Service or Teleport Auth Serv
 
 ## Step 4/7. Export the access plugin identity
 
-(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)
+Give the plugin access to a Teleport identity file. We recommend using Machine
+ID for this in order to produce short-lived identity files that are less
+dangerous if exfiltrated, though in demo deployments, you can generate
+longer-lived identity files with `tctl`:
 
 <Tabs>
-<TabItem label="Virtual Machine">
-
-The rest of this guide assumes that you have placed any files generated by this
-command into `/var/lib/teleport/plugins/email` for later reference when
-configuring the plugin:
-
-```code
-# create a data directory to hold certificate files for the plugin.
-$ sudo mkdir -p /var/lib/teleport/plugins/email
-$ sudo mv auth.* /var/lib/teleport/plugins/email
-```
+<TabItem label="Machine ID">
+(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-plugin-email-identity"!)
 </TabItem>
-<TabItem label="Kubernetes">
-
-Create a Kubernetes secret that contains the Teleport identity file:
-
-```code
-$ kubectl -n teleport create secret generic --from-file=auth.pem teleport-plugin-email-identity
-```
-
+<TabItem label="Long-lived identity files">
+(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin" secret="teleport-plugin-email-identity" !)
 </TabItem>
 </Tabs>
 
@@ -126,6 +116,8 @@ each value below.
 
 (!docs/pages/includes/plugins/config-toml-teleport.mdx!)
 
+(!docs/pages/includes/plugins/refresh-plugin-identity.mdx!)
+
 ### `[mailgun]` or `[smtp]`
 
 Provide the credentials for your SMTP service depending on whether you are using

diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx
@@ -21,6 +21,8 @@ compromising productivity.
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
+(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
+
 - A Mattermost account with admin privileges. This plugin has been tested with
   Mattermost v7.0.1.
 - Either a Linux host or Kubernetes cluster where you will run the Teleport Mattermost plugin.
@@ -63,29 +65,17 @@ Teleport Proxy Service and your Mattermost deployment.
 
 ## Step 4/8. Export the access plugin identity
 
-(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)
+Give the plugin access to a Teleport identity file. We recommend using Machine
+ID for this in order to produce short-lived identity files that are less
+dangerous if exfiltrated, though in demo deployments, you can generate
+longer-lived identity files with `tctl`:
 
 <Tabs>
-<TabItem label="Virtual Machine">
-
-The rest of this guide assumes that you have placed any files generated by this
-command into `/var/lib/teleport/plugins/mattermost` for later reference when
-configuring the plugin:
-
-```code
-# create a data directory to hold certificate files for the plugin.
-$ sudo mkdir -p /var/lib/teleport/plugins/mattermost
-$ sudo mv auth.* /var/lib/teleport/plugins/mattermost
-```
+<TabItem label="Machine ID">
+(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-plugin-mattermost-identity"!)
 </TabItem>
-<TabItem label="Kubernetes">
-
-Create a Kubernetes secret that contains the Teleport identity file:
-
-```code
-$ kubectl -n teleport create secret generic --from-file=auth.pem teleport-plugin-mattermost-identity
-```
-
+<TabItem label="Long-lived identity files">
+(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin" secret="teleport-plugin-mattermost-identity"!)
 </TabItem>
 </Tabs>
 
@@ -156,6 +146,8 @@ Edit the configuration as explained below:
 
 (!docs/pages/includes/plugins/config-toml-teleport.mdx!)
 
+(!docs/pages/includes/plugins/refresh-plugin-identity.mdx!)
+
 ### `[mattermost]`
 
 **`url`**: Include the scheme (`https://`) and fully qualified domain name of

diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx
@@ -15,6 +15,8 @@ compromising productivity.
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
+(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
+
 - A Microsoft Teams License (Microsoft 365 Business).
 - Azure console access in the organization/directory holding the Microsoft Teams
   License.
@@ -53,29 +55,17 @@ to generate an application archive to upload later in this guide.
 
 ## Step 4/9. Export the access plugin identity
 
-(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)
+Give the plugin access to a Teleport identity file. We recommend using Machine
+ID for this in order to produce short-lived identity files that are less
+dangerous if exfiltrated, though in demo deployments, you can generate
+longer-lived identity files with `tctl`:
 
 <Tabs>
-<TabItem label="Virtual Machine">
-
-The rest of this guide assumes that you have placed any files generated by this
-command into `/var/lib/teleport/plugins/msteams` for later reference when
-configuring the plugin:
-
-```code
-# create a data directory to hold certificate files for the plugin.
-$ sudo mkdir -p /var/lib/teleport/plugins/msteams
-$ sudo mv auth.* /var/lib/teleport/plugins/msteams
-```
+<TabItem label="Machine ID">
+(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-plugin-msteams-identity"!)
 </TabItem>
-<TabItem label="Kubernetes">
-
-Create a Kubernetes secret that contains the Teleport identity file:
-
-```code
-$ kubectl -n teleport create secret generic --from-file=auth.pem teleport-plugin-msteams-identity
-```
-
+<TabItem label="Long-lived identity files">
+(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin" secret="teleport-plugin-msteams-identity"!)
 </TabItem>
 </Tabs>
 
@@ -245,6 +235,8 @@ cluster.
 
 (!docs/pages/includes/plugins/config-toml-teleport.mdx!)
 
+(!docs/pages/includes/plugins/refresh-plugin-identity.mdx!)
+
 #### `[msapi]`/`msTeams`
 
 <Tabs>

diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx
@@ -28,6 +28,8 @@ PagerDuty.
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
+(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
+
 - A PagerDuty account with the "Admin", "Global Admin", or "Account Owner"
   roles. These roles are necessary for generating an API token that can list and
   look up user profiles.
@@ -369,29 +371,17 @@ Teleport cluster.
 
 ## Step 4/8. Export the access plugin identity
 
-(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)
+Give the plugin access to a Teleport identity file. We recommend using Machine
+ID for this in order to produce short-lived identity files that are less
+dangerous if exfiltrated, though in demo deployments, you can generate
+longer-lived identity files with `tctl`:
 
 <Tabs>
-<TabItem label="Virtual Machine">
-
-The rest of this guide assumes that you have placed any files generated by this
-command into `/var/lib/teleport/plugins/pagerduty` for later reference when
-configuring the plugin:
-
-```code
-# create a data directory to hold certificate files for the plugin.
-$ sudo mkdir -p /var/lib/teleport/plugins/pagerduty
-$ sudo mv auth.* /var/lib/teleport/plugins/pagerduty
-```
+<TabItem label="Machine ID">
+(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-plugin-pagerduty-identity"!)
 </TabItem>
-<TabItem label="Kubernetes">
-
-Create a Kubernetes secret that contains the Teleport identity file:
-
-```code
-$ kubectl -n teleport create secret generic --from-file=auth.pem teleport-plugin-pagerduty-identity
-```
-
+<TabItem label="Long-lived identity files">
+(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin" secret="teleport-plugin-pagerduty-identity"!)
 </TabItem>
 </Tabs>
 
@@ -460,6 +450,8 @@ The PagerDuty plugin uses this section to connect to your Teleport cluster:
 
 (!docs/pages/includes/plugins/config-toml-teleport.mdx!)
 
+(!docs/pages/includes/plugins/refresh-plugin-identity.mdx!)
+
 ### `[pagerduty]`
 
 Assign `api_key` to the PagerDuty API key you generated earlier.

diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx
@@ -37,6 +37,8 @@ Here is an example of sending an Access Request via Teleport's Slack plugin:
 
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
+(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
+
 - Slack admin privileges to create an app and install it to your workspace. Your
   Slack profile must have the "Workspace Owner" or "Workspace Admin" banner
   below your profile picture.
@@ -63,29 +65,17 @@ in your Teleport cluster.
 
 ## Step 4/8. Export the access plugin identity
 
-(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)
+Give the plugin access to a Teleport identity file. We recommend using Machine
+ID for this in order to produce short-lived identity files that are less
+dangerous if exfiltrated, though in demo deployments, you can generate
+longer-lived identity files with `tctl`:
 
 <Tabs>
-<TabItem label="Virtual Machine">
-
-The rest of this guide assumes that you have placed any files generated by this
-command into `/var/lib/teleport/plugins/slack` for later reference when
-configuring the plugin:
-
-```code
-# create a data directory to hold certificate files for the plugin.
-$ sudo mkdir -p /var/lib/teleport/plugins/slack
-$ sudo mv auth.* /var/lib/teleport/plugins/slack
-```
+<TabItem label="Machine ID">
+(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-plugin-slack-identity"!)
 </TabItem>
-<TabItem label="Kubernetes">
-
-Create a Kubernetes secret that contains the Teleport identity file:
-
-```code
-$ kubectl -n teleport create secret generic --from-file=auth.pem teleport-plugin-slack-identity
-```
-
+<TabItem label="Long-lived identity files">
+(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin" secret="teleport-plugin-slack-identity"!)
 </TabItem>
 </Tabs>
 
@@ -199,6 +189,8 @@ The Slack plugin uses this section to connect to your Teleport cluster:
 
 (!docs/pages/includes/plugins/config-toml-teleport.mdx!)
 
+(!docs/pages/includes/plugins/refresh-plugin-identity.mdx!)
+
 **`[slack]`**
 
 `token`: Open [`https://api.slack.com/apps`](https://api.slack.com/apps), find

diff --git a/docs/pages/includes/machine-id/plugin-prerequisites.mdx b/docs/pages/includes/machine-id/plugin-prerequisites.mdx
@@ -0,0 +1,6 @@
+**Recommended:** Configure Machine ID to provide short-lived Teleport
+credentials to the plugin. Before following this guide, follow a Machine ID
+[deployment guide](../../machine-id/deployment.mdx) to run the `tbot` binary on
+your infrastructure.
+
+
diff --git a/docs/pages/includes/plugins/machine-id-exporter-config.mdx b/docs/pages/includes/plugins/machine-id-exporter-config.mdx
@@ -0,0 +1,4 @@
+If you are providing credentials to the Event Handler using a `tbot` binary that
+runs on a Linux server, make sure the value of `identity` in the Event Handler
+configuration is the same as the path of the identity file you configured `tbot`
+to generate, `/opt/machine-id`.
diff --git a/docs/pages/includes/plugins/rbac-impersonate-event-handler.mdx b/docs/pages/includes/plugins/rbac-impersonate-event-handler.mdx
@@ -32,8 +32,9 @@ Next, create the role:
 $ tctl create teleport-event-handler-impersonator.yaml
 ```
 
-Add this role to the user that generates signed credentials for the Event
-Handler:
+If you are using Machine ID to provide short-lived credentials to the Event
+Handler, add this role to the Machine ID bot user. Otherwise, add this role to
+the user that generates signed credentials for the Event Handler:
 
 (!docs/pages/includes/add-role-to-user.mdx role="teleport-event-handler-impersonator"!)
 
diff --git a/docs/pages/includes/plugins/rbac-impersonate.mdx b/docs/pages/includes/plugins/rbac-impersonate.mdx
@@ -31,7 +31,12 @@ Create the `access-plugin-impersonator` role:
 $ tctl create -f access-plugin-impersonator.yaml
 ```
 
+If you are providing identity files to the plugin with Machine ID, assign the
+`access-plugin` role to the Machine ID bot user. Otherwise, assign this role to
+the user you plan to use to generate credentials for the `access-plugin` role
+and user:
+
 (!docs/pages/includes/add-role-to-user.mdx role="access-plugin-impersonator"!)
 
 You will now be able to generate signed certificates for the `access-plugin`
-role and user.
+role and user.
diff --git a/docs/pages/includes/plugins/refresh-plugin-identity.mdx b/docs/pages/includes/plugins/refresh-plugin-identity.mdx
@@ -0,0 +1,13 @@
+If you are providing credentials to the plugin using a `tbot` binary that runs
+on a Linux server, make sure the value of `identity` is the same as the path of
+the identity file you configured `tbot` to generate, `/opt/machine-id`.
+
+Configure the plugin to periodically reload the identity file, ensuring that it
+does not attempt to connect to the Teleport Auth Service with expired
+credentials.
+
+Add the following to the `teleport` section of the configuration:
+
+```toml
+refresh_identity = true
+```