Skip to content

Commit

Permalink
Edit four Access Controls guides for Cloud users
Browse files Browse the repository at this point in the history 
Backports #11838

* Edit four Access Controls guides for Cloud users

See #10638

Per-session MFA

- Add scoped Tabs to the Prerequisites section
- Add a ScopedBlock so Cloud users don't see the option to enable
  per-session MFA via static config
- Minor copy-edits and organization edits. For example, turn a section
  that refers to an example in another section into an Admonition.

Dual Authorization

- Add scoped Tabs to the Prerequisites
- Use a scoped Notice for the edition warning
- Style/clarity/grammar edits
- Hide the Troubleshooting section for Cloud users

Moderated Sessions

- Change the edition warning to a scoped Notice. Since this guide
  is a conceptual guide rather than a step-by-step tutorial, there's no
  other scope-irrelevant information to hide.

Impersonation

- Add scoped Tabs to the Prerequisites
- Used ScopedBlocks to hide minor scope-irrelevant details
- Minor style/grammar/clarity edits

* Respond to PR feedback

* Respond to PR feedback
  • Loading branch information
@ptgott
ptgott committed Apr 14, 2022
1 parent 3d19002 commit 94aa399
Show file tree
Hide file tree
Showing 5 changed files with 197 additions and 67 deletions.
93 changes: 71 additions & 22 deletions docs/pages/access-controls/guides/dual-authz.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,29 +7,66 @@ videoBanner: b_iqJm_o15I
You can set up Teleport to require require the approval of multiple team members to perform some critical actions.
Here are the most common scenarios:

- Improve security of your system and prevent one successful phishing attack from compromizing your system.
- 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.

Let's set up Teleport's access requests to require approval of
two team members for a privileged role `dbadmin`.
Let's set up Teleport's access requests to require the approval of two team members
for a privileged role `dbadmin`.

<Admonition
type="warning"
title="Version Warning"
<Notice
type="danger"
scope="oss"
>
This guide requires a commercial edition of Teleport. The open source
edition of Teleport only supports [Github](../../setup/admin/github-sso.mdx) as
an SSO provider.
</Admonition>
</Notice>

<Admonition title="Note" type="tip">
The steps below describe how to use Teleport with Mattermost. You can also [integrate with many other providers](../../enterprise/workflow/index.mdx).
</Admonition>

## Prerequisites

- Installed [Teleport Enterprise](../../enterprise/introduction.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=)
- [Tctl enterprise admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=)
<Tabs>
<TabItem
scope={["enterprise"]} label="Enterprise">

- A running Teleport cluster. For details on how to set this up, see our Enterprise
[Getting Started](../../enterprise/getting-started.mdx) guide.

- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=),
which you can download by visiting the
[customer portal](https://dashboard.gravitational.com/web/login).

```code
$ tctl version
# Teleport v(=teleport.version=) go(=teleport.golang=)
$ tsh version
# Teleport v(=teleport.version=) go(=teleport.golang=)
```

</TabItem>
<TabItem scope={["cloud"]}
label="Teleport Cloud">

- A Teleport Cloud account. If you do not have one, visit the
[sign up page](https://goteleport.com/signup/) to begin your free trial.

- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=).
To download these tools, visit the [Downloads](../../cloud/downloads.mdx) page.

```code
$ tctl version
# Teleport v(=cloud.version=) go(=teleport.golang=)
$ tsh version
# Teleport v(=cloud.version=) go(=teleport.golang=)
```

</TabItem>
</Tabs>
- Mattermost installed.

<Admonition
Expand All @@ -44,7 +81,7 @@ two team members for a privileged role `dbadmin`.

(!docs/pages/includes/tctl.mdx!)

## Set up Teleport bot
## Step 1/3. Set up a Teleport bot

### Create a bot within Mattermost

Expand Down Expand Up @@ -110,20 +147,25 @@ Update the config with the Teleport address, Mattermost URL, and a bot token.
(!examples/resources/plugins/teleport-mattermost-self.toml!)
```
</TabItem>
<TabItem scope={["cloud"]} label="Cloud">
<TabItem scope={["cloud"]} label="Teleport Cloud">
```yaml
(!examples/resources/plugins/teleport-mattermost-cloud.toml!)
```
</TabItem>
</Tabs>

## Dual authorization
## Step 2/3. Configure dual authorization

Alice and Ivan are reviewers - they can approve requests for assuming role `dbadmin`.
Bob is a devops and can assume `dbadmin` role if two members of the `reviewer` role
approved the request.
In this section, we will use an example to show you how to require dual
authorization for a user to assume a role.

Create `dbadmin`, `reviewer` and `devops` roles:
### Require dual authorization for a role

Alice and Ivan are reviewers. They can approve requests for assuming role
`dbadmin`. Bob is a DevOps engineer and can assume the `dbadmin` role if two members
of the `reviewer` role approve the request.

Create the following `dbadmin`, `reviewer` and `devops` roles:

```yaml
kind: role
Expand Down Expand Up @@ -159,17 +201,17 @@ spec:
'type': 'db'
```
Example below creates local users Alice, Ivan and Bob.
Bob does not have a role `dbadmin` assigned to him, but can create an access request for it.
The commands below create the local users Bob, Alice, and Ivan.
```code
$ tctl users add [email protected] --roles=devops
$ tctl users add [email protected] --roles=reviewer
$ tctl users add [email protected] --roles=reviewer
```

## Access Requests flow
### Create an access request

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:

Expand Down Expand Up @@ -215,11 +257,16 @@ Bob can also assume granted access request roles using Web UI:

![Teleport Assume](../../../img/access-controls/dual-authz/teleport-7-bob-assume.png)


{/* TODO: This H2 will show up in the table of contents when this section is invisible.
We need a way to hide invisible H2s from the TOC. */}
<ScopedBlock scope={["oss", "enterprise"]}>

## Troubleshooting

### Cert errors in self-hosted deployments

You may be getting certificate errors if Teleport's auth server is missing an address in the server certificate:
You may be getting certificate errors if Teleport's Auth Service is missing an address in the server certificate:

```txt
authentication handshake failed: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs
Expand All @@ -229,9 +276,11 @@ authentication handshake failed: x509: cannot validate certificate for 127.0.0.1
x509: certificate is valid for,*.teleport.cluster.local, teleport.cluster.local, not example.com
```

To fix the problem, update the auth service with a public address, and restart Teleport:
To fix the problem, update the Auth Service with a public address, and restart Teleport:

```yaml
auth_service:
public_addr: ['localhost:3025', 'example.com:3025']
```
</ScopedBlock>
84 changes: 52 additions & 32 deletions docs/pages/access-controls/guides/impersonation.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@ title: Impersonating Teleport Users
description: How to issue short-lived certs on behalf of Teleport users using impersonation.
---

# Impersonation

Sometimes users need to create short-lived certificates for non-interactive
users, for example, CI/CD systems. Your programs interacting with Teleport may
need to create their own authentication as well. Teleport's impersonation allows
Expand All @@ -22,13 +20,13 @@ non-interactive CI/CD user Jenkins and a security scanner.

## Step 1/3: Create a CI/CD user and corresponding role

First, let's create a role called `jenkins`. Notice the `max_session_ttl`
First, we will create a role called `jenkins`. Notice the `max_session_ttl`
parameter, which limits the cert duration for certificates issued to users with
this role. As a rule of thumb, the shorter the TTL, the better.

Next, we'll create a user also named `jenkins` and assign the role to the user.
We will also create a user also named `jenkins` and assign the role to the user.

Save this file as `jenkins.yaml` to create the user and role:
Save this file as `jenkins.yaml`:

```yaml
kind: role
Expand Down Expand Up @@ -57,20 +55,15 @@ spec:
roles: ['jenkins']
```
<Admonition
type="note"
title="Audit"
>
Here and below follow along and create yaml resources using `tctl create -f`:
Create the resources:
```code
$ tctl create -f jenkins.yaml
```
</Admonition>
```code
$ tctl create -f jenkins.yaml
```

## Step 2/3: Create an impersonator role

Let's create a role `impersonator`. Users with this role will be permitted to
Next, we will create a role called `impersonator`. Users with this role will be permitted to
impersonate the `jenkins` user and role.

Save this role definition as `impersonator.yaml`:
Expand Down Expand Up @@ -101,7 +94,13 @@ spec:
'*': '*'
```
Next, create an interactive user `alice` and assign the impersonator role so
Create the `role` resource:

```code
$ tctl create -f impersonator.yaml
```

Next, create an interactive user named `alice` and assign the impersonator role so
that `alice` can impersonate `jenkins`.

<Admonition
Expand All @@ -118,13 +117,25 @@ $ tctl users add alice --roles=impersonator,access

## Step 3/3: Use impersonation to issue a certificate

Alice can login using `tsh` and issue a cert for `jenkins`:
Alice can log in using `tsh` and issue a cert for `jenkins`:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
$ tsh login --proxy=teleport.localhost --user=alice --auth=local
$ tsh login --proxy=proxy.example.com --user=alice --auth=local
$ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
$ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local
$ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h
```

</ScopedBlock>

Here is an example of how Alice can use the keys:

```code
Expand Down Expand Up @@ -161,10 +172,10 @@ To prevent unintended consequences, Teleport defines the following impersonation
being impersonated.
- Even if the `jenkins` role could impersonate some other roles, Alice would not
be able to use this permission. Teleport prevents recursive impersonation.
- Alice can get a new `jenkins` certificate with the same TTL, but metadata
updated, for example pointing to a different Teleport leaf cluster. Teleport
allows impersonated users to renew their certificates with the reduced scope
of the certificate.
- Alice can get a new `jenkins` certificate with the same TTL, but with the
metadata updated, for example, to point to a different Teleport leaf cluster.
Teleport allows impersonated users to renew their certificates with the
reduced scope of the certificate.
### Dynamic Impersonation
Expand All @@ -175,7 +186,7 @@ based on matching labels.
For example, suppose you wanted to define a `security-impersonator` role that
allowed the impersonation of any users or roles with the label
`group: security`. This could be accomplished with the folowing role definition:
`group: security`. This could be accomplished with the following role definition:
```yaml
kind: role
Expand Down Expand Up @@ -246,11 +257,11 @@ the `group: security` label.
$ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h
```

**Matching user traits**
### Matching user traits

We can also define impersonation rules by matching against user traits.

Here we update the `security-impersonator` role to allow for the impersonation
Here we updated the `security-impersonator` role to allow for the impersonation
of any other users or roles where the `group` user trait contains the same value
as the label on the role and/or user to impersonate:

Expand Down Expand Up @@ -279,7 +290,7 @@ spec:
```

While user traits typically come from an external identity provider, we can test
with local user `alice` by manually updating Alices's account with traits.
with local user `alice` by manually updating Alice's account with traits.

```yaml
kind: user
Expand All @@ -298,12 +309,9 @@ Since Alice's `group` trait contains `security`, and the `security-scanner` user
has a label of `group: security`, Alice will be able to impersonate the security
scanner.

<Admonition
type="note"
title="Login"
>
Alice will need to log in again to receive the newly updated traits.
</Admonition>
Alice will need to log in again to receive the newly updated traits:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Once Alice logs in again, she will receive a new certificate with updated roles.
Expand All @@ -312,6 +320,18 @@ $ tsh login --proxy=teleport.example.com --user=alice --auth=local
$ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Once Alice logs in again, she will receive a new certificate with updated roles.
$ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local
# Alice can now get a certificate for the security scanner
$ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h
```

</ScopedBlock>

### Filter fields

Here is an explanation of the fields used in the `where` conditions within this guide.
Expand Down
12 changes: 10 additions & 2 deletions docs/pages/access-controls/guides/moderated-sessions.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,18 @@ description: Moderated Sessions
h1: Moderated Sessions
---

<Notice type="warning" scope="oss">

Moderated Sessions requires Teleport Enterprise or Teleport Cloud.

</Notice>

## Introduction

Moderated Sessions allows Teleport administrators to
define requirements for other users to be present in a Server or Kubernetes Access session. Depending on the requirements, these users can observe the session in real time, participate in the session, and terminate the session at will.
Moderated Sessions allows Teleport administrators to define requirements for
other users to be present in a Server or Kubernetes Access session. Depending on
the requirements, these users can observe the session in real time, participate
in the session, and terminate the session at will.

### Use cases

Expand Down
Loading

0 comments on commit 94aa399

Please sign in to comment.