From 1f4d13f4ac382243ef0c24dc1ed3d1838e65f4dd Mon Sep 17 00:00:00 2001 From: Brian Joerger Date: Tue, 17 Oct 2023 17:29:23 -0700 Subject: [PATCH] Update hardware key support docs (#33553) * Update hardware key support docs with details on: * Hardware Key PIN option * Custom PIV slot/key instructions * WebUI enabled details * Resolve comments. * Fix typo. --- docs/cspell.json | 1 + .../guides/hardware-key-support.mdx | 100 ++++++++++++------ 2 files changed, 68 insertions(+), 33 deletions(-) diff --git a/docs/cspell.json b/docs/cspell.json index d0702f60254..a94f88a9dcd 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -50,6 +50,7 @@ "Distroless", "Divio's", "EBSCSI", + "ECCP", "ECMWF", "EKCert", "ERRO", diff --git a/docs/pages/access-controls/guides/hardware-key-support.mdx b/docs/pages/access-controls/guides/hardware-key-support.mdx index 8e791cc0d1f..19b77f4d461 100644 --- a/docs/pages/access-controls/guides/hardware-key-support.mdx +++ b/docs/pages/access-controls/guides/hardware-key-support.mdx @@ -31,9 +31,8 @@ like `tctl edit`. With touch required, hardware key support provides better secu A user's touch is cached on the hardware security key for 15 seconds to prevent excessive touch prompts. - - Hardware key support provides the best security available. - However, there are some limitations in the services that support hardware keys. + + Hardware key support provides the best security available. However, not all services are compatible with hardware keys. Supported: @@ -42,11 +41,13 @@ like `tctl edit`. With touch required, hardware key support provides better secu - Server access. - Database access with `tsh proxy db` instead of `tsh db connect`. - Kubernetes access with `tsh proxy kube` instead of `tsh kube login`. - + - Teleport Web UI + - Web sessions are not backed by a hardware key directly, but they are strictly guarded by the + Auth/Proxy services. Therefore, web sessions are given permission to bypass hardware key support + and fallback to MFA prompts when user presence or verification is needed, like for per-session MFA. + Not yet supported: - - Teleport Web UI (except for user registration and reset password). - - Agent forwarding functionality such as `tsh ssh -A`, Proxy Recording mode, and OpenSSH integration. - Desktop access. - Application access. @@ -57,8 +58,7 @@ like `tctl edit`. With touch required, hardware key support provides better secu To navigate these incompatibilities, we recommend that you enable hardware key support only when necessary, such as for roles with access to critical infrastructure. These roles can be accessed as needed with Access Requests so that users can avoid these issues for their normal login - sessions. We also recommend trying [Teleport Connect](../../connect-your-client/teleport-connect.mdx) - as an alternative to the Teleport Web UI. + sessions. ## Prerequisites @@ -68,13 +68,8 @@ like `tctl edit`. With touch required, hardware key support provides better secu - A series 5+ YubiKey - Hardware key support requires users to use a PIV-compatible hardware key. + Hardware key support requires users to use a PIV-compatible hardware key. Currently, this feature is only guaranteed to support YubiKey series 5+. - - Teleport clients use PIV slot 9a for the `hardware_key` option and 9c for the `hardware_key_touch` option, - and will overwrite other keys and certificates in those slots, as needed. - This behavior might interfere with other PIV applications, like `yubikey-agent`, - so we recommend only using one PIV application at a time. - Install a smart card driver for you operating system. Teleport clients will connect to your YubiKey through the smart card driver to generate keys and perform cryptographic operations. @@ -86,6 +81,14 @@ like `tctl edit`. With touch required, hardware key support provides better secu ## Step 1/2. Enforce hardware key support Hardware key support is not required by default. + +There are three primary options for hardware key support: + - `hardware_key`: User keys are stored on their hardware key without touch/PIN protection. A separate MFA check is used for + sessions and other MFA-reliant features, like moderated sessions. + - `hardware_key_touch`: User keys are stored on their hardware key with touch protection. On each request, users must touch their hardware key. + - `hardware_key_touch_and_pin`: User keys will be stored on their hardware key with touch and PIN protection. On each request, users must touch their hardware key and enter their PIV pin. + - Users who have not set a PIV code are prompted to set it during login. + You can enforce hardware key support for specific roles, as shown here: ```yaml @@ -200,20 +203,51 @@ $ tsh clusters # example.com online root * ``` -## Configuring hardware key support with per-session MFA +## Custom PIV setup -For existing users of per-session MFA, upgrading to `hardware_key_touch` might seem disruptive because it affects -all access requests rather than just session requests. -Although upgrading to `hardware_key_touch` provides the best security, you can get a similar level of security -by combining hardware key support with per-session MFA. +### Custom PIV Slot -You can configure this combined functionality by specifying `require_session_mfa: hardware_key` in the `role` and `cluster_auth_preference` settings. -This option continues to use per-session MFA checks for starting sessions and requires hardware-based private keys for all Teleport requests. +By default, Teleport clients use the following PIV slots for each option: + - `hardware_key`: slot `9a` + - `hardware_key_touch`: slot `9c` + - `hardware_key_pin`: slot `9d` + - `hardware_key_and_pin`: slot `9e` -This configuration prevents basic data exfiltration attacks for Teleport sessions and requests. -However, since MFA is only required for sessions, non-session requests like `tctl edit` can still -be used by an attacker with remote access to the user's computer with the user's private key -available through the connected hardware device. +If you are using any other PIV applications, you might need to specify a different slot. +For example, `yubikey-agent` uses slot `9a`. To avoid overwriting the `yubikey-agent` key and certificate, +a user with the `hardware_key` requirement would need to specify a different slot. + +During login, users can specify a PIV slot using the `--piv-slot` command-line option or an environment variable. +For example: + - `tsh login --piv-slot=9c` + - `TELEPORT_PIV_SLOT=9c tsh login` + +The PIV slot can also be set cluster-wide with a configuration option: + +```yaml +kind: cluster_auth_preference +metadata: + ... + name: cluster-auth-preference +spec: + ... + require_session_mfa: hardware_key + piv_slot: 9c + ... +version: v2 +``` + +### Custom Key + +Teleport clients generate keys in the slots specified using the default management key. + +If your PIV key uses a different management key, you must generate the key yourself. +This can be done with the [YubiKey Manager CLI](https://developers.yubico.com/yubikey-manager/): + +`ykman piv keys generate -a ECCP256 [slot] --touch-policy=[never|cached|always] --pin-policy=[never|once|always] -` + +After running this command, you're prompted to enter your management key to complete the request. +Make sure that the touch and PIN policy satisfy the hardware key requirement for your cluster and roles. ## Troubleshooting @@ -223,15 +257,15 @@ This error is returned by the Auth and Proxy services if a user does not meet th Both `tsh` and Teleport Connect automatically catch these errors and require the user to sign in again with a valid hardware-based private key. If you see this error, make sure that your client is up to date (v11.0.0+). -This error is also displayed in the Teleport Web UI if a role or cluster require a hardware key because the -Web UI doesn't support hardware-based private keys. - ### `ERROR: authenticating with management key: auth challenge: smart card error 6982: security status not satisfied` -Smart card auth challenge errors can appear when the wrong Management key or PIN is used. -Teleport clients expect a fresh PIV module with the default Management and PIN keys. -You can reset these keys, along with any existing PIV keys and certificates, with the -[yubikey manager tool command](https://developers.yubico.com/yubikey-manager/) `ykman piv reset`. +Smart card auth challenge errors can appear when the wrong management key is used. + +Teleport clients expect a fresh PIV key with the default management key. +You can reset this key, along with any existing PIV keys and certificates, with the +[YubiKey Manager CLI](https://developers.yubico.com/yubikey-manager/) `ykman piv reset`. + +If you want to use a different management key, follow the [custom PIV setup instructions](#custom-piv-setup). ### `ERROR: ssh: handshake failed: command failed: transmitting request: an attempt was made to end a non-existent transaction` @@ -240,7 +274,7 @@ Sometimes, PIV interactions with your Yubikey can fail in unexpected ways. For example, if you tap your Yubikey for MFA and then subsequently tap your Yubikey for Hardware Key support, you might get an error on rare occasions. -### Why am I being asked to tap X times to login? +### Why am I being asked to tap several times to login? Depending on your settings, you might be asked to tap your Yubikey many times. Each tap is necessary to safely authenticate you.