Add/update docs for passwordless, WebAuthn and U2F (#13314)

Add a batch of public documentation changes that cover:

* Passwordless (new guide and various links)
* WebAuthn updates in regards to U2F
* U2F documentation removal (superseded by WebAuthn)
* Updated config reference (`teleport.yaml` and equivalents)
* Updated `tsh` reference

This should cover the bulk of the work under Passwordless (#9160) and U2F sunset (#10375).

#9160

Co-authored-by: Paul Gottschling <[email protected]>

docs/config.json

@@ -718,6 +718,10 @@
               "title": "Session Locking",
               "slug": "/access-controls/guides/locking/"
             },
+            {
+              "title": "Passwordless (Preview)",
+              "slug": "/access-controls/guides/passwordless/"
+            },
             {
               "title": "Second Factor - WebAuthn",
               "slug": "/access-controls/guides/webauthn/"
@@ -1324,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
     }
   ]
 }

docs/pages/access-controls/guides.mdx

@@ -16,6 +16,9 @@ layout: tocless-doc
   <li>
     [Impersonating Teleport Users](./guides/impersonation.mdx). Create certs for CI/CD using impersonation.
   </li>
+  <li>
+    [Passwordless](./guides/passwordless.mdx). Use passwordless authentication (Preview).
+  </li>
   <li>
     [Second Factor - WebAuthn](./guides/webauthn.mdx). Add Two-Factor Authentication through WebAuthn.
   </li>

docs/pages/access-controls/guides/passwordless.mdx

@@ -0,0 +1,292 @@
+---
+title: "Passwordless (Preview)"
+description: Learn how to use passwordless authentication with Teleport.
+---
+
+<Admonition type="tip" title="Preview">
+  Passwordless is currently in Preview.
+</Admonition>
+
+Passwordless takes advantage of WebAuthn 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.
+  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.mdx#macos).
+
+A Teleport cluster capable of WebAuthn is automatically capable of passwordless.
+
+## Step 1/2. 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.
+```
+
+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
+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.
+
+<Admonition type="tip" title="Important">
+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`, the Teleport Web UI, and different computers.
+</Admonition>
+
+<Details
+  title="Registering Touch ID for tsh"
+  opened={true}
+>
+  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.
+</Details>
+
+## Step 2/2. 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 the next section to learn how to enable
+passwordless by default.
+
+<Admonition type="tip" title="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.
+</Admonition>
+
+## 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:
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+<Tabs>
+  <TabItem label="Static Config">
+    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
+    ```
+  </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
+      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
+    ```
+  </TabItem>
+</Tabs>
+</ScopedBlock>
+
+<ScopedBlock scope={["cloud"]}>
+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
+```
+</ScopedBlock>
+
+## 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.mdx).
+
+### 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 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
+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.mdx#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:
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+<Tabs>
+  <TabItem label="Static Config">
+    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
+    ```
+  </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
+      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
+    ```
+  </TabItem>
+</Tabs>
+</ScopedBlock>
+
+<ScopedBlock scope={["cloud"]}>
+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
+```
+</ScopedBlock>

docs/pages/access-controls/guides/per-session-mfa.mdx

@@ -246,6 +246,11 @@ $ tsh ssh prod3.example.com
 # [email protected] >
 ```
 
+<Admonition title="Tip" type="tip">
+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`.
+</Admonition>
+
 If per-session MFA was enabled cluster-wide, Jerry would be prompted for MFA
 even when logging into `dev1.example.com`.
 
@@ -283,11 +288,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.