From 1fc9c420c501e54967e2654b1deafa18467dcec9 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Fri, 3 Jun 2022 10:10:22 -0400 Subject: [PATCH] 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 --- .../guides/per-session-mfa.mdx | 22 ++++- .../pages/access-controls/guides/webauthn.mdx | 81 ++++++++++++------- docs/pages/setup/admin/github-sso.mdx | 10 ++- docs/pages/setup/reference/authentication.mdx | 20 ++++- .../setup/security/reduce-blast-radius.mdx | 42 ++++++++-- 5 files changed, 134 insertions(+), 41 deletions(-) diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index e09690ec8d442..497c5fec5bf8e 100644 --- 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: -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: -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 -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 index 689a08c90deb2..8fee14df8cf98 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -49,39 +49,56 @@ configuration as below: ``` - 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 + ``` + -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 index 6f48598e5a1f9..e68874f45dbd9 100644 --- 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 index d89bb0f06eb13..fadf509fb174e 100644 --- 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 index d88bcd13bf7a3..8a3f7898ca032 100644 --- a/docs/pages/setup/security/reduce-blast-radius.mdx +++ b/docs/pages/setup/security/reduce-blast-radius.mdx @@ -23,16 +23,35 @@ To do so, make the following changes depending on your environment: -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 ``` + + + +`u2f` is an alias for `webauthn`. + + + -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 @@ -40,10 +59,21 @@ version: v2 metadata: name: cluster-auth-preference spec: - second_factor: otp|u2f|webauthn|on + second_factor: otp +``` + + + +`u2f` is an alias for `webauthn`. + + + +Apply your change: + +```code +$ tctl create -f cap.yaml ``` -Create your dynamic resource using `tctl create -f `. @@ -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`.