Backport #12544 to branch/v9 (#13110)

* Flesh out CAP instructions 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. * Respond to PR feedback
gravitational · Jun 3, 2022 · 1fc9c42 · 1fc9c42
1 parent 6404f22
commit 1fc9c42
Show file tree

Hide file tree

Showing 5 changed files with 134 additions and 41 deletions.
diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx
@@ -78,7 +78,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:
@@ -90,7 +90,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
@@ -113,7 +121,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

diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx
@@ -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
@@ -95,9 +112,15 @@ spec:
   webauthn:
     rp_id: example.com
     attestation_allowed_cas:
-    - "/path/to/allowed_ca.pem"
+    - |
+      -----BEGIN CERTIFICATE-----
+      ...
+      -----END CERTIFICATE-----
     attestation_denied_cas:
-    - "/path/to/denied_ca.pem"
+    - |
+      -----BEGIN CERTIFICATE-----
+      ...
+      -----END CERTIFICATE-----
 ```
 
 Update the configuration:

diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx
@@ -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

diff --git a/docs/pages/setup/reference/authentication.mdx b/docs/pages/setup/reference/authentication.mdx
@@ -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
@@ -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

diff --git a/docs/pages/setup/security/reduce-blast-radius.mdx b/docs/pages/setup/security/reduce-blast-radius.mdx
@@ -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: webauthn
 ```
+
+<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> 
 
@@ -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`.