mirror of
https://github.com/gravitational/teleport
synced 2024-10-20 17:23:22 +00:00
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.
This commit is contained in:
Brian Joerger
GitHub
parent
9d84f8d379
commit
1f4d13f4ac
|
|
@ -50,6 +50,7 @@
|
|||
"Distroless",
|
||||
"Divio's",
|
||||
"EBSCSI",
|
||||
"ECCP",
|
||||
"ECMWF",
|
||||
"EKCert",
|
||||
"ERRO",
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
</Admonition>
|
||||
|
||||
<Admonition type="warning" title="Compatibility Issues">
|
||||
Hardware key support provides the best security available.
|
||||
However, there are some limitations in the services that support hardware keys.
|
||||
<Admonition type="warning" title="Compatibility">
|
||||
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.
|
||||
</Admonition>
|
||||
|
||||
## Prerequisites
|
||||
|
|
@ -68,13 +68,8 @@ like `tctl edit`. With touch required, hardware key support provides better secu
|
|||
- A series 5+ YubiKey
|
||||
|
||||
<Admonition type="note" title="PIV support">
|
||||
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.
|
||||
</Admonition>
|
||||
|
||||
- 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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue