diff --git a/docs/img/request-access.png b/docs/img/request-access.png new file mode 100644 index 00000000000..6938e77595c Binary files /dev/null and b/docs/img/request-access.png differ diff --git a/docs/img/review-request.png b/docs/img/review-request.png new file mode 100644 index 00000000000..3210b6344e9 Binary files /dev/null and b/docs/img/review-request.png differ diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx index debc76baf44..1419efade97 100644 --- a/docs/pages/access-controls/guides/dual-authz.mdx +++ b/docs/pages/access-controls/guides/dual-authz.mdx @@ -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`. @@ -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: @@ -215,7 +215,7 @@ Alice and Ivan can review and approve request using Web UI or CLI: 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) diff --git a/docs/pages/access-controls/guides/locking.mdx b/docs/pages/access-controls/guides/locking.mdx index adca31fce52..b172998a312 100644 --- a/docs/pages/access-controls/guides/locking.mdx +++ b/docs/pages/access-controls/guides/locking.mdx @@ -81,7 +81,7 @@ with one of the following options: ``` - 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". diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx index 2d12451737a..6c5c43864a7 100644 --- a/docs/pages/access-controls/reference.mdx +++ b/docs/pages/access-controls/reference.mdx @@ -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.| diff --git a/docs/pages/api/introduction.mdx b/docs/pages/api/introduction.mdx index c3e2637f03d..771b8a3288b 100644 --- a/docs/pages/api/introduction.mdx +++ b/docs/pages/api/introduction.mdx @@ -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. diff --git a/docs/pages/architecture/authorization.mdx b/docs/pages/architecture/authorization.mdx index 5d96f24c02b..31a8996a8b7 100644 --- a/docs/pages/architecture/authorization.mdx +++ b/docs/pages/architecture/authorization.mdx @@ -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'] diff --git a/docs/pages/database-access/introduction.mdx b/docs/pages/database-access/introduction.mdx index fd3a8fc21c6..a3b22ce8f68 100644 --- a/docs/pages/database-access/introduction.mdx +++ b/docs/pages/database-access/introduction.mdx @@ -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: diff --git a/docs/pages/enterprise/soc2.mdx b/docs/pages/enterprise/soc2.mdx index 75e0642627a..28830dfafd8 100644 --- a/docs/pages/enterprise/soc2.mdx +++ b/docs/pages/enterprise/soc2.mdx @@ -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. diff --git a/docs/pages/enterprise/workflow/index.mdx b/docs/pages/enterprise/workflow/index.mdx index 6ad0cff8931..eb024e84e35 100644 --- a/docs/pages/enterprise/workflow/index.mdx +++ b/docs/pages/enterprise/workflow/index.mdx @@ -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. diff --git a/docs/pages/enterprise/workflow/resource-requests.mdx b/docs/pages/enterprise/workflow/resource-requests.mdx index e7ca956b209..bf1579ed376 100644 --- a/docs/pages/enterprise/workflow/resource-requests.mdx +++ b/docs/pages/enterprise/workflow/resource-requests.mdx @@ -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 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. ## 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 diff --git a/docs/pages/enterprise/workflow/role-requests.mdx b/docs/pages/enterprise/workflow/role-requests.mdx index b88a3da1df0..14980cde7d6 100644 --- a/docs/pages/enterprise/workflow/role-requests.mdx +++ b/docs/pages/enterprise/workflow/role-requests.mdx @@ -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. diff --git a/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx b/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx index a1771643655..dc3170abdd7 100644 --- a/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx +++ b/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx @@ -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. diff --git a/docs/pages/enterprise/workflow/ssh-approval-slack.mdx b/docs/pages/enterprise/workflow/ssh-approval-slack.mdx index 8c97bd9a06f..6f2a4897ad6 100644 --- a/docs/pages/enterprise/workflow/ssh-approval-slack.mdx +++ b/docs/pages/enterprise/workflow/ssh-approval-slack.mdx @@ -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. - - - 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. - - - -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: - 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 ``` - + + -## 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
-**Development Slack Workspace:** Pick the workspace you'd like the requests to show up in.
-**App Icon:** Download Teleport Bot Icon +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. + + + +The address and credentials you configure depend on whether your plugin can +access the Auth Service directly: - + -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 ``` - + -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" ``` + + + + +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" +``` + + **`[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! +
+ +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. + +
+ +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 - 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 ``` - 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) ``` + + + 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) + + -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) + +
+ +You can also review an Access Request from the command line: + - + ```code # Replace REQUEST_ID with the id of the request $ tctl request approve REQUEST_ID $ tctl request deny REQUEST_ID ``` - + ```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 -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 +
+ +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 + -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 and `access_request.review` if reviewing the audit log on the +Auth Service host. + + + +## 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 -and `access_request.review` if reviewing the audit log on the Auth Service host. +## 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. diff --git a/docs/pages/includes/plugins/identity-export.mdx b/docs/pages/includes/plugins/identity-export.mdx index ca66443718d..fb9d965f896 100644 --- a/docs/pages/includes/plugins/identity-export.mdx +++ b/docs/pages/includes/plugins/identity-export.mdx @@ -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 +*/} + + +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. - + + + +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. + - + + +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`. - - +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. + + + + + + + + +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. + + + - 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 - \ No newline at end of file + + 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. + + diff --git a/docs/pages/includes/plugins/impersonations.mdx b/docs/pages/includes/plugins/impersonations.mdx deleted file mode 100644 index 1364372deef..00000000000 --- a/docs/pages/includes/plugins/impersonations.mdx +++ /dev/null @@ -1,32 +0,0 @@ - - -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). - - diff --git a/docs/pages/includes/plugins/rbac.mdx b/docs/pages/includes/plugins/rbac.mdx index d9148f8c2c2..855b6d114b3 100644 --- a/docs/pages/includes/plugins/rbac.mdx +++ b/docs/pages/includes/plugins/rbac.mdx @@ -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 ``` - - If you're using other plugins, you might want to create different users and roles for different plugins - \ No newline at end of file +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. + +If you are using `tctl` from the Auth +Service host, you will already have impersonation privileges. + +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. diff --git a/docs/pages/includes/role-spec.mdx b/docs/pages/includes/role-spec.mdx index 54429f03dd3..b3a5e2c7991 100644 --- a/docs/pages/includes/role-spec.mdx +++ b/docs/pages/includes/role-spec.mdx @@ -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 diff --git a/docs/pages/setup/security/reduce-blast-radius.mdx b/docs/pages/setup/security/reduce-blast-radius.mdx index 7d08f5f4b8f..42b0b0e0982 100644 --- a/docs/pages/setup/security/reduce-blast-radius.mdx +++ b/docs/pages/setup/security/reduce-blast-radius.mdx @@ -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: