self-hosted/teleport
self-hosted/teleport
1
0
Fork 0
mirror of https://github.com/gravitational/teleport synced 2024-10-19 16:53:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Hardware Key docs (#17258)

Browse source
This commit is contained in:
Brian Joerger 2022-10-20 13:01:06 -07:00 committed by GitHub
parent e47df397b8
commit 3001cfad07
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 231 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
docs/config.json
View file

@ -219,6 +219,11 @@
"title": "Moderated Sessions",
"slug": "/access-controls/guides/moderated-sessions/",
"forScopes": ["enterprise", "cloud"]
},
{
"title": "Hardware Key Support (Preview)",
"slug": "/access-controls/guides/hardware-key-support/",
"forScopes": ["enterprise", "cloud"]
}
]
},

223
docs/pages/access-controls/guides/hardware-key-support.mdx Normal file
View file

@ -0,0 +1,223 @@
---
title: Hardware Key Support (Preview)
description: Hardware Key Support
---
## Introduction
<Admonition type="warning" title="Preview">
Hardware key Support is currently in Preview mode.
</Admonition>
By default, `tsh`, Teleport Connect, and other Teleport clients store a user's login session directly on their filesystem. If a user's filesystem is compromised, any of their active Teleport login sessions would also be compromised.
[Per-session MFA](per-session-mfa.mdx) provides a way to require an MFA presence check with a user's login session, but this check is only used for starting sessions with Teleport services (SSH, Kube, DB, etc.). This means that non-session actions, like administrative commands run with `tctl`, can still be run with an exfiltrated login session.
To prevent these types of exfiltration attacks altogether, Teleport clients support hardware-based private keys. Unlike disk-based private keys, hardware-based private keys are generated and stored directly on a hardware device and are impossible to export. With this feature, a user's login session is only functional with access to the user's hardware device.
Additionally, this feature can be configured to require touch for every Teleport request, including non-session requests. With touch required, hardware key support provides better security in comparison to our per-session MFA offering.
<Admonition type="note" title="touch caching">
A user's touch is cached on the YubiKey for 15 seconds to prevent excessive touch prompts.
</Admonition>
<Admonition type="warning" title="Compatibility Issues">
Hardware key support provides the best security available, but it is a new feature with some compatiblity trade-offs. We hope to improve compatibility in the future.
Supported (`tsh`, `tctl`, and Teleport Connect):
- Standard Teleport API requests (`tsh ls`, `tctl create`, etc.)
- Server Access
- Database Access
- Must use `tsh proxy db` instead of `tsh db connect`
- Application Access
Not yet supported:
- Teleport WebUI (except for user registration / reset password)
- Agent forwarding functionality such as `tsh ssh -A`, Proxy Recording mode, and OpenSSH integration
- Kubernetes Access
- Desktop Access
To navigate these incompatiblities, we recommend enabling 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.
</Admonition>
## Prerequisites
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
- A series 5+ YubiKey
<Admonition type="note" title="PIV support">
Hardware key support requires users to use a PIV-compatible hardware key. Currently, this feature is only guarenteed 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 certs in these slots as needed. This may interfere with other PIV applications, like `yubikey-agent`, so we recommend only using one PIV application at a time.
</Admonition>
(!docs/pages/includes/tctl.mdx!)
## Step 1/2. Enforce Hardware Key Support
Hardware key support is not required by default. You can enforce hardware key support for specific roles, as shown here:
```yaml
kind: role
metadata:
name: admin
spec:
allow:
require_session_mfa: hardware_key_touch
```
You can also enforce hardware key support cluster-wide by updating your Teleport configuration as below:
<ScopedBlock scope={["enterprise"]}>
<Tabs>
<TabItem label="Static Config">
In the Auth Server's `teleport.yaml` file:
```yaml
# snippet from /etc/teleport.yaml:
auth_service:
authentication:
require_session_mfa: hardware_key_touch
```
</TabItem>
<TabItem label="Dynamic resources">
Obtain your existing `cluster_auth_preference` resource:
```code
$ tctl get cap > cap.yaml
```
If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.
Ensure that `cap.yaml` includes the following content:
```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
require_session_mfa: hardware_key_touch
```
Update the configuration:
```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```
</TabItem>
</Tabs>
</ScopedBlock>
<ScopedBlock scope={["cloud"]}>
Obtain your existing `cluster_auth_preference` resource:
```code
$ tctl get cap > cap.yaml
```
If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.
Ensure that `cap.yaml` includes the following content:
```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
require_session_mfa: hardware_key_touch
```
Update the configuration:
```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```
</ScopedBlock>
## Step 2/2. Log In
Once hardware key support is enforced, affected users will be required to have their login sessions backed by a Hardware Key for all Teleport requests.
These users will be prompted to connect and touch their YubiKey on log in:
<ScopedBlock scope={["enterprise"]}>
```code
$ tsh login --user=dev --proxy=proxy.example.com:3080
# Enter password for Teleport user dev:
# Tap your YubiKey
# > Profile URL: https://example.com
# Logged in as: dev
# Cluster: example.com
# Roles: access, editor
# Logins: bjoerger
# Kubernetes: enabled
# Valid until: 2022-10-11 01:53:44 -0700 PDT [valid for 8h0m0s]
# Extensions: permit-X11-forwarding, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy
```
</ScopedBlock>
<ScopedBlock scope={["cloud"]}>
```code
$ tsh login --proxy=mytenant.teleport.sh
# Enter password for Teleport user dev:
# Tap your YubiKey
# > Profile URL: https://example.com
# Logged in as: dev
# Cluster: example.com
# Roles: access, editor
# Logins: bjoerger
# Kubernetes: enabled
# Valid until: 2022-10-11 01:53:44 -0700 PDT [valid for 8h0m0s]
# Extensions: permit-X11-forwarding, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy
```
</ScopedBlock>
Affected users with existing sessions not backed by a hardware key will be prompted to re-login on their next request:
```code
$ tsh clusters
# Unmet private key policy "hardware_key_touch"
# Relogging in with YubiKey generated private key.
# Enter password for Teleport user dev:
# Tap your YubiKey
# Cluster Name Status Cluster Type Labels Selected
# ----------- ------ ------------ ------ --------
# example.com online root *
```
## Configuring Hardware Key Support with Per-session MFA
For existing users of per-session MFA, upgrading to `hardware_key_touch` may be disruptive, as it requires touch on all requests as opposed to only session requests. While this upgrade would yield the best security, we can get a very similar level of security by combining hardware key support with per-session MFA.
For users who want this mash-up of functionality, you can use the `require_session_mfa: hardware_key` option in both roles and cluster auth preference settings. This option will continue to use per-session MFA checks while also requiring hardware-based private keys for all Teleport requests.
This prevents basic data exfiltration attacks for Teleport sesssion and non-session requests. However, it does not prevent hacking attacks with non-session Teleport requests, since gaining access to a user's computer would provide both their certificates on disk and a local connection to their YubiKey, assuming its connected.
## Troubleshooting
### `ERROR: private key policy not met`
This error is returned by the Auth and Proxy servers when a user does not meet their required private key policy. Both `tsh` and Teleport Connect will automatically catch these errors and initiate re-login with a valid hardware-based private key. If you are getting this error, make sure that your client is up to date (v11.0.0+).
This error may also appear in the WebUI, since the WebUI does not 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 Mangement 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 certs, with the [yubikey manager tool command](https://developers.yubico.com/yubikey-manager/) `ykman piv reset`.

2
docs/pages/access-controls/reference.mdx
View file

@ -105,7 +105,7 @@ The table below documents the behavior of each option if multiple roles are assi
| `max_sessions` | Total number of session channels which can be established across a single SSH connection via Teleport | |
| `enhanced_recording` | Indicates which events should be recorded by the BFP-based session recorder | |
| `permit_x11_forwarding` | Allow users to enable X11 forwarding with OpenSSH clients and servers | |
| `require_session_mfa` | Require additional MFA tap before initiating a session | Logical "OR" i.e. evaluates to "yes" if at least one role requires session MFA |
| `require_session_mfa` | Enforce per-session MFA or PIV-hardware key restrictions on user login sessions (`no`, `yes`, `hardware_key`, `hardware_key_touch`) | For per-session MFA, Logical "OR" i.e. evaluates to "yes" if at least one role requires session MFA |
| `lock` | Locking mode (`strict` or `best_effort`) | `strict` wins in case of conflict |
| `request_access` | Enterprise-only Access Request strategy (`optional`, `always` or `reason`) | |
| `request_prompt` | Prompt for the Access Request "reason" field | |

4
docs/pages/reference/terraform-provider.mdx
View file

@ -280,7 +280,7 @@ Options specify session, connection and auditing permissions of the role.
| `port_forwarding` | bool | Port forwarding |
| `request_access` | string | Access request strategy (optional\|note\|always) |
| `request_prompt` | string | An optional message which tells users what they aught to |
| `require_session_mfa` | bool | Specifies whether a user is required to do an MFA check for every session |
| `require_session_mfa` | bool/string | Enforce per-session MFA or PIV-hardware key restrictions on user login sessions |
## teleport_provision_token
@ -476,6 +476,6 @@ Spec contains parameters of a resource.
| `u2f.app_id` | string | The application ID for universal second factor |
| `u2f.facets` | string list | The facets for universal second factor |
| `u2f.device_attestation_cas` | string list | Trusted attestation CAs for U2F devices |
| `require_session_mfa` | bool | Causes all sessions in this cluster to require MFA checks |
| `require_session_mfa` | bool/string | Enforce per-session MFA or PIV-hardware key restrictions on all user login sessions |
| `disconnect_expired_cert` | bool | If true, connections with expired client certificates will get disconnected |
| `allow_local_auth` | bool | If true, local authentication is enabled |