Skip to content

Commit

Permalink
Edit the Slack access request plugin guide
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
ptgott committed Aug 1, 2022
1 parent af5e251 commit 51742ea
Show file tree
Hide file tree
Showing 19 changed files with 526 additions and 200 deletions.
Binary file added docs/img/request-access.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/review-request.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
10 changes: 5 additions & 5 deletions docs/pages/access-controls/guides/dual-authz.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 Access Requests to require the approval
of two team members for a privileged role `dbadmin`.

<ScopedBlock scope="oss">
Expand Down Expand Up @@ -171,11 +171,11 @@ $ tctl users add [email protected] --roles=reviewer
$ tctl users add [email protected] --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">
Expand Down Expand Up @@ -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)

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/guides/locking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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".
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/access-controls/reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.|
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/api/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/architecture/authorization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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']
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/database-access/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/enterprise/soc2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/enterprise/workflow/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions docs/pages/enterprise/workflow/resource-requests.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -169,15 +169,15 @@ 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`.

```code
$ 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions docs/pages/enterprise/workflow/role-requests.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading

0 comments on commit 51742ea

Please sign in to comment.