opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-09-24 16:17:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Edit the Slack access request plugin guide (#14852)

Browse Source 
* Edit the Slack access request plugin guide

Fixes #14581

- Flesh out the intro a bit
- Fix the directory name used in the `mv` command in the installation
  step. Also fix the name of the binary generated by the `make` command.
- Add a step to test the installation
- Edit the rbac.mdx and impersonations.mdx partials to provide more
  context and restructure the instructions so users can follow them step
  by step.
- Add context around other existing steps
- Add more comprehensive role mapping instructions. The guide included
  an example role mapping, but did not spell out the general logic of
  the role mapping bheavior, e.g., that the "*" key is required.
- Move the step re: inviting the bot to after the user configures role
  mapping so they know which channels to invite the bot to.
- Add a section on creating roles to enable Access Requests so it is
  eassier to follow this guide linearly. Otherwise, users will need to
  do more work to match the configuration instructions with the
  specifics of their RBAC setup.
- Capitalize "Access Request" in this and other guides, since we're
  adding more emphasis on this as a product.
- Turn the "Audit Log" section into an Admonition and make the
  instructions there more accurate.
- Add context to the "identity-export.mdx" partial. This is a pretty
  confusing part of the Access Request setup process, so I added context
  to explain why different identity file formats are used.

* Apply suggestions from code review

Co-authored-by: Nic Klaassen <nic@goteleport.com>

* Respond to PR review

Co-authored-by: Nic Klaassen <nic@goteleport.com>
This commit is contained in:
Paul Gottschling
2022-08-01 14:44:23 +00:00
committed by GitHub
co-authored by Nic Klaassen
parent af5e2517de
commit ecdb9dfff7
19 changed files with 532 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/img/request-access.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 294 KiB

docs/img/review-request.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.9 MiB

docs/pages/access-controls/guides/dual-authz.mdx
+5 -5
View File
@@ -10,7 +10,7 @@ Here are the most common scenarios:
- Improve the security of your system and prevent one successful phishing attack from compromising your system.
- Satisfy FedRAMP AC-3 Dual authorization control that requires approval of two authorized individuals.
In this guide, we will set up Teleport's access requests to require the approval
In this guide, we will set up Teleport's Just-in-Time Access Requests to require the approval
of two team members for a privileged role `dbadmin`.
<ScopedBlock scope="oss">
@@ -171,11 +171,11 @@ $ tctl users add alice@example.com --roles=reviewer
$ tctl users add ivan@example.com --roles=reviewer
```
### Create an access request
### Create an Access Request
Bob does not have a role `dbadmin` assigned to him, but can create an access request for it.
Bob does not have a role `dbadmin` assigned to him, but can create an Access Request for it.
Bob can create an access request for the `dbadmin` role in the Web UI or CLI:
Bob can create an Access Request for the `dbadmin` role in the Web UI or CLI:
<Tabs>
<TabItem label="Web UI">
@@ -215,7 +215,7 @@ Alice and Ivan can review and approve request using Web UI or CLI:
</Tabs>
If Bob has created a request using CLI, he will assume it once it has been approved.
Bob can also assume granted access request roles using Web UI:
Bob can also assume granted Access Request roles using Web UI:
![Teleport Assume](../../../img/access-controls/dual-authz/teleport-7-bob-assume.png)
docs/pages/access-controls/guides/locking.mdx
+1 -1
View File
@@ -81,7 +81,7 @@ with one of the following options:
```
</TabItem>
<TabItem label="Access request">
All connections using elevated privileges from the matching access request will be locked.
All connections using elevated privileges from the matching Access Request will be locked.
```code
$ tctl lock --access-request=261e80c5-357b-4c43-9b67-40a6bc4c6e4d --ttl=24h
# Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1".
docs/pages/access-controls/reference.mdx
+2 -2
View File
@@ -106,8 +106,8 @@ The table below documents the behavior of each option if multiple roles are assi
| `permit_x11_forwarding` | Allow users to enable X11 forwarding with OpenSSH clients and servers | |
| `require_session_mfa` | Require additional MFA tap before initiating a session | Logical "OR" i.e. evaluates to "yes" if at least one role requires session MFA |
| `lock` | Locking mode (`strict` or `best_effort`) | `strict` wins in case of conflict |
| `request_access` | Enterprise-only access request strategy (`optional`, `always` or `reason`) | |
| `request_prompt` | Prompt for the access request "reason" field | |
| `request_access` | Enterprise-only Access Request strategy (`optional`, `always` or `reason`) | |
| `request_prompt` | Prompt for the Access Request "reason" field | |
| `max_connections` | Enterprise-only limit on how many concurrent sessions can be started via Teleport | |
| `max_kubernetes_connections` | Defines the maximum number of concurrent Kubernetes sessions per user | |
| `record_session` |Defines the [Session recording mode](../setup/reference/audit.mdx#modes).|The strictest value takes precedence.|
docs/pages/api/introduction.mdx
+1 -1
View File
@@ -15,7 +15,7 @@ Here is what you can do with the Go Client:
- Integrating with external tools, which we have already done
for [several tools](../enterprise/workflow/index.mdx#integrating-with-an-external-tool),
such as Slack, Jira, and Mattermost.
- Writing a program/bot to manage access requests automatically, based on your use case. One idea
- Writing a program/bot to manage Access Requests automatically, based on your use case. One idea
is to allow/deny developer requests based on their currently assigned tasks.
- Performing CRUD actions on resources, such as `roles`, `auth connectors`, and `provisioning tokens`.
- Dynamically configuring Teleport.
docs/pages/architecture/authorization.mdx
+1 -1
View File
@@ -353,7 +353,7 @@ or rejections are required:
spec:
allow:
# review_requests allows a user holding this role
# to approve or deny access requests
# to approve or deny Access Requests
review_requests:
roles: ['dbadmin']
docs/pages/database-access/introduction.mdx
+1 -1
View File
@@ -11,7 +11,7 @@ Some of the things you can do with Database Access:
- Users can retrieve short-lived database certificates using single sign-on
flow thus maintaining their organization-wide identity.
- Configure role-based access controls for databases and implement custom
[access request](../enterprise/workflow/index.mdx) workflows.
[Access Request](../enterprise/workflow/index.mdx) workflows.
- Capture database access events as well as query activity in the audit log.
Database Access currently supports the following databases:
docs/pages/enterprise/soc2.mdx
+1 -1
View File
@@ -36,7 +36,7 @@ Teleport helps audit and monitor access.
- Monitor, share and join interactive sessions in real-time from the CLI or browser.
### CC8 Change Management
Teleport helps users elevate their permissions during incidents, RBAC helps limit the need for approvals. The Teleport slack integration allows for managers to quickly approve temporary SSH access requests.
Teleport helps users elevate their permissions during incidents, RBAC helps limit the need for approvals. The Teleport slack integration allows for managers to quickly approve temporary SSH Access Requests.
- Let engineers request elevated permissions on the fly without ever leaving the terminal
- Approve or deny permission requests with ChatOps workflow via Slack or other supported platforms.
docs/pages/enterprise/workflow/index.mdx
+1 -1
View File
@@ -12,7 +12,7 @@ denied based on a configurable number of approvers.
Just-in-time Access Requests are a feature of Teleport Enterprise.
Open-source Teleport users can get a preview of how Access Requests work by
requesting a role via the Teleport CLI. Full access request functionality,
requesting a role via the Teleport CLI. Full Access Request functionality,
including Resource Access Requests and an intuitive and searchable UI are
available in Teleport Enterprise.
docs/pages/enterprise/workflow/resource-requests.mdx
+6 -6
View File
@@ -18,7 +18,7 @@ requests.
Just-in-time Access Requests are a feature of Teleport Enterprise.
Open-source Teleport users can get a preview of how Access Requests work by
requesting a role via the Teleport CLI. Full access request functionality,
requesting a role via the Teleport CLI. Full Access Request functionality,
including Resource Access Requests and an intuitive and searchable UI are
available in Teleport Enterprise.
@@ -169,7 +169,7 @@ Waiting for request approval...
The command will automatically wait until the request is approved.
## Step 6/8. Approve the access request
## Step 6/8. Approve the Access Request
First, log in as `bob`.
@@ -177,7 +177,7 @@ First, log in as `bob`.
$ tsh login --proxy teleport.example.com --user bob
```
Then list, review, and approve the access request.
Then list, review, and approve the Access Request.
```code
$ tsh request ls
@@ -206,7 +206,7 @@ Successfully submitted review. Request state: APPROVED
<Notice type="tip">
Check out our
[Access Request Integrations](#integrating-with-an-external-tool)
to notify the right people about new access requests.
to notify the right people about new Access Requests.
</Notice>
## Step 7/8. Access the requested resource
@@ -270,8 +270,8 @@ $ tsh request drop
### Automatically request access for SSH
Once you have configured resource access requests,
`tsh ssh` is able to automatically create a resource access request for you when access is denied,
Once you have configured Resource Access Requests,
`tsh ssh` is able to automatically create a Resource Access Request for you when access is denied,
allowing you to skip the `tsh request search` and `tsh request create` steps.
```code
docs/pages/enterprise/workflow/role-requests.mdx
+5 -5
View File
@@ -12,7 +12,7 @@ approve or deny these requests.
Just-in-time Access Requests are a feature of Teleport Enterprise.
Open-source Teleport users can get a preview of how Access Requests work by
requesting a role via the Teleport CLI. Full access request functionality,
requesting a role via the Teleport CLI. Full Access Request functionality,
including Resource Access Requests and an intuitive and searchable UI are
available in Teleport Enterprise.
@@ -157,7 +157,7 @@ deny:
When requesting a new role users can add provide a reason along with their request
`tsh login --request-roles="db" --request-reason="Need access to db"`.
By requiring a reason along with an access request, you can provide users with a default
By requiring a reason along with an Access Request, you can provide users with a default
unprivileged state where they must always go through the Access Requests API in order to
gain meaningful privilege.
@@ -188,7 +188,7 @@ spec:
- claim: groups
value: admins
roles: ['*']
# Teleport can attach annotations to pending access requests. these
# Teleport can attach annotations to pending Access Requests. these
# annotations may be literals, or be variable interpolation expressions,
# effectively creating a means for propagating selected claims from an
# external identity provider to the plugin system.
@@ -197,9 +197,9 @@ spec:
groups: ['{{external.groups}}']
options:
# the `request_access` field can be set to 'always' or 'reason' to tell
# tsh or the web UI to always create an access request on login. If it is
# tsh or the web UI to always create an Access Request on login. If it is
# set to 'reason', the user will be required to indicate *why* they are
# generating the access request.
# generating the Access Request.
request_access: reason
# the `request_prompt` field can be used to tell the user what should
# be supplied in the request reason field.
docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx
+1 -1
View File
@@ -154,7 +154,7 @@ Save this as `teleport-pagerduty.service`.
## On-call auto-approval
The PagerDuty plugin has an option to auto-approve access requests. This
The PagerDuty plugin has an option to auto-approve Access Requests. This
feature will map an external SSO identity to a PagerDuty on-call email address.
If the user requesting matches the person on call the request will be
automatically approved.
docs/pages/enterprise/workflow/ssh-approval-slack.mdx
+342 -104
View File
@@ -1,24 +1,15 @@
---
title: Teleport's integration with Slack
description: This guide explains how to setup a Slack plugin for Teleport for privilege elevation approvals.
h1: Teleport Slack Plugin Setup
title: Access Requests with Slack
description: How to set up Teleport's Slack plugin for privilege elevation approvals.
---
This guide will explain how to set up Teleport with Slack. Teleport's Slack
integration notifies individuals and channels of access requests.
This guide will explain how to set up Slack to receive Access Request messages
from Teleport. Teleport's Slack integration notifies individuals and channels of
Access Requests. Users can then approve and deny Access Requests from within
Slack, making it easier to implement security best practices without
compromising productivity.
<Notice
type="danger"
scope="oss"
>
This guide requires Teleport Cloud or Teleport Enterprise. The open source
edition of Teleport only supports [GitHub](../../setup/admin/github-sso.mdx)
as an SSO provider.
</Notice>
Here is an example of sending an access request via Teleport's Slack plugin:
Here is an example of sending an Access Request via Teleport's Slack plugin:
<video controls>
<source
@@ -36,16 +27,102 @@ Here is an example of sending an access request via Teleport's Slack plugin:
## Prerequisites
- Slack admin privileges to create an app and install it to your workspace
(!/docs/pages/includes/commercial-prereqs-tabs.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.
(!/docs/pages/includes/tctl.mdx!)
## Step 1/7. Install the Teleport Slack plugin
## Step 1/8. Define RBAC resources
We currently only provide `linux-amd64` binaries. You can also compile these plugins
from source.
Before you set up the Slack plugin, you will need to enable Access Requests in
your Teleport cluster. For the purpose of this guide, we will define an
`editor-requester` role, which can request the built-in `editor` role, and
an `editor-reviewer` role that can review requests for the `editor` role.
Create a file called `editor-request-rbac.yaml` with the following content:
```yaml
kind: role
version: v5
metadata:
name: editor-reviewer
spec:
allow:
review_requests:
roles: ['editor']
---
kind: role
version: v5
metadata:
name: editor-requester
spec:
allow:
request:
roles: ['editor']
thresholds:
- approve: 1
deny: 1
```
Create the roles you defined:
```code
$ tctl create -f editor-request-rbac.yaml
role 'editor-reviewer' has been created
role 'editor-requester' has been created
```
Allow yourself to review requests by users with the `editor-requester` role by
assigning yourself the `editor-reviewer` role. First, retrieve your user
definition:
```code
$ TELEPORT_USER=$(tsh status --format=json | jq -r .active.username)
$ tctl get user/${TELEPORT_USER?} > user.yaml
```
Edit `user.yaml` to add the `editor-reviewer` role:
```diff
spec:
roles:
- access
- editor
+ - editor-reviewer
```
Update your user definition:
```code
$ tctl create -f user.yaml
```
Log out of Teleport and log in again. You will now have the ability to review
requests for the `editor` role.
Create a user called `myuser` who has the `editor-requester` role as well as the
built-in `access` role and the `ubuntu` login. This user cannot edit your
cluster configuration unless they request the `editor` role:
```code
$ tctl users add myuser --roles=editor-requester
```
`tctl` will print an invitation URL to your terminal. Visit the URL and log in
as `myuser` for the first time, registering credentials as configured for your
Teleport cluster.
Later in this guide, you will have `myuser` request the `editor` role so you can
review the request using the Teleport plugin.
## Step 2/8. Install the Teleport Slack plugin
We currently only provide `linux-amd64` binaries. You can also compile these
plugins from source. You can run the plugin from a remote host or your local
development machine.
<Notice scope={["enterprise"]} type="tip">
We recommend installing Teleport plugins on the same host as the Teleport
@@ -62,7 +139,8 @@ and will require access to both the public internet and the Teleport Auth Servic
```
</TabItem>
<TabItem label="From Source">
To install from source you need `git` and `go >= (=teleport.golang=)` installed.
To install from source you need `git` and `go` >= (=teleport.golang=)
installed.
```code
# Check out the teleport-plugins repository
@@ -70,22 +148,35 @@ and will require access to both the public internet and the Teleport Auth Servic
$ cd teleport-plugins/access/slack
$ make
```
Place `./teleport-access-slack/teleport-slack` into an appropriate location within the system's PATH, e.g.`/usr/local/bin`.
```code
mv ./teleport-access-slack/teleport-slack /usr/local/bin
Place the `teleport-slack` binary into an appropriate location
within the sytem's `PATH`, e.g., `/usr/local/bin`:
```code
$ mv ./build/teleport-slack /usr/local/bin
```
</TabItem>
</TabItem>
</Tabs>
## Step 2/7. Create a user and role for the plugin
Make sure the binary is installed:
```code
$ teleport-slack version
teleport-slack v(=teleport.plugin.version=) git:teleport-slack-v(=teleport.plugin.version=)-fffffffff go(=teleport.golang=)
```
## Step 3/8. Create a user and role for the plugin
(!docs/pages/includes/plugins/rbac.mdx!)
## Step 3/7. Export the access plugin identity
## Step 4/8. Export the access plugin identity
(!docs/pages/includes/plugins/identity-export.mdx!)
Place any files generated by this command into `/var/lib/teleport/plugins/slack` for later reference when configuring the plugin.
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.
@@ -93,57 +184,87 @@ $ sudo mkdir -p /var/lib/teleport/plugins/slack
$ sudo mv auth.* /var/lib/teleport/plugins/slack
```
## Step 4/7. Create a Slack app
## Step 5/8. Register a Slack app
You'll need to:
The Access Request plugin for Slack receives Access Request events from the
Teleport Auth Service, formats them into Slack messages, and sends them to the
Slack API to post them in your workspace. For this to work, you must register a
new app with the Slack API.
1. Create a new app, pick a name, and select a workspace it belongs to.
2. Add an OAuth Scope, which is required by Slack for the app to be installed.
3. Obtain an OAuth token.
### Create your app
We'll create a new Slack app and set up auth tokens and callback URLs so that
Slack knows how to notify the Teleport plugin when "Approve" or "Deny" buttons are
clicked.
Visit [https://api.slack.com/apps](https://api.slack.com/apps) to create a new Slack App.
**App Name:** Teleport<br/>
**Development Slack Workspace:** Pick the workspace you'd like the requests to show up in. <br/>
**App Icon:** <a href="../../../img/enterprise/plugins/teleport_bot@2x.png" download>Download Teleport Bot Icon</a>
Visit [https://api.slack.com/apps](https://api.slack.com/apps) to create a new
Slack app. Click "Create an App", then "From scratch". Fill in the form as shown
below:
![Create Slack App](../../../img/enterprise/plugins/slack/Create-a-Slack-App.png)
### Select OAuth scopes
The "App Name" should be "Teleport". Click the "Development Slack Workspace"
dropdown and choose the workspace where you would like to see Access Request
messages.
On the App screen, go to “OAuth and Permissions” under Features in the sidebar menu. Then scroll to Scopes, and add `chat:write, incoming-webhook, users:read, users:read.email` scopes so that our plugin can post messages to your Slack channels.
### Generate an OAuth token with scopes
Next, configure your application to authenticate to the Slack API. We will do
this by generating an OAuth token that the plugin will present to the Slack API.
We will restrict the plugin to the norrowest possible permissions by using OAuth
scopes. The Slack plugin needs to post messages to your workspace. It also needs
to read usernames and email addresses in order to direct Access Request
notifications from the Auth Service to the appropriate Teleport users in Slack.
After creating your app, the Slack website will open a console where you can
specify configuration options. On the sidebar menu under "Features", click
"OAuth & Permissions".
Scroll to the "Scopes" section and click "Add an OAuth Scope" for each of the
following scopes:
- `chat:write`
- `incoming-webhook`
- `users:read`
- `users:read.email`
The result should look like this:
![API Scopes](../../../img/enterprise/plugins/slack/api-scopes.png)
### Obtain an OAuth token
After you have configured scopes for your plugin, scroll back to the top of the
OAuth & Permissions page, find the "OAuth Tokens for Your Workspace" section,
and click "Install to Workspace". You will see a summary of the permission you
configured for the Slack plugin earlier.
In "Where should Teleport post?", choose "Slackbot" as the default channel the
plugin will post to. The plugin will post here when sending direct messages.
Later in this guide, we will configure the plugin to post in other channels as
well.
After submitting this form, you will see an OAuth token in the "OAuth &
Permissions" tab under "Tokens for Your Workspace":
![OAuth Tokens](../../../img/enterprise/plugins/slack/OAuth.png)
### Add to workspace
You will use this token later when configuring the Slack plugin.
![OAuth Tokens](../../../img/enterprise/plugins/slack/Slackbot-Permissions.png)
After adding to the workspace, you still need to invite the bot to the channel. Do this by using the @ command,
and inviting them to the channel.
![Invite bot to channel](../../../img/enterprise/plugins/slack/invite-user-to-team.png)
## Step 6/8. Configure the Teleport Slack plugin
## Step 5/7. Configure the Teleport Slack Plugin
At this point, the Teleport Slack plugin has the credentials it needs to
communicate with your Teleport cluster and the Slack API. In this step, you will
configure the Slack plugin to use these credentials. You will also configure the
plugin to notify the right Slack channels when it receives an Access Request
update.
### Generate a config file
The Teleport Slack plugin uses a config file in TOML format. Generate a boilerplate config by
running the following command and place it in the `/etc` directory where it can be
read by the plugin.
The Teleport Slack plugin uses a config file in TOML format. Generate a
boilerplate config by running the following command (the plugin will not run
unless the config file is in `/etc/teleport-slack.toml`):
```code
$ teleport-slack configure > teleport-slack.toml
$ sudo mv teleport-slack.toml /etc
$ teleport-slack configure | sudo tee /etc/teleport-slack.toml > /dev/null
```
This should result in a config file like the one below.
This should result in a config file like the one below:
```toml
(!examples/resources/plugins/teleport-slack.toml!)
@@ -151,19 +272,26 @@ This should result in a config file like the one below.
### Edit the config file
Edit the following fields in the configuration file you generated with values specific to your Teleport and Slack app instances.
Edit the `teleport-slack.toml` file you created earlier to update the following
fields:
**`[teleport]`**
This section is used to connect to your Teleport Auth Server.
The Slack plugin uses this section to connect to the Teleport Auth Service.
<ScopedBlock scope={["oss", "enterprise"]}>
The address and credentials you configure depend on whether your plugin can
access the Auth Service directly:
<Tabs>
<TabItem label="Self-Hosted" scope={["oss","enterprise"]}>
<TabItem label="Connect to the Auth Service">
Set `addr` to your Auth Server address. This address must be reachable from the Teleport Slack Plugin.
Set `addr` to the address and port of your Auth Service. This address must be
reachable from the Teleport Slack Plugin.
Set `client_key`, `client_crt`, and `root_cas` to the identity files
generated in the [export identity](#step-37-export-the-access-plugin-identity) section.
generated earlier:
```toml
[teleport]
@@ -173,47 +301,115 @@ client_crt = "/var/lib/teleport/plugins/slack/auth.crt" # Teleport GRPC client c
root_cas = "/var/lib/teleport/plugins/slack/auth.cas" # Teleport cluster CA certs
```
</TabItem>
<TabItem label="Cloud" scope={["cloud"]}>
<TabItem label="Connect to the Proxy Service">
Set `addr` to your Teleport Cloud tenant address.
Set `addr` to your Proxy Service address with port `443`.
Set `identity` to the identity file generated in the [export identity](#step-37-export-the-access-plugin-identity) section.
Set `identity` to the identity file generated earlier:
```toml
[teleport]
addr = "mytenant.teleport.sh"
addr = "mytenant.teleport.sh:443"
identity = "/var/lib/teleport/plugins/slack/auth.pem"
```
</TabItem>
</Tabs>
</ScopedBlock>
<ScopedBlock scope="cloud">
Set `addr` to your Teleport Cloud tenant address with port `443`.
Set `identity` to the identity file generated earlier:
```toml
[teleport]
addr = "mytenant.teleport.sh:443"
identity = "/var/lib/teleport/plugins/slack/auth.pem"
```
</ScopedBlock>
**`[slack]`**
`token`: set this to the token found in the [Obtain an OAuth Token](#obtain-an-oauth-token) section.
`token`: Open [`https://api.slack.com/apps`](https://api.slack.com/apps), find
the Slack app you created earlier, navigate to the "OAuth & Permissions" tab,
copy the "Bot User OAuth Token", and paste it into this field.
**`[role_to_recipients]`**
Provide a mapping of Teleport roles to Slack recipients based on your desired
functionality.
The `role_to_recipients` map configure the channels that the Slack plugin will
notify when a user requests access to a specific role. When the Slack plugin
receives an Access Request from the Auth Service, it will look up the role being
requested and identify the Slack channels to notify.
For example:
Here is an example of a `role_to_recipients` map:
```toml
[role_to_recipients]
"*" = "admin-slack-channel"
"dev" = ["dev-slack-channel", "admin-slack-channel"]
"alex" = "alex@gmail.com"
"dba" = "alex@gmail.com"
```
If a user requests the `dev` role, the plugin will send a message to both the `dev-slack-channel`
and `admin-slack-channel`. If a user requests the `alex` role, the Slack user with the username
`alex@gmail.com`, if one exists, will receive a DM. If any other role is requested, the plugin will
follow the `*` entry and send a message to the `admin-slack-channel`.
In the `role_to_recipients` map, each key is the name of a Teleport role. Each
value configures the Slack channel (or channels) to notify. The value can be a
single string or an array of strings. Each string must be either the name of a
Slack channel (including a user's direct message channel) or the email address
of a Slack user. If the recipient is an email address, the Slack plugin will
use that email address to look up a direct message channel.
## Step 6/7. Test your Slack app
The `role_to_recipients` map must also include an entry for `"*"`, which the
plugin looks up if no other entry matches a given role name. In the example
above, requests for roles aside from `dev` and `dba` will notify the
`admin-slack-channel` channel.
Assuming that Teleport is running, you've created the Slack app, and the plugin is
configured, you can now run the plugin and test the workflow!
<Details title="Suggested reviewers">
Users can suggest reviewers when they create an Access Request, e.g.,:
```code
$ tsh request create --roles=dbadmin --reviewers=alice@example.com,ivan@example.com
```
If an Access Request includes suggested reviewers, the Slack 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.
</Details>
Configure the Slack plugin to notify you when a user requests the `editor` role
by adding the following to your `role_to_recipients` config (replace
`TELEPORT_USERNAME` with the user you assigned the `editor-reviewer` role
earlier):
```toml
[role_to_recipients]
"*" = "access-requests"
"editor" = "TELEPORT_USERNAME"
```
Either create an `access-requests` channel in your Slack workspace or rename the
value of the `"*"` key to an existing channel.
### Invite your Slack app
Once you have configured the channels that the Slack plugin will notify when it
receives an Access Request, you will need to ensure that the plugin can post in
those channels.
You have already configured the plugin to send direct messages as Slackbot. For
any other channel you mention in your `role_to_recipients` map, you will need
to invite the plugin to that channel. Navigate to each channel and enter `/invite
@teleport` in the message box.
## Step 7/8. Test your Slack app
Once Teleport is running, you've created the Slack app, and the plugin is
configured, you can now run the plugin and test the workflow.
Start the plugin:
```code
$ teleport-slack start
@@ -227,42 +423,59 @@ INFO Starting Teleport Access Slack Plugin 7.2.1: slack/app.go:80
INFO Plugin is ready slack/app.go:101
```
Create an access request and check if the plugin works as expected with the
Create an Access Request and check if the plugin works as expected with the
following steps.
### Create an access request
### Create an Access Request
<Tabs>
<TabItem label="As admin">
A Teleport admin can create an access request for another user with `tctl`.
A Teleport admin can create an Access Request for another user with `tctl`.
```code
# Replace USERNAME with a Teleport local user and TARGET_ROLE with a Teleport Role
$ tctl request create USERNAME --roles=TARGET_ROLE
$ tctl request create myuser --roles=editor
```
</TabItem>
<TabItem label="As user">
Users can use `tsh` to create an access request and log in with approved roles.
Users can use `tsh` to create an Access Request and log in with approved roles.
```code
# Replace TARGET_ROLE with a Teleport role
$ tsh request new --roles=TARGET_ROLE
$ tsh request new --roles=editor
Seeking request approval... (id: 8f77d2d1-2bbf-4031-a300-58926237a807)
```
</TabItem>
<TabItem label="From the Web UI">
Users can request access using the Web UI by visiting the "Access Requests"
tab and clicking "New Request":
![Creating an Access Request using the Web UI](../../../img/request-access.png)
</TabItem>
</Tabs>
The configured Slack recipients should receive a new message for the new pending request.
The user you configured earlier to review the request should receive a direct
message from "Teleport" in Slack allowing them to visit a link in the Teleport
Web UI and either approve or deny the request.
### Resolve the request
Once you receive the review request in Slack, click the link to visit the Web UI
and approve or deny the request:
![Reviewing a request](../../../img/review-request.png)
<Details title="Reviewing from the command line">
You can also review an Access Request from the command line:
<Tabs>
<TabItem label="As admin">
<TabItem label="As an Admin">
```code
# Replace REQUEST_ID with the id of the request
$ tctl request approve REQUEST_ID
$ tctl request deny REQUEST_ID
```
</TabItem>
<TabItem label="As user">
<TabItem label="As a User">
```code
# Replace REQUEST_ID with the id of the request
$ tsh request review --approve REQUEST_ID
@@ -271,31 +484,56 @@ The configured Slack recipients should receive a new message for the new pending
</TabItem>
</Tabs>
Once the request is resolved, the Slack bot will make an emoji reaction of ✅ or
❌ on the Slack message for the access request, depending on whether the request
</Details>
Once the request is resolved, the Slack bot will add an emoji reaction of ✅ or
❌ to the Slack message for the Access Request, depending on whether the request
was approved or denied.
## Step 7/7. Set up systemd
<Admonition title="Auditing Access Requests">
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:
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
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-slack.service!)
```
Save this as `teleport-slack.service`.
Save this as `teleport-slack.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 Slack channel approve access
requests, so it's important to review the Teleport audit log to ensure that only
the expected users are submitting reviews.
```code
$ sudo systemctl enable teleport-slack
$ sudo systemctl start teleport-slack
```
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>.
## Next steps
- Read our guides to configuring [Resource Access
Requests](./resource-requests.mdx) and [Role Access
Requests](./role-requests.mdx) so you can get the most out
of your Access Request plugins.
## Feedback
If you have any issues with this plugin, please create a GitHub issue in our [`gravitational/teleport-plugins`](https://github.com/gravitational/teleport-plugins/issues/new) repo.
docs/pages/includes/plugins/identity-export.mdx
+81 -16
View File
@@ -1,31 +1,96 @@
Teleport's plugins use the `access-plugin` user to manage access requests. In order to act as
the user, the plugin must present the Teleport Auth Service with valid identity files.
We export the identity files for the user using [`tctl auth sign`](../../setup/reference/cli.mdx#tctl-auth-sign).
Like all Teleport users, `access-plugin` needs signed credentials in
order to connect to your Teleport cluster. You will use the `tctl auth sign`
command to request these credentials for your plugin.
{/*
TODO (ptgott): Remove "oss" once gravitational/docs#118 is fixed
*/}
<ScopedBlock scope={["oss", "enterprise"]}>
The format of the credentials depends on whether you have set up your network to
give the plugin direct access to the Teleport Auth Service, or if all Teleport
clients and services connect to the Teleport Proxy Service instead.
<Tabs>
<TabItem label="Self-Hosted" scope={["oss","enterprise"]}>
<TabItem label="Connect to the Proxy Service">
The following `tctl auth sign` command impersonates the `access-plugin` user,
generates signed credentials, and writes an identity file to the local
directory:
```code
$ tctl auth sign --format=tls --user=access-plugin --out=auth --ttl=2190h
# ...
$ tctl auth sign --user=access-plugin --out=auth.pem
```
The above sequence should result in three PEM encoded files being generated: `auth.crt`, `auth.key`, and `auth.cas` (certificate, private key, and CA certs respectively).
Teleport's Access Request plugins listen for new and updated Access Requests by
connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, `auth.pem`, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
You will refer to this file later when configuring the plugin.
</TabItem>
<TabItem label="Cloud" scope={["cloud"]}>
<TabItem label="Connect to the Auth Service">
If your network allows your plugin to access the Auth Service directly, e.g.,
you are running the plugin on the Auth Service host, the plugin uses TLS
credentials to connect to the Auth Service's gRPC endpoint and listen for new
and updated Access Requests.
You can generate TLS credentials with the following command:
```code
$ tctl auth sign --user=access-plugin --out=auth.pem --ttl=2190h
# ...
$ tctl auth sign --format=tls --user=access-plugin --out=auth
```
The above sequence should result in one PEM encoded file: `auth.pem`.
</TabItem>
This command should result in three PEM-encoded files: `auth.crt`,
`auth.key`, and `auth.cas` (certificate, private key, and CA certs
respectively). Later, you will configure the plugin to use these credentials to
connect to the Auth Service directly.
</TabItem>
</Tabs>
</ScopedBlock>
<ScopedBlock scope="cloud">
The following `tctl auth sign` command impersonates the `access-plugin` user,
generates signed credentials, and writes an identity file to the local
directory:
```code
$ tctl auth sign --user=access-plugin --out=auth.pem
```
Teleport's Access Request plugins listen for new and updated Access Requests by
connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, `auth.pem`, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
You will refer to this file later when configuring the plugin.
</ScopedBlock>
<Admonition
type="note"
title="Certificate Lifetime"
>
By default, [`tctl auth sign`](../../setup/reference/cli.mdx#tctl-auth-sign) produces certificates with a relatively short lifetime. For production deployments, the `--ttl` flag can be used to ensure a more practical certificate lifetime. `--ttl=8760h` exports a 1 year token
</Admonition>
By default, `tctl auth sign` produces certificates with a relatively short
lifetime. For production deployments, you can use the `--ttl` flag to ensure a
more practical certificate lifetime, e.g., `--ttl=8760h` to export a one-year
certificate.
</Admonition>
docs/pages/includes/plugins/impersonations.mdx
-32
View File
@@ -1,32 +0,0 @@
<ScopedBlock opened={true}
scopeOnly={true}
scope={["cloud"]}
>
Teleport Cloud requires authenticating with a role that can create and impersonate
the `access-plugin` role and user. Log in with `tsh` with a user that has this role
or has a role with these `allow` rules.
```
kind: role
version: v4
metadata:
name: plugin-admin
spec:
allow:
impersonate:
roles:
- access-plugin
users:
- access-plugin
rules:
- resources: ['roles']
verbs: ['create','update','read','list','delete']
- resources: ['user']
verbs: ['create','update','read','list','delete']
```
Learn more about impersonation in [Impersonating Teleport Users](../../access-controls/guides/impersonation.mdx).
</ScopedBlock>
docs/pages/includes/plugins/rbac.mdx
+77 -19
View File
@@ -1,23 +1,14 @@
Using an existing Teleport cluster, create the following `user` and `role` resources with the command below, replacing `YAML_PATH` with the path to each resource spec.
Teleport's Access Request plugins authenticate to your Teleport cluster as a
user with permissions to list, read, and update Access Requests. This way,
plugins can retrieve Access Requests from the Teleport Auth Service, present
them to reviewers, and modify them after a review.
```
$ tctl create -f YAML_PATH.yaml
```
(!docs/pages/includes/plugins/impersonations.mdx!)
Create a non-interactive bot user and role called `access-plugin`.
Define a user and role called `access-plugin` by adding the following content to
a file called `access-plugin.yaml`:
```yaml
kind: user
metadata:
name: access-plugin
spec:
roles: ['access-plugin']
version: v2
---
kind: role
version: v4
version: v5
metadata:
name: access-plugin
spec:
@@ -27,8 +18,75 @@ spec:
verbs: ['list', 'read', 'update']
- resources: ['access_plugin_data']
verbs: ['update']
---
kind: user
metadata:
name: access-plugin
spec:
roles: ['access-plugin']
version: v2
```
<Admonition type="tip">
If you're using other plugins, you might want to create different users and roles for different plugins
</Admonition>
Create the user and role:
```code
$ tctl create -f access-plugin.yaml
```
As with all Teleport users, the Teleport Auth Service authenticates the
`access-plugin` user by issuing short-lived TLS credentials. In this case, we
will need to request the credentials manually by *impersonating* the
`access-plugin` role and user.
<ScopedBlock scope={["oss", "enterprise"]}>If you are using `tctl` from the Auth
Service host, you will already have impersonation privileges.</ScopedBlock>
To grant your user impersonation privileges for `access-plugin`, define a role
called `access-plugin-impersonator` by pasting the following YAML document into
a file called `access-plugin-impersonator.yaml`:
```yaml
kind: role
version: v5
metadata:
name: access-plugin-impersonator
spec:
allow:
impersonate:
roles:
- access-plugin
users:
- access-plugin
```
Create the `access-plugin-impersonator` role:
```code
$ tctl create -f access-plugin-impersonator.yaml
```
Retrieve your user definition:
```code
$ TELEPORT_USER=$(tsh status --format=json | jq -r .active.username)
$ tctl get users/${TELEPORT_USER?} > myuser.yaml
```
Edit `myuser.yaml` to include the role you just created:
```diff
roles:
- access
- auditor
- editor
+ - access-plugin-impersonator
```
Apply your changes:
```code
$ tctl create -f myuser.yaml
```
Log out of your Teleport cluster and log in again. You will now be able to
generate signed certificates for the `access-plugin` role and user.
docs/pages/includes/role-spec.mdx
+6 -6
View File
@@ -39,9 +39,9 @@ spec:
# valid values are "strict" or "best_effort"
lock: strict
# enterprise-only request_access field is either 'always' or 'reason'. If set to always, it instructs
# tsh or the web UI clients to always create an access request on login. If it is
# tsh or the web UI clients to always create an Access Request on login. If it is
# set to 'reason', the user will be required to indicate why they are
# generating the access request.
# generating the Access Request.
request_access: reason
# the `request_prompt` field can be used to tell the user what should
# be supplied in the request reason field.
@@ -176,7 +176,7 @@ spec:
contains(user.spec.traits["group"], impersonate_user.metadata.labels["group"])
# review_requests allows a user holding this role
# to approve or deny access requests
# to approve or deny Access Requests
review_requests:
roles: ['dbadmin']
@@ -208,7 +208,7 @@ spec:
# generates a role name from the value capture
roles: ['$1-admin']
# Teleport can attach annotations to pending access requests. these
# Teleport can attach annotations to pending Access Requests. these
# annotations may be literals, or be variable interpolation expressions,
# effectively creating a means for propagating selected claims from an
# external identity provider to the plugin system.
@@ -262,8 +262,8 @@ spec:
# trusted_cluster - trusted cluster resource
# remote_cluster - remote cluster resource
#
# access_request - access request resource
# access_plugin_data - allows modifying access request plugin data
# access_request - Access Request resource
# access_plugin_data - allows modifying Access Request plugin data
#
# session - session playback records
# ssh_session - an active SSH session
docs/pages/setup/security/reduce-blast-radius.mdx
+1 -1
View File
@@ -165,7 +165,7 @@ The `spec.allow.request.roles` field lists the names of other roles that a user
## Automatically prevent some roles from requesting others
A malicious Teleport user could request a more privileged role and trick a reviewer into granting access. You can prevent such a scenario by defining roles that prohibit users from even requesting access to particular roles.
The `spec.deny` field has the same possible properties as the `spec.allow` field we described [earlier](#require-dual-authorization-for-role-requests) except, rather than enabling actions, this field disables them. For example, the `spec.deny.requests.roles` field is a list of roles that a user is prohibited from requesting. Teleport gives `deny` rules precedence over `allow` rules when executing access requests.
The `spec.deny` field has the same possible properties as the `spec.allow` field we described [earlier](#require-dual-authorization-for-role-requests) except, rather than enabling actions, this field disables them. For example, the `spec.deny.requests.roles` field is a list of roles that a user is prohibited from requesting. Teleport gives `deny` rules precedence over `allow` rules when executing Access Requests.
As an illustration, we have assigned user `myuser` to the `user` role, which we defined using the following template: