Edit the Mattermost guide

Fixes #14577

Update the guide and make it easier to use:

- Give this guide the structure of the Slack guide, adding stepped
  headings and a section on configuring Access Requests, to make this
  guide easier to follow step by step.
- Add the initial Access Request RBAC setup as a partial
- Indicate that this has been tested with Mattermost v7.0.1
- Add clarity tweaks throughout
- Update the instructions for editing the plugin configuration. The
  configuration fields have changed since guide was written.

docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx

@@ -1,12 +1,15 @@
 ---
-title: Teleport integration with Mattermost
-description: This guide explains how to setup a Mattermost plugin for Teleport for privilege elevation approvals.
-h1: Teleport Mattermost Plugin Setup
+title: Access Requests with Mattermost
+description: How to set up Teleport's Mattermost plugin for privilege elevation approvals.
 ---
 
-This guide will explain how to set up Teleport with Mattermost, an open source messaging platform. Teleport's Mattermost integration allows teams to approve or deny Teleport Access Requests using Mattermost.
+This guide will explain how to set up Teleport with Mattermost, an open source
+messaging platform. Teleport's Mattermost integration allows teams to approve or
+deny Teleport Access Requests using Mattermost, making it easier to implement
+security best practices without compromising productivity.
 
-#### Example Mattermost request
+Here is example of sending an Access Request via Teleport's Mattermost
+plugin:
 
 <video controls>
   <source
@@ -22,59 +25,38 @@ This guide will explain how to set up Teleport with Mattermost, an open source m
   Your browser does not support the video tag.
 </video>
 
-## Setup
+## Prerequisites
 
-### Prerequisites
+(!/docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
-This guide assumes that you have:
-
-- A running Teleport Cluster
-- Admin privileges with access to `tctl`
-- A Mattermost account with admin privileges. This plugin has been tested with Mattermost 5.x
-
-Teleport Cloud requires that plugins connect through the Proxy Service (`mytenant.teleport.sh:443`). Open Source and Enterprise installations can connect to the Auth Service (`auth.example.com:3025`) directly.
+- A Mattermost account with admin privileges. This plugin has been tested with
+  Mattermost v7.0.1.
 
 (!docs/pages/includes/tctl.mdx!)
 
-### Setting up Mattermost to work with the bot
-
-![Enable Mattermost bots](../../../img/enterprise/plugins/mattermost/mattermost_admin_console_integrations_bot_accounts.png)
-
-In Mattermost, go to System Console → Integrations → Enable Bot Account Creation → Set to True.
-This will allow you to create a new bot account that the Teleport bot will use.
-
-Go back to your team, then Integrations → Bot Accounts → Add Bot Account.
-
-The new bot account will need Post All permission.
-
-**App Icon:** <a href="../../../img/enterprise/plugins/[email protected]" download>Download Teleport Bot Icon</a>
-
-![Enable Mattermost Bots](../../../img/enterprise/plugins/mattermost/mattermost_bot.png)
-
-### Create an OAuth 2.0 application
+## Step 1/8. Define RBAC resources
 
-In Mattermost, go to System Console → Integrations → OAuth 2.0 Applications.
+Before you set up the Mattermost plugin, you will need to enable Role Access
+Requests in your Teleport cluster.
 
-- Set Callback URLs to the location of your Teleport Proxy
+(!/docs/pages/includes/plugins/editor-request-rbac.mdx!)
 
-![Create OAuth Application](../../../img/enterprise/plugins/mattermost/mattermost_OAuth_token.png)
+## Step 2/8. Install the Teleport Mattermost plugin
 
-The confirmation screen after you've created the bot will give you the access token.
-We'll use this in the config later.
+<ScopedBlock scope={["enterprise", "oss"]}>
 
-### Create User and Role resources for access
-(!docs/pages/includes/plugins/rbac.mdx!)
+We recommend installing Teleport plugins on the same host as the Teleport Proxy
+Service. This is an ideal location as plugins have a low memory footprint, and
+will require both public internet access and Teleport Auth Service access. 
 
-### Export access-plugin Certificate
-(!docs/pages/includes/plugins/identity-export.mdx!)
+</ScopedBlock>
 
-We'll reference these files later when [configuring the plugins](#configuring-mattermost-bot).
+<ScopedBlock scope="cloud">
 
-## Downloading and installing the plugin
+Install the Teleport Mattermost plugin on a host that can access both your
+Teleport Cloud tenant and your Mattermost deployment.
 
-We recommend installing the Teleport Plugins alongside the Teleport Proxy. This is an ideal
-location as plugins have a low memory footprint, and will require both public internet access
-and Teleport Auth Service access. 
+</ScopedBlock>
 
 <Tabs>
 <TabItem label="Download">
@@ -103,64 +85,240 @@ Run `./install` from `teleport-mattermost` or place the executable in the approp
 </TabItem>
 </Tabs>
 
-### Configuring Mattermost bot
+## Step 3/8. Create a user and role for the plugin
+
+(!docs/pages/includes/plugins/rbac.mdx!)
+
+## Step 4/8. Export the access plugin identity
 
-Mattermost Bot uses a config file in TOML format. Generate a boilerplate config by
-running the following command:
+(!docs/pages/includes/plugins/identity-export.mdx!)
+
+## Step 5/8. Register a Mattermost bot
+
+Now that you have generated the credentials your plugin needs to connect to your
+Teleport cluster, register your plugin with Mattermost so it can send Access
+Request messages to your workspace.
+
+In Mattermost, click the menu button in the upper left of the UI, then click
+System Console → Integrations → Bot Accounts. 
+
+Set "Enable Bot Account Creation" to "true".
+
+![Enable Mattermost bots](../../../img/enterprise/plugins/mattermost/mattermost_admin_console_integrations_bot_accounts.png)
+
+This will allow you to create a new bot account for the Mattermost plugin.
+
+Go back to your team. In the menu on the upper left of the UI, click
+Integrations → Bot Accounts → Add Bot Account.
+
+Set the "Username", "Display Name", and "Description" fields according to how
+you would like the Mattermost plugin bot to appear in your workspace. Set "Role"
+to "Member".
+
+You can <a href="../../../img/enterprise/plugins/[email protected]"
+download>download</a> our avatar to set as your Bot Icon.
+
+Set "post:all" to "Enabled".
+
+![Enable Mattermost Bots](../../../img/enterprise/plugins/mattermost/mattermost_bot.png)
+
+Click "Create Bot Account". We will use the resulting OAuth 2.0 token when we
+configure the Mattermost plugin.
+
+## Step 6/8. Configure the Mattermost plugin
+
+At this point, you have generated credentials that the Mattermost plugin will use
+to connect to Teleport and Mattermost. You will now configure the Mattermost
+plugin to use these credentials and post messages in the right channels for your
+workspace.
+
+The Mattermost plugin usess a config file in TOML format. On the host where you
+will run the Mattermost plugin, generate a boilerplate config by running the
+following commands:
 
 ```code
 $ teleport-mattermost configure > teleport-mattermost.toml
 $ sudo mv teleport-mattermost.toml /etc
 ```
 
-Then, edit the config as needed.
+Edit the configuration as explained below:
+
+### `[teleport]`
+
+<Tabs>
+<TabItem label="Teleport Enterprise" scope={["oss", "enterprise"]}>
+
+**`addr`**: Include the hostname and HTTPS port of your Teleport Proxy Service
+(e.g., `mytenant.teleport.sh:443`). If you are configuring your plugin to
+connect directly to the Teleport Auth Service, use your Auth Service's gRPC
+endpoint (e.g., `teleport.example.com:3025`).
+
+**`identity`**, **`client_key`**, **`client_crt`**, **`root_cas`**: The values
+you will use for these fields depend on whether the Mattermost plugin will
+connect to the Proxy Service or the Auth Service. 
+
+If you exported an identity file earlier, fill in the `identity` field with the
+path to the file and comment out the other fields.
+
+If you exported a client key, client certificate, and root CAs earlier, fill in
+the `client_key`, `client_crt`, and `root_cas` fields with the paths to these
+files and leave `identity` commented out.
+
+</TabItem>
+<TabItem label="Teleport Cloud" scope="cloud">
+
+**`addr`**: Include the hostname and HTTPS port of your Teleport Cloud tenant
+(e.g., `mytenant.teleport.sh:443`).
+
+**`identity`**, **`client_key`**, **`client_crt`**, **`root_cas`**: Fill in the
+`identity` field with the path to the identity file you exported earlier and
+comment out the other fields.
+
+</TabItem>
+</Tabs>
+
+
+### `[mattermost]`
+
+**`url`**: Include the scheme (`https://`) and fully qualified domain name of
+your Mattermost deployment.
+
+**`token`**: Find your Mattermost bot's OAuth 2.0 token. To do so, visit
+Mattermost. In the menu on the upper left of the UI, go to Integrations → Bot
+Accounts. Find the listing for the Teleport plugin and click "Create New Token".
+After you save the token, you will see a message with text in the format,
+"Access Token: TOKEN". Copy the token and paste it here.
+
+**`recipients`**: This field configures the channels that the Mattermost plugin
+will notify when it receives an Access Request message. The value is an array of
+strings, where each element is either:
+
+- The email address of a Mattermost user to notify via a direct message when the
+  plugin receives an Access Request event
+- A channel name in the format `team/channel`, where `/` separates the name
+  of the team and the name of the channel
+
+For example, this configuration will notify `[email protected]` and
+the `Town Square` channel in the `myteam` team of any Access Request events:
+
+```toml
+recipients = [
+  "myteam/Town Square",
+  "[email protected]"
+]
+```
+
+You will need to invite your Teleport plugin to any channel you add to the
+`recipients` list (aside from direct message channels). Visit Mattermost,
+navigate to each channel you want to invite the plugin to, and enter `/invite
+@teleport` (or the name of the bot you configured) into the message box.
+
+![Invite the bot](../../../img/enterprise/plugins/mattermost/add-bot.png)
+
+<Details title="Suggested reviewers">
+
+Users can also suggest reviewers when they create an Access Request, e.g.,:
+
+```code
+$ tsh request create --roles=dbadmin [email protected],[email protected]
+```
+
+If an Access Request includes suggested reviewers, the Mattermost plugin will
+add these to the list of channels to notify. If a suggested reviewer is an email
+address, the plugin will look up the the direct message channel for that address
+and post a message in that channel.
+
+If `recipients` is empty, and the user requesting elevated privileges has not
+suggested any reviewers, the plugin will skip forwarding the Access Request to
+Mattermost.
+
+</Details>
+
+The final configuration should look similar to this:
 
 <Tabs>
-<TabItem scopes={["oss", "enterprise"]} label="Self-Hosted">
+<TabItem scopes={["cloud"]} label="Connect to the Proxy Service">
 ```yaml
-(!examples/resources/plugins/teleport-mattermost-self.toml!)
+(!examples/resources/plugins/teleport-mattermost-cloud.toml!)
 ```
 </TabItem>
-<TabItem scopes={["cloud"]} label="Cloud">
+<TabItem scopes={["oss", "enterprise"]} label="Connect to the Auth Service">
 ```yaml
-(!examples/resources/plugins/teleport-mattermost-cloud.toml!)
+(!examples/resources/plugins/teleport-mattermost-self.toml!)
 ```
 </TabItem>
 </Tabs>
 
-### Testing the plugin
+## Step 7/8. Test your Mattermost bot
 
-With the config above, you should be able to run the bot invoking
-`teleport-mattermost start -d`. The will provide some debug information to make sure
-the bot can connect to Mattermost.
+After modifying your configuration, run the bot with the following command:
 
 ```code
 $ teleport-mattermost start -d
-# DEBU   DEBUG logging enabled logrus/exported.go:117
-# INFO   Starting Teleport Access Mattermost Bot (=teleport.plugin.version=)-dev.1: mattermost/main.go:140
-# DEBU   Checking Teleport server version mattermost/main.go:234
-# DEBU   Starting a request watcher... mattermost/main.go:296
-# DEBU   Starting Mattermost API health check... mattermost/main.go:186
-# DEBU   Starting secure HTTPS server on :8081 utils/http.go:146
-# DEBU   Watcher connected mattermost/main.go:260
-# DEBU   Mattermost API health check finished ok mattermost/main.go:19
 ```
 
-### Set up with SystemD
+The `-d` flag provides debug information to make sure the bot can connect to
+Mattermost, e.g.:
+
+```text
+DEBU   Checking Teleport server version mattermost/main.go:234
+DEBU   Starting a request watcher... mattermost/main.go:296
+DEBU   Starting Mattermost API health check... mattermost/main.go:186
+DEBU   Starting secure HTTPS server on :8081 utils/http.go:146
+DEBU   Watcher connected mattermost/main.go:260
+DEBU   Mattermost API health check finished ok mattermost/main.go:19
+```
+
+### Create an Access Request
+
+(!docs/pages/includes/plugins/create-request.mdx!)
 
-In production, we recommend starting the Teleport plugin daemon via an init system like systemd. Here's the recommended Teleport plugin service unit file for systemd:
+The users and channels you configured earlier to review the request should
+receive a message from "Teleport" in Mattermost allowing them to visit a link in
+the Teleport Web UI and either approve or deny the request.
+
+### Resolve the request
+
+(!docs/pages/includes/plugins/resolve-request.mdx!)
+
+<Admonition title="Auditing Access Requests">
+
+When the Mattermost plugin posts an Access Request notification to a channel,
+anyone with access to the channel can view the notification and follow the link.
+While users must be authorized via their Teleport roles to review Access
+Requests, you should still check the Teleport audit log to ensure that the right
+users are reviewing the right requests.
+
+When auditing Access Request reviews, check for events with the type `Access
+Request Reviewed` in the Teleport Web UI <ScopedBlock scope={["oss",
+"enterprise"]}>and `access_request.review` if reviewing the audit log on the
+Auth Service host</ScopedBlock>.
+
+</Admonition>
+
+## Step 8/8. Set up systemd
+
+In production, we recommend starting the Teleport plugin daemon via an init
+system like systemd. Here's the recommended Teleport plugin service unit file
+for systemd:
 
 ```ini
 (!examples/systemd/plugins/teleport-mattermost.service!)
 ```
 
-Save this as `teleport-mattermost.service`.
+Save this as `teleport-mattermost.service` in either `/usr/lib/systemd/system/` or
+another [unit file load
+path](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20File%20Load%20Path)
+supported by systemd.
 
-## Audit log
+Enable and start the plugin:
 
-The plugin will let anyone with access to the Mattermost channel requests so it's
-important to review Teleport's audit log.
+```code
+$ sudo systemctl enable teleport-mattermost
+$ sudo systemctl start teleport-mattermost
+```
 
 ## Feedback
 
-If you have any issues with this plugin please create an [issue here](https://github.com/gravitational/teleport-plugins/issues/new).
+If you have any issues with this plugin, please create an [issue
+on GitHub](https://github.com/gravitational/teleport-plugins/issues/new).

docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx

@@ -493,7 +493,7 @@ was approved or denied.
 <Admonition title="Auditing Access Requests">
 
 When the Slack plugin posts an Access Request notification to a channel, anyone
-with access to the channel can view the notification and follow the link. While
+with access to the channel can view the notification and follow the link.  While
 users must be authorized via their Teleport roles to review Access Requests, you
 should still check the Teleport audit log to ensure that the right users are
 reviewing the right requests.

examples/resources/plugins/teleport-mattermost-cloud.toml

@@ -5,16 +5,11 @@ identity = "/var/lib/teleport/plugins/mattermost/auth.pem"   # Identity file pat
 
 [mattermost]
 url = "https://mattermost.example.com" # Mattermost Server URL
-team = "team-name"                     # Mattermost team in which the channel resides.
-channel = "channel-name"               # Mattermost Channel name to post requests to
 token = "api-token"                    # Mattermost Bot OAuth token
-secret = "signing-secret-value"        # Mattermost API signing Secret
-
-[http]
-public_addr = "example.com" # URL on which callback server is accessible externally, e.g. [https://]teleport-mattermost.example.com
-# listen_addr = ":8081" # Network address in format [addr]:port on which callback server listens, e.g. 0.0.0.0:443
-https_key_file = "/var/lib/teleport/plugins/mattermost/server.key"  # TLS private key
-https_cert_file = "/var/lib/teleport/plugins/mattermost/server.crt" # TLS certificate
+recipients = [
+  "myteam/general",
+  "[email protected]"
+]
 
 [log]
 output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/mattermost.log"