Skip to content

Commit

Permalink
Flesh out CAP instructions
Browse files Browse the repository at this point in the history
Closes #11840

Since Cloud accounts begin with a cluster_auth_preference resource,
you need to obtain your current resource via tctl get and make changes,
rather than creating a fresh one. This changes Cloud instructions in
several guides to reflect this.

Also use the same instructions for self-hosted users. If a CAP does
not exist on the backend, the shell redirection used in the
"tctl get" command will result in an empty file, which follows the
existing instructions with minimal changes.

Also update the instructions related to u2f in the Reducing the
Blast Radius guide.
  • Loading branch information
ptgott committed May 10, 2022
1 parent e569902 commit 3ecba41
Show file tree
Hide file tree
Showing 5 changed files with 126 additions and 39 deletions.
22 changes: 19 additions & 3 deletions docs/pages/access-controls/guides/per-session-mfa.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ configuration:
<Tabs>
<TabItem label="Static configuration">

Update `teleport.yaml` on the Auth Server to contain:
Update `teleport.yaml` on the Auth Server to include the following content:

```yaml
auth_service:
Expand All @@ -89,7 +89,15 @@ auth_service:
</TabItem>
<TabItem label="Dynamic resources">

Create a file called `cap.yaml` with the following content:
Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

Ensure that `cap.yaml` contains the following content:

```yaml
kind: cluster_auth_preference
Expand All @@ -112,7 +120,15 @@ $ tctl create -f cap.yaml
</ScopedBlock>
<ScopedBlock scope="cloud">

Create a file called `cap.yaml` with the following content:
Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

Ensure that `cap.yaml` contains the following content:

```yaml
kind: cluster_auth_preference
Expand Down
71 changes: 44 additions & 27 deletions docs/pages/access-controls/guides/webauthn.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,39 +49,56 @@ configuration as below:
```
</TabItem>
<TabItem label="Dynamic resources">
Create a `cap.yaml` file or get the existing configuration using
`tctl get cluster_auth_preference`:

```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
# To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
second_factor: on
webauthn:
rp_id: example.com
attestation_allowed_cas:
- "/path/to/allowed_ca.pem"
attestation_denied_cas:
- "/path/to/denied_ca.pem"
```

Update the configuration:

```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```
Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

Ensure that `cap.yaml` includes the following content:

```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
# To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
second_factor: on
webauthn:
rp_id: example.com
attestation_allowed_cas:
- "/path/to/allowed_ca.pem"
attestation_denied_cas:
- "/path/to/denied_ca.pem"
```

Update the configuration:

```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```

</TabItem>
</Tabs>

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>
Create a `cap.yaml` file or get the existing configuration using
`tctl get cluster_auth_preference`:

Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

Ensure that `cap.yaml` includes the following content:

```yaml
kind: cluster_auth_preference
Expand Down
10 changes: 9 additions & 1 deletion docs/pages/setup/admin/github-sso.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,15 @@ $ tctl create github.yaml
Configure the Teleport Auth Service to enable the GitHub authentication
connector.

Create a file called `cap.yaml` with the following content:
Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

Ensure that `cap.yaml` includes the following content:

```yaml
kind: cluster_auth_preference
Expand Down
20 changes: 18 additions & 2 deletions docs/pages/setup/reference/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,15 @@ Add the following to your Teleport configuration file, which is stored in

### Dynamic resource

Create a file called `cap.yaml` to define your `cluster_auth_preference`:
Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

Ensure that `cap.yaml` includes the following content:

```yaml
kind: cluster_auth_preference
Expand Down Expand Up @@ -84,7 +92,15 @@ $ tsh login --proxy=myinstance.teleport.sh
$ tctl status
```

Create a file called `cap.yaml` to define your `cluster_auth_preference`:
Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

Ensure that `cap.yaml` includes the following content:

```yaml
kind: cluster_auth_preference
Expand Down
42 changes: 36 additions & 6 deletions docs/pages/setup/security/reduce-blast-radius.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,27 +23,57 @@ To do so, make the following changes depending on your environment:

<Tabs>
<TabItem label="Self-hosted" scope={["oss","enterprise"]}>
Add the following to your Teleport configuration file:

Ensure that the value of `auth_service.authentication.second_factor` is `otp`,
`u2f`, `webauthn`, or `on`:

```yaml
auth_service:
authentication:
second_factor: otp|u2f|webauthn|on
second_factor: otp
```

<Notice type="tip">

`u2f` is an alias for `webauthn`.

</Notice>

</TabItem>
<TabItem label="Teleport Cloud" scope={["cloud"]}>
Create the following `cluster_auth_preference` dynamic resource:

Obtain your existing `cluster_auth_preference` resource:

```code
$ tctl get cap > cap.yaml
```

If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.

In `cap.yaml`, ensure that the value of `spec.second_factor` is `otp`, `u2f`,
`webauthn`, or `on`:

```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
second_factor: otp|u2f|webauthn|on
second_factor: otp
```

<Notice type="tip">

`u2f` is an alias for `webauthn`.

</Notice>

Apply your change:

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

Create your dynamic resource using `tctl create -f <path to your YAML file>`.
</TabItem>
</Tabs>

Expand All @@ -54,7 +84,7 @@ To make MFA mandatory for all users, `second_factor` must be set to one of the f
- `webauthn`
- `on`

Choose `on` if you would like to require MFA for all users while letting them choose an OTP, U2F, or WebAuthn device. The other options restrict users to a single type of MFA device, which is useful for enforcing a particular standard of security. Once you start the Teleport Proxy Service with the `second_factor` configuration option set to one of these values, Teleport will mandate MFA by:
Choose `on` if you would like to require MFA for all users while letting them choose an OTP or WebAuthn device. The other options restrict users to a single type of MFA device, which is useful for enforcing a particular standard of security. Once you start the Teleport Proxy Service with the `second_factor` configuration option set to one of these values, Teleport will mandate MFA by:

- Adjusting the Teleport signup page so a user must enroll an MFA device of the kind you have selected. If the value of `second_factor` is `on`, users will have the option to select from multiple device types.
- Presenting the user with an MFA challenge when they run `tsh login`.
Expand Down

0 comments on commit 3ecba41

Please sign in to comment.