From 9dfbbf0c0737b3ba399fc5eb097631afe72cc974 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 Jun 2022 14:03:44 -0300 Subject: [PATCH 01/31] Add the passwordless guide --- docs/config.json | 4 + .../access-controls/guides/passwordless.mdx | 354 ++++++++++++++++++ 2 files changed, 358 insertions(+) create mode 100644 docs/pages/access-controls/guides/passwordless.mdx diff --git a/docs/config.json b/docs/config.json index 56e750f4b5e14..d81d97930ba0c 100644 --- a/docs/config.json +++ b/docs/config.json @@ -718,6 +718,10 @@ "title": "Session Locking", "slug": "/access-controls/guides/locking/" }, + { + "title": "Passwordless", + "slug": "/access-controls/guides/passwordless/" + }, { "title": "Second Factor - WebAuthn", "slug": "/access-controls/guides/webauthn/" diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx new file mode 100644 index 0000000000000..ae65f6873c8a8 --- /dev/null +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -0,0 +1,354 @@ +--- +title: "Passwordless" +description: Use passwordless authentication +--- + +Passwordless takes advantage of [WebAuthn](./webauthn.mdx) to provide +passwordless and usernameless authentication for Teleport. + +## Prerequisites + +* A Teleport cluster with WebAuthn configured. + See the [Second Factor: WebAuthn](./webauthn.mdx) guide. +* A hardware device with support for WebAuthn and resident keys, or a Mac with + biometrics / Touch ID. +* A Web browser with [WebAuthn support]( + https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/). +* A signed and notarized `tsh` for Touch ID. + [Download the macOS tsh installer](../../installation/#macos). + +## Step 1/3. Configure WebAuthn + +See the [Second Factor: WebAuthn](./webauthn.mdx) guide for an in-depth +explanation of the WebAuthn configuration. + +A minimal configuration is shown below: + + + + + Auth Server `teleport.yaml` file: + + ```yaml + # snippet from /etc/teleport.yaml: + auth_service: + authentication: + type: local + second_factor: on + webauthn: + rp_id: example.com + ``` + + + 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 + second_factor: on + webauthn: + rp_id: example.com + ``` + + 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`: + +```yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: on + webauthn: + rp_id: example.com +``` + +Update the configuration: + +```code +$ tctl create -f cap.yaml +# cluster auth preference has been updated +``` + + +`rp_id` is the public domain of the Teleport Proxy Service, *excluding* protocol +(`https://`) and port number. + +A Teleport cluster capable of WebAuthn is automatically capable of passwordless. + +## Step 2/3. Register + +Register your passwordless device using `tsh`: + +```code +$ tsh mfa add +# Choose device type [TOTP, WEBAUTHN, TOUCHID]: webauthn +# Enter device name: bio +# Allow passwordless logins [YES, NO]: yes +# Tap any *registered* security key +# Tap your *new* security key +# MFA device "bio" added. +``` + +If you are using a hardware device, a passwordless registration will occupy a +resident key slot. Regardless of your device type, passwordless registrations +may also be used for regular MFA. + + +If you plan on relying exclusively on passwordless, it's recommended to register +more than one device. A portable hardware device is ideal, as it can be shared +between `tsh`, Web UI, and different computers. + + + +Touch ID registrations are siloed per-application. A Touch ID registration for +`tsh` is different from a registration made from Chrome or Safari. You may +register the same Touch ID device from multiple applications to get passwordless +access in all of them. + + +## Step 3/3. Authenticate + +Authenticate using your passwordless credential: + +```code +$ tsh login --proxy=example.com --auth=passwordless +# Tap your security key +# > Profile URL: https://example.com +# Logged in as: codingllama +# Cluster: example.com +# Roles: access, editor +# Logins: codingllama +# Kubernetes: enabled +# Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s] +# Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty +``` + + +A fully passwordless cluster defaults to passwordless logins, making +`--auth=passwordless` unnecessary. See [enable passwordless by default]( +#optional-enable-passwordless-by-default). + + + +Look for the passwordless link in the Web UI. + + +## Optional: Enable passwordless by default + +Passwordless enthusiasts may enable passwordless by default in their clusters. +Note that this configuration changes Teleport's behavior even for users without +a passwordless device registered, so existing users may need to authenticate +using `tsh login --proxy=example.com --auth=local` in order to get their first +passwordless registration. + +To enable passwordless by default, add `connector_name: passwordless` to your +cluster configuration: + + + + + Auth Server `teleport.yaml` file: + + ```yaml + auth_service: + authentication: + type: local + second_factor: on + webauthn: + rp_id: example.com + connector_name: passwordless # passwordless by default + ``` + + + 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 + second_factor: on + webauthn: + rp_id: example.com + connector_name: passwordless # passwordless by default + ``` + + 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`: + +```yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: on + webauthn: + rp_id: example.com + connector_name: passwordless # passwordless by default +``` + +Update the configuration: + +```code +$ tctl create -f cap.yaml +# cluster auth preference has been updated +``` + + +## Troubleshooting + +### "Allow passwordless logins" doesn't appear + +If you don't see the "Allow passwordless logins" prompt during `tsh mfa add`, +you may be using an older version of `tsh`. Download the latest `tsh` from our +[installation page](../../installation). + +### Hardware device not usable + +`tsh` only prompts for hardware devices with certain capabilities for +passwordless registrations. If your device isn't blinking it may not be capable +of passwordless logins. + +Below is a non-comprehensive list of requirements: + +* Device must support WebAuthn (sometimes also called FIDO2 or CTAP2) +* Device must be capable of user verification (biometrics or PIN) +* Device must have PIN set +* Device must have fingerprints enrolled (if biometric). This typically means + both PIN _and_ fingerprints. + +`tsh` relies in an embedded libfido2 to access hardware devices. If you are +running on Linux, you may be missing the necessary udev rules to access your +device. Try following the [installation instructions for libfido2]( +https://github.com/Yubico/libfido2#installation), which may provide you the +necessary udev rules. + +### Touch ID not usable + +If you are having trouble with Touch ID, make sure that you are using the latest +standalone version of `tsh`. [Download the macOS tsh installer]( +../../installation/#macos). + +Touch ID support requires Macs with the Touch Bar and Secure Enclave. It also +requires macOS >= 10.13 (macOS High Sierra). + +You can run the `tsh touchid diag` command to verify requirements. A capable +device and `tsh` binary should show an output similar to the one below: + +```code +$ tsh touchid diag +# Has compile support? true +# Has signature? true +# Has entitlements? true +# Passed LAPolicy test? true +# Passed Secure Enclave test? true +# Touch ID enabled? true +``` + +### Disable passwordless + +If you want to forbid passwordless access to your cluster, add `passwordless: +false` to your configuration: + + + + + Auth Server `teleport.yaml` file: + + ```yaml + # snippet from /etc/teleport.yaml: + auth_service: + authentication: + type: local + second_factor: on + webauthn: + rp_id: example.com + passwordless: false # disable passwordless + ``` + + + 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 + second_factor: on + webauthn: + rp_id: example.com + passwordless: false # disable passwordless + ``` + + 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`: + +```yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: on + webauthn: + rp_id: example.com + passwordless: false # disable passwordless +``` + +Update the configuration: + +```code +$ tctl create -f cap.yaml +# cluster auth preference has been updated +``` + From 8641eb28e9a4cd1adc3e579a553f2657ecb800db Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 Jun 2022 17:14:56 -0300 Subject: [PATCH 02/31] Link various pages to passwordless --- docs/pages/access-controls/guides.mdx | 3 +++ docs/pages/access-controls/guides/webauthn.mdx | 3 ++- docs/pages/access-controls/introduction.mdx | 3 +++ 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides.mdx b/docs/pages/access-controls/guides.mdx index 1c9bf2a0b1263..877c92a228c2b 100644 --- a/docs/pages/access-controls/guides.mdx +++ b/docs/pages/access-controls/guides.mdx @@ -16,6 +16,9 @@ layout: tocless-doc
  • [Impersonating Teleport Users](./guides/impersonation.mdx). Create certs for CI/CD using impersonation.
    • +
  • + [Passwordless](./guides/passwordless.mdx). Use passwordless authentication. +
  • [Second Factor - WebAuthn](./guides/webauthn.mdx). Add Two-Factor Authentication through WebAuthn.
    • diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index 8d9ffd187b163..b1d4c891ba789 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -221,4 +221,5 @@ $ tsh login --proxy=mytenant.teleport.sh ## Next steps -- [Setup per-session MFA checks](per-session-mfa.mdx) +- [Passwordless](./passwordless.mdx) +- [Setup per-session MFA checks](./per-session-mfa.mdx) diff --git a/docs/pages/access-controls/introduction.mdx b/docs/pages/access-controls/introduction.mdx index 2682056936f34..5b05938ea2799 100644 --- a/docs/pages/access-controls/introduction.mdx +++ b/docs/pages/access-controls/introduction.mdx @@ -34,6 +34,9 @@ guide. Create certs for CI/CD using impersonation. + + Use passwordless authentication. + Add Two-Factor Authentication through WebAuthn. From 61b6796b3f8c8a95d060ce16a66542ea541ea483 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 Jun 2022 16:17:00 -0300 Subject: [PATCH 03/31] Document U2F migration in WebAuthn --- .../pages/access-controls/guides/webauthn.mdx | 110 ++++++++++++++++-- 1 file changed, 101 insertions(+), 9 deletions(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index b1d4c891ba789..eb4e252998577 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -29,7 +29,6 @@ WebAuthn is disabled by default. To enable WebAuthn support, update your Telepor configuration as below: - Auth Server `teleport.yaml` file: @@ -84,11 +83,11 @@ configuration as below: $ tctl create -f cap.yaml # cluster auth preference has been updated ``` - + - + Obtain your existing `cluster_auth_preference` resource: @@ -130,10 +129,11 @@ Update the configuration: $ tctl create -f cap.yaml # cluster auth preference has been updated ``` - -You will need to include the following configuration fields. + + Starting on Teleport v10, WebAuthn replaces U2F. See the [U2F](#u2f) section. + `rp_id` is the public domain of the Teleport Proxy Service, *excluding* protocol (`https://`) and port number. @@ -179,7 +179,6 @@ $ tsh mfa add Once a WebAuthn device is registered, the user will be prompted for it on login: - ```code $ tsh login --proxy=example.com # Enter password for Teleport user codingllama: @@ -193,10 +192,9 @@ $ tsh login --proxy=example.com # Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s] # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - - + ```code $ tsh login --proxy=mytenant.teleport.sh # Enter password for Teleport user codingllama: @@ -210,7 +208,6 @@ $ tsh login --proxy=mytenant.teleport.sh # Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s] # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - @@ -219,6 +216,101 @@ $ tsh login --proxy=mytenant.teleport.sh multi-factor authentication in their SSO provider. +## U2F + +Starting on Teleport v10, WebAuthn replaces U2F. If you didn't configure U2F +before no further action is necessary - any U2F devices are automatically +supported. + +If you have an existing U2F configuration, but haven't explicitly configured +WebAuthn yet, Teleport will automatically derive your WebAuthn configuration +from U2F. You may write the WebAuthn configuration yourself, but keep the U2F +"app_id" field - doing so ensures any already-registered U2F devices won't need +to be re-registered. + +For example, consider the U2F configuration below: + +```yaml +# snippet from /etc/teleport.yaml showing an U2F configuration: +auth_service: + authentication: + type: local + second_factor: u2f + u2f: + app_id: https://example.com + facets: + - "https://example.com" + - "https://example.com:443" + device_attestation_cas: + - "/path/to/u2f_attestation_ca.pem" +``` + +The migrated WebAuthn configuration is: + + + + + ```yaml + # snippet from /etc/teleport.yaml: + auth_service: + authentication: + type: local + second_factor: on # changed from "u2f" + u2f: + # Keep the app_id to avoid re-registering U2F devices. + app_id: https://example.com + webauthn: + # rp_id is the public domain of the Teleport Proxy Service. + # It's similar to the U2F app_id, but without "https://" or port number. + rp_id: example.com + attestation_allowed_cas: + - "/path/to/u2f_attestation_ca.pem" + ``` + + + ```yaml + kind: cluster_auth_preference + version: v2 + metadata: + name: cluster-auth-preference + spec: + type: local + second_factor: on # changed from "u2f" + u2f: + # Keep the app_id to avoid re-registering U2F devices. + app_id: https://example.com + webauthn: + # rp_id is the public domain of the Teleport Proxy Service. + # It's similar to the U2F app_id, but without "https://" or port number. + rp_id: example.com + attestation_allowed_cas: + - "/path/to/u2f_attestation_ca.pem" + ``` + + + + + +```yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: on # changed from "u2f" + u2f: + # Keep the app_id to avoid re-registering U2F devices. + app_id: https://example.com + webauthn: + # rp_id is the public domain of the Teleport Proxy Service. + # It's similar to the U2F app_id, but without "https://" or port number. + rp_id: example.com + attestation_allowed_cas: + - "/path/to/u2f_attestation_ca.pem" +``` + + ## Next steps - [Passwordless](./passwordless.mdx) From 05b4c1fbe4b007b3b5bfffa4b9e531969bcbfef9 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 Jun 2022 16:34:04 -0300 Subject: [PATCH 04/31] Update reference config for passwordless, WebAuthn and U2F --- docs/pages/setup/reference/config.mdx | 66 +++++++++------------------ 1 file changed, 21 insertions(+), 45 deletions(-) diff --git a/docs/pages/setup/reference/config.mdx b/docs/pages/setup/reference/config.mdx index e93ed77a5d0f7..3c8dfbbc029a8 100644 --- a/docs/pages/setup/reference/config.mdx +++ b/docs/pages/setup/reference/config.mdx @@ -277,14 +277,25 @@ auth_service: # (https://goteleport.com/docs/enterprise/ssh-kubernetes-fedramp/) #local_auth: true - # second_factor can be 'off', 'on', 'optional', 'otp', 'webauthn' or - # 'u2f'. - # - 'on' requires otp and either webauthn (preferred) or u2f. - # - 'optional' allows otp and either webauthn (preferred) or u2f. - # - 'otp', 'webauthn' and 'u2f' require their corresponding second - # factor type. + # second_factor can be 'off', 'on', 'optional', 'otp' or 'webauthn'. + # - 'on' requires either otp or webauthn second factor. + # - 'optional' allows otp and webauthn second factor. + # - 'otp' and 'webauthn' require the corresponding second factor. second_factor: otp + # Sets whether passwordless authorization is allowed. + # Passwordless requires WebAuthn. + # Defaults to "true". + #passwordless: true + + # Sets the authenticator connector for SSO (Enterprise) or the default + # connector for "local" authentication. + # See SSO for Enterprise (https://goteleport.com/docs/enterprise/sso/). + # See Passwordless for local + # (http://goteleport.com/docs/access-controls/guides/passwordless/#optional-enable-passwordless-by-default). + # Defaults to "local". + #connector_name: local + # this section is used if second_factor is set to 'on', 'optional' or # 'webauthn'. webauthn: @@ -333,48 +344,13 @@ auth_service: # second factor modes 'on' and 'optional'. disabled: false - # this section is used if second_factor is set to 'u2f' + # the U2F section is kept for legacy purposes and to support existing + # U2F registrations. u2f: - # public address of the Teleport proxy, _including_ the `https://` - # prefix. If you use a port number other than 443, include it as - # well. - # - # Examples: - # - "https://example.com" (uses default port 443) - # - "https://example.com:3080" (uses non-default port 3080) - # - # IMPORTANT: app_id must never change in the lifetime of the - # cluster, because it's recorded in the registration data on the - # U2F device. If the app_id changes, all existing U2F key - # registrations will become invalid and all users who use U2F as - # the second factor will need to re-register. + # app ID used by U2F registrations. + # Keep it in your config to avoid having to re-register U2F devices. app_id: https://localhost:3080 - # list of allowed addresses of the Teleport proxy checked during - # authentication attempts. This list is used to prevent malicious - # websites and proxies from requesting U2F challenges on behalf of - # the legitimate proxy. - facets: - # app_id should always also be listed as a facet - - https://localhost:3080 - - https://localhost - # localhost allows non-https facets as well - - localhost:3080 - - localhost - - # optional list of certificate authorities (as local file paths or - # in-line PEM certificate string) for U2F [device - # attestation](https://fidoalliance.org/specs/fido-u2f-v1.0-nfc-bt-amendment-20150514/fido-u2f-overview.html#verifying-that-a-u2f-device-is-genuine) - # verification. This field allows you to restrict which U2F device - # vendors you trust. Devices from other vendors will be rejected - # during registration. By default, any vendor is allowed. - device_attestation_cas: - - /path/to/u2f_ca.pem - - | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - # Locking mode determines how to apply lock views locally available to # a Teleport component; can be strict or best_effort. # See the "Locking mode" section for more details From 5fe82b7971f71d551a2a3e7c57709c564f40932c Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 Jun 2022 16:42:45 -0300 Subject: [PATCH 05/31] Remove U2F guide and most U2F doc references --- .../guides/per-session-mfa.mdx | 5 +- docs/pages/access-controls/guides/u2f.mdx | 137 ------------------ docs/pages/access-controls/reference.mdx | 4 +- .../pages/setup/operations/backup-restore.mdx | 12 +- .../setup/security/reduce-blast-radius.mdx | 29 +--- 5 files changed, 18 insertions(+), 169 deletions(-) delete mode 100644 docs/pages/access-controls/guides/u2f.mdx diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index 5594c7be08d3b..14b0622b2d626 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -283,11 +283,10 @@ Current limitations for this feature are: - WebAuthn hardware devices aren't currently supported in `tsh` on Windows. - Only `tsh ssh` supports per-session MFA authentication for SSH (OpenSSH `ssh` does not). -- Only `kubectl` supports per-session U2F authentication for Kubernetes. +- Only `kubectl` supports per-session WebAuthn authentication for Kubernetes. - Application access clients don't support per-session MFA authentication yet, although cluster and role configuration applies to them. If you enable per-session MFA checks cluster-wide, you will not be able to use Application access. We're working on integrating per-session MFA checks for these clients. -- For Desktop Access, only WebAuthn devices are supported. Teleport does not - support U2F devices for Desktop Access MFA. +- For Desktop Access, only WebAuthn devices are supported. diff --git a/docs/pages/access-controls/guides/u2f.mdx b/docs/pages/access-controls/guides/u2f.mdx deleted file mode 100644 index 0dd3515630510..0000000000000 --- a/docs/pages/access-controls/guides/u2f.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Second Factor - U2F -description: Configuring U2F support in Teleport clusters. ---- - -# U2F (Hardware Tokens) - - - Consider updating your cluster to use [WebAuthn](./webauthn.mdx) as the second - factor protocol. WebAuthn is a modern U2F replacement that allows for a wider - range of devices to be used as second factor authenticators. - - -Teleport supports [FIDO U2F](https://www.yubico.com/about/background/fido/) -hardware keys as a second authentication factor. U2F can be used for logging -into Teleport (`tsh login` or the login page on the Web UI) and for logging -into individual SSH nodes or Kubernetes clusters (`tsh ssh` and `kubectl`). - -## Prerequisites - -(!docs/pages/includes/edition-prereqs-tabs.mdx!) - -- U2F hardware device, such as Yubikey or Solokey -- Web browser that [supports U2F](https://caniuse.com/u2f) - -(!docs/pages/includes/tctl.mdx!) - -## Enable U2F support - -By default U2F is disabled. To enable U2F support, edit the Teleport -configuration file `/etc/teleport.yaml` like so: - -```yaml -# snippet from /etc/teleport.yaml to show an example configuration of U2F: -auth_service: - authentication: - type: local - # to enable U2F support, set this field to 'u2f', 'on' or 'optional' - second_factor: u2f - u2f: - app_id: https://example.com - facets: - - "https://example.com" # app_id should always also be listed as a facet - - "https://example.com:443" - device_attestation_cas: - - "/path/to/u2f_attestation_ca.pem" -``` - -The fields in the above snippet are: - -- `app_id` - public address of the Teleport proxy, *including* the `https://` - prefix. If you use a port number other than 443, include it as well. - - Examples: - - - `https://example.com` (uses default port 443) - - `https://example.com:3080` (uses non-default port 3080) - - - The `app_id` must never change in the lifetime of the cluster, because it's - recorded in the registration data on the U2F device. If the App ID changes, - all existing U2F key registrations will become invalid and all users who use - U2F as the second factor will need to re-register. When using multiple proxy - servers, make sure they are reachable at the same public address (usually - behind a load balancer). - - -- `facets` - list of allowed addresses of the Teleport proxy, checked during - authentication attempts. This list is used to prevent malicious websites and - proxies from requesting U2F challenges on behalf of the legitimate proxy. - - For compatibility with multiple browsers, it's recommended to write down the - proxy address in several formats. For example, if your `app_id` is - `https://example.com`, your `facets` should include `https://example.com` - (same as the app_id) and `https://example.com:443`. - -- `device_attestation_cas` - optional list of certificate authorities (as local - file paths or in-line PEM certificate string) for U2F [device - attestation](https://fidoalliance.org/specs/fido-u2f-v1.0-nfc-bt-amendment-20150514/fido-u2f-overview.html#verifying-that-a-u2f-device-is-genuine) - verification. This field allows you to restrict which U2F device vendors you - trust. Devices from other vendors will be rejected during registration. By - default, any vendor is allowed. - -Once the configuration file was edited, restart `teleport` to pick up the -changes. - -## Register U2F devices as a user - -A user can register multiple U2F devices [using `tsh`](../../setup/reference/cli.mdx#tsh-mfa-add): - -```code -$ tsh mfa add - -# Choose device type [TOTP, U2F]: u2f -# Enter device name: desktop yubikey -# Tap any *registered* security key -# Tap your *new* security key -# MFA device "desktop yubikey" added. -``` - -{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */} - - - U2F devices are currently not supported in `tsh` on Windows. - - -## Login using U2F - -Once a U2F device is registered, the user will be prompted for it on login: - -```code -$ tsh login --proxy=example.com - -# Enter password for Teleport user awly: -# Tap any security key -# > Profile URL: https://example.com -# Logged in as: awly -# Cluster: example.com -# Roles: admin* -# Logins: awly -# Kubernetes: enabled -# Valid until: 2021-04-01 23:32:29 -0700 PDT [valid for 12h0m0s] -# Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty -``` - - -U2F for logging into Teleport is only required for [local -users](../../setup/reference/authentication.mdx#local-no-authentication-connector). SSO users should configure -multi-factor authentication in their SSO provider. - - -## Next steps - -- [Setup per-session U2F checks](per-session-mfa.mdx) diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx index 29eca8393370c..011f27656f0d0 100644 --- a/docs/pages/access-controls/reference.mdx +++ b/docs/pages/access-controls/reference.mdx @@ -334,8 +334,8 @@ spec: ## Second Factor - U2F -Refer to the [Second Factor - U2F guide](./guides/u2f.mdx) if you have a cluster -using the legacy U2F support. +Refer to the [Second Factor - WebAuthn](./guides/webauthn.mdx#u2f) guide if you +have a cluster using the legacy U2F support. ## Filter fields diff --git a/docs/pages/setup/operations/backup-restore.mdx b/docs/pages/setup/operations/backup-restore.mdx index 9b5005c7e4da6..832e22815dd34 100644 --- a/docs/pages/setup/operations/backup-restore.mdx +++ b/docs/pages/setup/operations/backup-restore.mdx @@ -150,9 +150,9 @@ also apply to a new cluster being bootstrapped from the state of an old cluster: - Changing the cluster name will break your CAs. This will be caught and Teleport will refuse to start. - - Some user authentication mechanisms (e.g. WebAuthn and U2F) require that the - public endpoint of the Web UI remains the same. This cannot be caught by - Teleport, so be careful! + - Some user authentication mechanisms (e.g. WebAuthn) require that the public + endpoint of the Web UI remains the same. This cannot be caught by Teleport, + so be careful! - Any Node whose invite token is defined in the Auth Service's configuration file will be able to join automatically, but Nodes that were added dynamically will need to be re-invited. @@ -214,9 +214,9 @@ also apply to a new cluster being bootstrapped from the state of an old cluster: - Changing the cluster name will break your CAs. This will be caught and Teleport will refuse to start. - - Some user authentication mechanisms (e.g. WebAuthn and U2F) require that the - public endpoint of the Web UI remains the same. This cannot be caught by - Teleport, so be careful! + - Some user authentication mechanisms (e.g. WebAuthn) require that the public + endpoint of the Web UI remains the same. This cannot be caught by Teleport, + so be careful! - Any Node whose invite token is defined in the Auth Service's configuration file will be able to join automatically, but Nodes that were added dynamically will need to be re-invited. diff --git a/docs/pages/setup/security/reduce-blast-radius.mdx b/docs/pages/setup/security/reduce-blast-radius.mdx index 8a3f7898ca032..4e087a8db59fb 100644 --- a/docs/pages/setup/security/reduce-blast-radius.mdx +++ b/docs/pages/setup/security/reduce-blast-radius.mdx @@ -15,9 +15,9 @@ Teleport encourages users to practice defense in depth so that every component o (!docs/pages/includes/tctl.mdx!) ## Make MFA mandatory for `tsh login` -If a user sets up an account to authenticate to their Teleport cluster with only a password, an adversary can gain access to the password using brute-force attacks, person-in-the-middle attacks, or phishing. But even if a user's password is compromised, you can stop an attacker from authenticating with it when they run `tsh login`. +If a user sets up an account to authenticate to their Teleport cluster with only a password, an adversary can gain access to the password using brute-force attacks, person-in-the-middle attacks, or phishing. But even if a user's password is compromised, you can stop an attacker from authenticating with it when they run `tsh login`. -Teleport lets you make it mandatory for a user to enroll an MFA device when they create an account, and to authenticate using that device when they begin a new Teleport session. +Teleport lets you make it mandatory for a user to enroll an MFA device when they create an account, and to authenticate using that device when they begin a new Teleport session. To do so, make the following changes depending on your environment: @@ -25,7 +25,7 @@ To do so, make the following changes depending on your environment: Ensure that the value of `auth_service.authentication.second_factor` is `otp`, -`u2f`, `webauthn`, or `on`: +`webauthn`, or `on`: ```yaml auth_service: @@ -33,12 +33,6 @@ auth_service: second_factor: webauthn ``` - - -`u2f` is an alias for `webauthn`. - - - @@ -50,7 +44,7 @@ $ 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`, +In `cap.yaml`, ensure that the value of `spec.second_factor` is `otp`, `webauthn`, or `on`: ```yaml @@ -62,25 +56,18 @@ spec: second_factor: otp ``` - - -`u2f` is an alias for `webauthn`. - - - -Apply your change: +Apply your change: ```code $ tctl create -f cap.yaml ``` - + To make MFA mandatory for all users, `second_factor` must be set to one of the following values: - `otp` -- `u2f` - `webauthn` - `on` @@ -92,7 +79,7 @@ Choose `on` if you would like to require MFA for all users while letting them ch If you have enabled SSO in your Teleport environment, Teleport will conduct its own MFA challenge before sending a request to the identity provider. This means that, even if an attacker has managed to compromise your organization's SSO provider (e.g., by impersonating an administrator), a malicious user will still need to authenticate using valid credentials. -If your `second_factor` configuration is set to `off` and a user creates an account without a second factor, changing `second_factor` to a value that requires MFA will force that user to authenticate with a credential they have not registered. This will lock them out of their account. You have two ways to avoid this scenario: +If your `second_factor` configuration is set to `off` and a user creates an account without a second factor, changing `second_factor` to a value that requires MFA will force that user to authenticate with a credential they have not registered. This will lock them out of their account. You have two ways to avoid this scenario: - Set `second_factor` to `optional` until you have confirmed that existing users have enrolled their MFA devices. - Run the `tctl users reset ` command to force a user to enter new credentials, including any required MFA device. @@ -127,7 +114,7 @@ spec: Create your dynamic resource using `tctl create -f `. - + ## Require dual authorization for role requests Even if an attacker gains access to a user's credentials and successfully signs into your Teleport cluster, you can still prevent the user from escalating their privileges. If you enable dual authorization, users who request to assume a particular role must obtain permission to do so from two or more reviewers. This way, if a malicous user manages to impersonate a legitimate one, reviewers can contact the real user before granting the new role. From 7973b89c91237782de4c671259b00cdbeb960813 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 8 Jun 2022 16:59:36 -0300 Subject: [PATCH 06/31] Document new and modified tsh flags --- docs/pages/access-controls/guides/per-session-mfa.mdx | 5 +++++ docs/pages/setup/reference/cli.mdx | 8 ++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index 14b0622b2d626..c15ecbeffcbab 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -246,6 +246,11 @@ $ tsh ssh prod3.example.com # jerry@prod3.example.com > ``` + +If you are using `tsh` in a constrained environment, you can tell it to use +OTP by doing `tsh --mfa-mode=otp ssh prod3.example.com`. + + If per-session MFA was enabled cluster-wide, Jerry would be prompted for MFA even when logging into `dev1.example.com`. diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index c7ef7e1afcc4e..07be6b2d1ed82 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -154,7 +154,8 @@ information about the cluster. | `-i, --identity` | none | **string** filepath | Identity file | | `--cert-format` | `file` | `file` or `openssh` | SSH certificate format | | `--insecure` | none | none | Do not verify the server's certificate and host name. Use only in test environments. | -| `--auth` | `local` | Any defined [authentication connector](./authentication.mdx) | Specify the type of authentication connector to use. | +| `--auth` | `local` | any defined [authentication connector](./authentication.mdx), including `local` and `passwordless` | Specify the type of authentication connector to use. | +| `--mfa-mode` | auto | `auto`, `cross-platform`, `platform` or `otp` | Preferred mode for MFA and Passwordless assertions. | | `--skip-version-check` | none | none | Skip version checking between server and client. | | `-d, --debug` | none | none | Verbose logging to stdout | | `-J, --jumphost` | none | A jump host | SSH jumphost | @@ -695,11 +696,14 @@ registered devices using [`tsh mfa ls`](cli.mdx#tsh-mfa-ls). $ tsh mfa rm ``` +### tsh environment variables + Environment variables configure your tsh client and can help you avoid using flags repetitively. | Environment Variable | Description | Example Value | | - | - | - | -| TELEPORT_AUTH | Name of a defined SAML, OIDC, or GitHub auth connector | okta | +| TELEPORT_AUTH | Name of a defined local, SAML, OIDC, or Github auth connector | okta | +| TELEPORT_MFA_MODE | Preferred mode for MFA and Passwordless assertions | otp | | TELEPORT_CLUSTER | Name of a Teleport root or leaf cluster | cluster.example.com | | TELEPORT_LOGIN | Login name to be used by default on the remote host | root | | TELEPORT_LOGIN_BIND_ADDR | Address in the form of host:port to bind to for login command webhook | host:port | From 93d94a85a98516fc04dc0f8530e80ca1faedd375 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Fri, 10 Jun 2022 10:33:54 -0300 Subject: [PATCH 07/31] Add a brief explanation of resident keys --- docs/pages/access-controls/guides/passwordless.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index ae65f6873c8a8..8df9b3d710985 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -109,8 +109,12 @@ $ tsh mfa add ``` If you are using a hardware device, a passwordless registration will occupy a -resident key slot. Regardless of your device type, passwordless registrations -may also be used for regular MFA. +resident key slot. Resident keys, also called discoverable credentials, are +stored in persistent memory in the authenticator, unlike MFA keys which are +encrypted by the authenticator and stored in the Teleport Auth Server. + +Regardless of your device type, passwordless registrations may also be used for +regular MFA. If you plan on relying exclusively on passwordless, it's recommended to register From c1f647a53a20c5a06c06485439da2cb3f60c5d5e Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:52:42 -0300 Subject: [PATCH 08/31] Update docs/pages/access-controls/guides/passwordless.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/passwordless.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 8df9b3d710985..d345dfa65b8d7 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -1,6 +1,6 @@ --- title: "Passwordless" -description: Use passwordless authentication +description: Learn how to use passwordless authentication with Teleport. --- Passwordless takes advantage of [WebAuthn](./webauthn.mdx) to provide From d32bc0b1bf8de5caba427dd7c83f200fbeb9b350 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:57:01 -0300 Subject: [PATCH 09/31] Update docs/pages/access-controls/guides/passwordless.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/passwordless.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index d345dfa65b8d7..274f4ec89fcec 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -119,7 +119,7 @@ regular MFA. If you plan on relying exclusively on passwordless, it's recommended to register more than one device. A portable hardware device is ideal, as it can be shared -between `tsh`, Web UI, and different computers. +between `tsh`, the Teleport Web UI, and different computers. From 91a9f638a2a5d2653bbb642308288068ae91cd84 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:57:28 -0300 Subject: [PATCH 10/31] Update docs/pages/access-controls/guides/passwordless.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/passwordless.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 274f4ec89fcec..c694d65bc2b59 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -123,7 +123,7 @@ between `tsh`, the Teleport Web UI, and different computers. -Touch ID registrations are siloed per-application. A Touch ID registration for +Touch ID registrations are isolated by application. A Touch ID registration for `tsh` is different from a registration made from Chrome or Safari. You may register the same Touch ID device from multiple applications to get passwordless access in all of them. From a2f02b6e053e0201dc408b7b336f4b9f1c10adb7 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:57:58 -0300 Subject: [PATCH 11/31] Update docs/pages/access-controls/guides/passwordless.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/passwordless.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index c694d65bc2b59..f4a7b0086fde9 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -252,7 +252,7 @@ Below is a non-comprehensive list of requirements: * Device must support WebAuthn (sometimes also called FIDO2 or CTAP2) * Device must be capable of user verification (biometrics or PIN) -* Device must have PIN set +* Device must have a PIN set. * Device must have fingerprints enrolled (if biometric). This typically means both PIN _and_ fingerprints. From 0523045f8d5e582400f460f2f7fc6ebfbfb305e8 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:58:15 -0300 Subject: [PATCH 12/31] Update docs/pages/access-controls/guides/webauthn.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/webauthn.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index eb4e252998577..2b56a1abade54 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -218,7 +218,7 @@ $ tsh login --proxy=mytenant.teleport.sh ## U2F -Starting on Teleport v10, WebAuthn replaces U2F. If you didn't configure U2F +Starting with Teleport v10, WebAuthn replaces U2F. If you haven't configured U2F before no further action is necessary - any U2F devices are automatically supported. From 9477cefa76f744bc5be853f1a4c00438a038cee9 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:58:35 -0300 Subject: [PATCH 13/31] Update docs/pages/access-controls/guides/webauthn.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/webauthn.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index 2b56a1abade54..e5098ec552cc3 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -219,7 +219,7 @@ $ tsh login --proxy=mytenant.teleport.sh ## U2F Starting with Teleport v10, WebAuthn replaces U2F. If you haven't configured U2F -before no further action is necessary - any U2F devices are automatically +before, no further action is necessary—any U2F devices are automatically supported. If you have an existing U2F configuration, but haven't explicitly configured From d058d03be8a244936359666f6c292fdb0d0890b9 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:59:05 -0300 Subject: [PATCH 14/31] Update docs/pages/access-controls/guides/webauthn.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/webauthn.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index e5098ec552cc3..b30e0b5230960 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -224,7 +224,9 @@ supported. If you have an existing U2F configuration, but haven't explicitly configured WebAuthn yet, Teleport will automatically derive your WebAuthn configuration -from U2F. You may write the WebAuthn configuration yourself, but keep the U2F +from your existing U2F configuration. + +You may write the WebAuthn configuration yourself, but keep the U2F "app_id" field - doing so ensures any already-registered U2F devices won't need to be re-registered. From c73d7bc8858fdc4461580ce54dca93ed4a50d5f1 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:59:14 -0300 Subject: [PATCH 15/31] Update docs/pages/access-controls/guides/webauthn.mdx Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/webauthn.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index b30e0b5230960..d82d48012b6f2 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -227,7 +227,7 @@ WebAuthn yet, Teleport will automatically derive your WebAuthn configuration from your existing U2F configuration. You may write the WebAuthn configuration yourself, but keep the U2F -"app_id" field - doing so ensures any already-registered U2F devices won't need +`app_id` field. Doing so ensures that any already-registered U2F devices won't need to be re-registered. For example, consider the U2F configuration below: From 07d10622390d068e4857c2cb0c9bc77286693002 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 18:55:41 -0300 Subject: [PATCH 16/31] Apply suggestions --- .../access-controls/guides/passwordless.mdx | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index f4a7b0086fde9..382d65bce2695 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -10,10 +10,11 @@ passwordless and usernameless authentication for Teleport. * A Teleport cluster with WebAuthn configured. See the [Second Factor: WebAuthn](./webauthn.mdx) guide. -* A hardware device with support for WebAuthn and resident keys, or a Mac with - biometrics / Touch ID. -* A Web browser with [WebAuthn support]( - https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/). +* A hardware device with support for WebAuthn and resident keys. + As an alternative, you can use a Mac with biometrics / Touch ID. +* A web browser with WebAuthn support. To see if your browser supports + WebAuthn, check the [WebAuthn Compatibility]( + https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) page. * A signed and notarized `tsh` for Touch ID. [Download the macOS tsh installer](../../installation/#macos). @@ -110,8 +111,9 @@ $ tsh mfa add If you are using a hardware device, a passwordless registration will occupy a resident key slot. Resident keys, also called discoverable credentials, are -stored in persistent memory in the authenticator, unlike MFA keys which are -encrypted by the authenticator and stored in the Teleport Auth Server. +stored in persistent memory in the authenticator (i.e., the device that is used +to authenticate). In contrast, MFA keys which are encrypted by the authenticator +and stored in the Teleport Auth Server. Regardless of your device type, passwordless registrations may also be used for regular MFA. @@ -250,11 +252,11 @@ of passwordless logins. Below is a non-comprehensive list of requirements: -* Device must support WebAuthn (sometimes also called FIDO2 or CTAP2) -* Device must be capable of user verification (biometrics or PIN) +* Device must support WebAuthn (sometimes also called FIDO2 or CTAP2). +* Device must be capable of user verification (biometrics or PIN). * Device must have a PIN set. * Device must have fingerprints enrolled (if biometric). This typically means - both PIN _and_ fingerprints. + both a PIN _and_ fingerprints. `tsh` relies in an embedded libfido2 to access hardware devices. If you are running on Linux, you may be missing the necessary udev rules to access your From c112517ed3efc8db5190c019f408f738bdbacd32 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 19:29:43 -0300 Subject: [PATCH 17/31] Keep line lengths consistent --- .../pages/access-controls/guides/webauthn.mdx | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index d82d48012b6f2..13aa8dc6cf1e3 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -5,9 +5,9 @@ videoBanner: vQgKkD4ZRDU --- Teleport supports [WebAuthn](https://webauthn.guide/) as a second authentication -factor. WebAuthn can be used for logging in to Teleport (`tsh login` or the login -page on the Web UI) and for logging in to individual SSH nodes or Kubernetes -clusters (`tsh ssh` and `kubectl`). +factor. WebAuthn can be used for logging in to Teleport (`tsh login` or the +login page on the Web UI) and for logging in to individual SSH nodes or +Kubernetes clusters (`tsh ssh` and `kubectl`). WebAuthn support includes hardware devices, such as YubiKeys or SoloKeys (`tsh` and Web UI), as well as biometric authenticators like Touch ID and Windows Hello @@ -25,8 +25,8 @@ and Web UI), as well as biometric authenticators like Touch ID and Windows Hello ## Step 1/3. Enable WebAuthn support -WebAuthn is disabled by default. To enable WebAuthn support, update your Teleport -configuration as below: +WebAuthn is disabled by default. To enable WebAuthn support, update your +Teleport configuration as below: @@ -212,8 +212,8 @@ $ tsh login --proxy=mytenant.teleport.sh WebAuthn for logging in to Teleport is only required for [local users]( - ../../setup/reference/authentication.mdx#local-no-authentication-connector). SSO users should configure - multi-factor authentication in their SSO provider. + ../../setup/reference/authentication.mdx#local-no-authentication-connector). + SSO users should configure multi-factor authentication in their SSO provider. ## U2F @@ -224,11 +224,11 @@ supported. If you have an existing U2F configuration, but haven't explicitly configured WebAuthn yet, Teleport will automatically derive your WebAuthn configuration -from your existing U2F configuration. +from your existing U2F configuration. -You may write the WebAuthn configuration yourself, but keep the U2F -`app_id` field. Doing so ensures that any already-registered U2F devices won't need -to be re-registered. +You may write the WebAuthn configuration yourself, but keep the U2F `app_id` +field. Doing so ensures that any already-registered U2F devices won't need to be +re-registered. For example, consider the U2F configuration below: From 943d6474519be887ab2b976d87e35459ee50ba56 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 22 Jun 2022 19:09:14 -0300 Subject: [PATCH 18/31] Mention valid device types and passwordless "YES" --- docs/pages/access-controls/guides/passwordless.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 382d65bce2695..cc5005382881f 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -101,14 +101,17 @@ Register your passwordless device using `tsh`: ```code $ tsh mfa add -# Choose device type [TOTP, WEBAUTHN, TOUCHID]: webauthn +# Choose device type [TOTP, WEBAUTHN, TOUCHID]: WEBAUTHN # Enter device name: bio -# Allow passwordless logins [YES, NO]: yes +# Allow passwordless logins [YES, NO]: YES # Tap any *registered* security key # Tap your *new* security key # MFA device "bio" added. ``` +You may pick either `WEBAUTHN` or `TOUCHID` as the device type. Make sure to +answer `YES` to "Allow passwordless logins". + If you are using a hardware device, a passwordless registration will occupy a resident key slot. Resident keys, also called discoverable credentials, are stored in persistent memory in the authenticator (i.e., the device that is used From b79acde9e4ceccd2f1c131a6bed82dfc4fe27cc7 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Thu, 23 Jun 2022 16:19:28 -0300 Subject: [PATCH 19/31] Remove "Configured WebAuthn" section --- .../access-controls/guides/passwordless.mdx | 83 +------------------ 1 file changed, 4 insertions(+), 79 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index cc5005382881f..c1d706879f0f0 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -3,8 +3,8 @@ title: "Passwordless" description: Learn how to use passwordless authentication with Teleport. --- -Passwordless takes advantage of [WebAuthn](./webauthn.mdx) to provide -passwordless and usernameless authentication for Teleport. +Passwordless takes advantage of WebAuthn to provide passwordless and +usernameless authentication for Teleport. ## Prerequisites @@ -18,84 +18,9 @@ passwordless and usernameless authentication for Teleport. * A signed and notarized `tsh` for Touch ID. [Download the macOS tsh installer](../../installation/#macos). -## Step 1/3. Configure WebAuthn - -See the [Second Factor: WebAuthn](./webauthn.mdx) guide for an in-depth -explanation of the WebAuthn configuration. - -A minimal configuration is shown below: - - - - - Auth Server `teleport.yaml` file: - - ```yaml - # snippet from /etc/teleport.yaml: - auth_service: - authentication: - type: local - second_factor: on - webauthn: - rp_id: example.com - ``` - - - 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 - second_factor: on - webauthn: - rp_id: example.com - ``` - - 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`: - -```yaml -kind: cluster_auth_preference -version: v2 -metadata: - name: cluster-auth-preference -spec: - type: local - second_factor: on - webauthn: - rp_id: example.com -``` - -Update the configuration: - -```code -$ tctl create -f cap.yaml -# cluster auth preference has been updated -``` - - -`rp_id` is the public domain of the Teleport Proxy Service, *excluding* protocol -(`https://`) and port number. - A Teleport cluster capable of WebAuthn is automatically capable of passwordless. -## Step 2/3. Register +## Step 1/2. Register Register your passwordless device using `tsh`: @@ -134,7 +59,7 @@ register the same Touch ID device from multiple applications to get passwordless access in all of them. -## Step 3/3. Authenticate +## Step 2/2. Authenticate Authenticate using your passwordless credential: From 94a31f0b449d9f02846ac6d4ed4b74e4d1e3d834 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Thu, 23 Jun 2022 16:22:39 -0300 Subject: [PATCH 20/31] Turn "About Touch ID" admonition into a details section --- .../pages/access-controls/guides/passwordless.mdx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index c1d706879f0f0..62c9c44a916a3 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -52,12 +52,15 @@ more than one device. A portable hardware device is ideal, as it can be shared between `tsh`, the Teleport Web UI, and different computers. - -Touch ID registrations are isolated by application. A Touch ID registration for -`tsh` is different from a registration made from Chrome or Safari. You may -register the same Touch ID device from multiple applications to get passwordless -access in all of them. - +
    + Touch ID registrations are isolated by application. A Touch ID registration + for `tsh` is different from a registration made from Chrome or Safari. You may + register the same Touch ID device from multiple applications to get + passwordless access in all of them. +
    ## Step 2/2. Authenticate From 8371a87b26dcb8e5d3a78a2c2088a0cf7957952e Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Thu, 23 Jun 2022 16:27:36 -0300 Subject: [PATCH 21/31] Drop "Passwordless clusters" admonition --- docs/pages/access-controls/guides/passwordless.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 62c9c44a916a3..f0024c059a7e9 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -79,11 +79,9 @@ $ tsh login --proxy=example.com --auth=passwordless # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - A fully passwordless cluster defaults to passwordless logins, making `--auth=passwordless` unnecessary. See [enable passwordless by default]( #optional-enable-passwordless-by-default). - Look for the passwordless link in the Web UI. From 119a68431a23b51fd05dd3d948d12cd8fbb1f992 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Thu, 23 Jun 2022 16:34:43 -0300 Subject: [PATCH 22/31] Redirect U2F guide to WebAuthn --- docs/config.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/config.json b/docs/config.json index d81d97930ba0c..8df22c4ab6ac2 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1328,6 +1328,11 @@ "source": "/kubernetes-access/helm/reference/teleport-kube-agent/", "destination": "/setup/helm-reference/teleport-kube-agent/", "permanent": true + }, + { + "source": "/access-controls/guides/u2f/", + "destination": "/access-controls/guides/webauthn/", + "permanent": true } ] } From 6f1d53f2dd8ff04cd5523103377a5fd5bb3c1ab8 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Thu, 23 Jun 2022 16:41:14 -0300 Subject: [PATCH 23/31] Change U2F admonition to details --- docs/pages/access-controls/guides/webauthn.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index 13aa8dc6cf1e3..f0696ec46ee66 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -131,9 +131,12 @@ $ tctl create -f cap.yaml ```     - +
    Starting on Teleport v10, WebAuthn replaces U2F. See the [U2F](#u2f) section. - +
    `rp_id` is the public domain of the Teleport Proxy Service, *excluding* protocol (`https://`) and port number. From 2ebd1968ba7682d6c3c382a15fb2b4ffe3964b5e Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Fri, 1 Jul 2022 19:18:24 -0300 Subject: [PATCH 24/31] Add preview markers to passwordless titles and links --- docs/config.json | 2 +- docs/pages/access-controls/guides.mdx | 2 +- docs/pages/access-controls/guides/passwordless.mdx | 6 +++++- docs/pages/access-controls/introduction.mdx | 2 +- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/config.json b/docs/config.json index 8df22c4ab6ac2..8b8fa947aac44 100644 --- a/docs/config.json +++ b/docs/config.json @@ -719,7 +719,7 @@ "slug": "/access-controls/guides/locking/" }, { - "title": "Passwordless", + "title": "Passwordless (Preview)", "slug": "/access-controls/guides/passwordless/" }, { diff --git a/docs/pages/access-controls/guides.mdx b/docs/pages/access-controls/guides.mdx index 877c92a228c2b..294df91c17f13 100644 --- a/docs/pages/access-controls/guides.mdx +++ b/docs/pages/access-controls/guides.mdx @@ -17,7 +17,7 @@ layout: tocless-doc [Impersonating Teleport Users](./guides/impersonation.mdx). Create certs for CI/CD using impersonation.
  • - [Passwordless](./guides/passwordless.mdx). Use passwordless authentication. + [Passwordless](./guides/passwordless.mdx). Use passwordless authentication (Preview).
  • [Second Factor - WebAuthn](./guides/webauthn.mdx). Add Two-Factor Authentication through WebAuthn. diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index f0024c059a7e9..5f5400a2a76d4 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -1,8 +1,12 @@ --- -title: "Passwordless" +title: "Passwordless (Preview)" description: Learn how to use passwordless authentication with Teleport. --- + + Passwordless is currently in Preview. + + Passwordless takes advantage of WebAuthn to provide passwordless and usernameless authentication for Teleport. diff --git a/docs/pages/access-controls/introduction.mdx b/docs/pages/access-controls/introduction.mdx index 5b05938ea2799..56833db802749 100644 --- a/docs/pages/access-controls/introduction.mdx +++ b/docs/pages/access-controls/introduction.mdx @@ -35,7 +35,7 @@ guide. Create certs for CI/CD using impersonation. - Use passwordless authentication. + Use passwordless authentication (Preview). Add Two-Factor Authentication through WebAuthn. From ee8243bd3acc48a478acf51381ce1a752ff03f03 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 6 Jul 2022 17:07:55 -0300 Subject: [PATCH 25/31] Update webauthn.mdx (s/an U2F/a U2F/) Co-authored-by: Paul Gottschling --- docs/pages/access-controls/guides/webauthn.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index f0696ec46ee66..8003bf72cc540 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -236,7 +236,7 @@ re-registered. For example, consider the U2F configuration below: ```yaml -# snippet from /etc/teleport.yaml showing an U2F configuration: +# snippet from /etc/teleport.yaml showing a U2F configuration: auth_service: authentication: type: local From 115c499e334b7771735c8187deaf11cb2f089fac Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 6 Jul 2022 16:56:17 -0300 Subject: [PATCH 26/31] Apply Paul's suggestion --- docs/pages/access-controls/guides/passwordless.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 5f5400a2a76d4..5579bbe3e41dd 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -44,8 +44,8 @@ answer `YES` to "Allow passwordless logins". If you are using a hardware device, a passwordless registration will occupy a resident key slot. Resident keys, also called discoverable credentials, are stored in persistent memory in the authenticator (i.e., the device that is used -to authenticate). In contrast, MFA keys which are encrypted by the authenticator -and stored in the Teleport Auth Server. +to authenticate). In contrast, MFA keys are encrypted by the authenticator and +stored in the Teleport Auth Server. Regardless of your device type, passwordless registrations may also be used for regular MFA. From c4dd2a879583fde77aa4eb119d97412d4ddc9ff7 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 6 Jul 2022 16:59:41 -0300 Subject: [PATCH 27/31] Move MFA comment to paragraph above --- docs/pages/access-controls/guides/passwordless.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 5579bbe3e41dd..8aae07ca82856 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -45,10 +45,8 @@ If you are using a hardware device, a passwordless registration will occupy a resident key slot. Resident keys, also called discoverable credentials, are stored in persistent memory in the authenticator (i.e., the device that is used to authenticate). In contrast, MFA keys are encrypted by the authenticator and -stored in the Teleport Auth Server. - -Regardless of your device type, passwordless registrations may also be used for -regular MFA. +stored in the Teleport Auth Server. Regardless of your device type, passwordless +registrations may also be used for regular MFA. If you plan on relying exclusively on passwordless, it's recommended to register From f4950d39f71bd487b647d9ce0ca989843b666ae7 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 6 Jul 2022 17:05:30 -0300 Subject: [PATCH 28/31] Change link to sentence ("see next section ...") --- docs/pages/access-controls/guides/passwordless.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 8aae07ca82856..b119ee6ca05e6 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -82,8 +82,8 @@ $ tsh login --proxy=example.com --auth=passwordless ``` A fully passwordless cluster defaults to passwordless logins, making -`--auth=passwordless` unnecessary. See [enable passwordless by default]( -#optional-enable-passwordless-by-default). +`--auth=passwordless` unnecessary. See the next section to learn how to enable +passwordless by default. Look for the passwordless link in the Web UI. From 28a293844b5689b17def1657e21a50d9ee16654c Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 6 Jul 2022 17:06:26 -0300 Subject: [PATCH 29/31] Better Web UI admonition --- docs/pages/access-controls/guides/passwordless.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index b119ee6ca05e6..35accbe815ef5 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -86,7 +86,8 @@ A fully passwordless cluster defaults to passwordless logins, making passwordless by default. -Look for the passwordless link in the Web UI. +You can also execute passwordless logins in the Teleport Web UI. To do so, look +for the passwordless link in the Web UI. ## Optional: Enable passwordless by default From 6fd8e1d3e5e5905e9a594a72d037a6a6cc79f141 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 6 Jul 2022 17:18:46 -0300 Subject: [PATCH 30/31] Appease linter --- .../access-controls/guides/passwordless.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 35accbe815ef5..92bda80108e55 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -12,15 +12,15 @@ usernameless authentication for Teleport. ## Prerequisites -* A Teleport cluster with WebAuthn configured. +- A Teleport cluster with WebAuthn configured. See the [Second Factor: WebAuthn](./webauthn.mdx) guide. -* A hardware device with support for WebAuthn and resident keys. +- A hardware device with support for WebAuthn and resident keys. As an alternative, you can use a Mac with biometrics / Touch ID. -* A web browser with WebAuthn support. To see if your browser supports +- A web browser with WebAuthn support. To see if your browser supports WebAuthn, check the [WebAuthn Compatibility]( https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) page. -* A signed and notarized `tsh` for Touch ID. - [Download the macOS tsh installer](../../installation/#macos). +- A signed and notarized `tsh` for Touch ID. + [Download the macOS tsh installer](../../installation.mdx/#macos). A Teleport cluster capable of WebAuthn is automatically capable of passwordless. @@ -174,7 +174,7 @@ $ tctl create -f cap.yaml If you don't see the "Allow passwordless logins" prompt during `tsh mfa add`, you may be using an older version of `tsh`. Download the latest `tsh` from our -[installation page](../../installation). +[installation page](../../installation.mdx). ### Hardware device not usable @@ -184,11 +184,11 @@ of passwordless logins. Below is a non-comprehensive list of requirements: -* Device must support WebAuthn (sometimes also called FIDO2 or CTAP2). -* Device must be capable of user verification (biometrics or PIN). -* Device must have a PIN set. -* Device must have fingerprints enrolled (if biometric). This typically means - both a PIN _and_ fingerprints. +- Device must support WebAuthn (sometimes also called FIDO2 or CTAP2). +- Device must be capable of user verification (biometrics or PIN). +- Device must have a PIN set. +- Device must have fingerprints enrolled (if biometric). This typically means + both a PIN *and* fingerprints. `tsh` relies in an embedded libfido2 to access hardware devices. If you are running on Linux, you may be missing the necessary udev rules to access your @@ -200,7 +200,7 @@ necessary udev rules. If you are having trouble with Touch ID, make sure that you are using the latest standalone version of `tsh`. [Download the macOS tsh installer]( -../../installation/#macos). +../../installation.mdx/#macos). Touch ID support requires Macs with the Touch Bar and Secure Enclave. It also requires macOS >= 10.13 (macOS High Sierra). From 60e41c378a3877519187b2eee7c16f6ac0c8aca2 Mon Sep 17 00:00:00 2001 From: Alan Parra Date: Wed, 6 Jul 2022 17:25:27 -0300 Subject: [PATCH 31/31] Appease linter again --- docs/pages/access-controls/guides/passwordless.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index 92bda80108e55..fab927b4ff9c7 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -20,7 +20,7 @@ usernameless authentication for Teleport. WebAuthn, check the [WebAuthn Compatibility]( https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) page. - A signed and notarized `tsh` for Touch ID. - [Download the macOS tsh installer](../../installation.mdx/#macos). + [Download the macOS tsh installer](../../installation.mdx#macos). A Teleport cluster capable of WebAuthn is automatically capable of passwordless. @@ -200,7 +200,7 @@ necessary udev rules. If you are having trouble with Touch ID, make sure that you are using the latest standalone version of `tsh`. [Download the macOS tsh installer]( -../../installation.mdx/#macos). +../../installation.mdx#macos). Touch ID support requires Macs with the Touch Bar and Secure Enclave. It also requires macOS >= 10.13 (macOS High Sierra).