diff --git a/docs/config.json b/docs/config.json index 12db712e6d6c3..302b80b8d6cf2 100644 --- a/docs/config.json +++ b/docs/config.json @@ -345,23 +345,35 @@ "slug": "/access-controls/device-trust/", "forScopes": [ "enterprise", - "cloud" + "cloud", + "team" ], "entries": [ { - "title": "Set Up Device Trust", + "title": "Getting Started", "slug": "/access-controls/device-trust/guide/", "forScopes": [ "enterprise", - "cloud" + "cloud", + "team" ] }, { - "title": "Set Up Auto-Enrollment", - "slug": "/access-controls/device-trust/auto-enrollment/", + "title": "Manage Trusted Devices", + "slug": "/access-controls/device-trust/device-management/", "forScopes": [ "enterprise", - "cloud" + "cloud", + "team" + ] + }, + { + "title": "Enforce Device Trust", + "slug": "/access-controls/device-trust/enforcing-device-trust/", + "forScopes": [ + "enterprise", + "cloud", + "team" ] }, { @@ -1551,6 +1563,11 @@ } ], "variables": { + "clusterDefaults": { + "clusterName": "teleport.example.com", + "username": "myuser", + "nodeIP": "ip-172-31-35-170" + }, "ansible": { "min_version": "2.9.6" }, @@ -2659,6 +2676,11 @@ "destination": "/access-controls/device-trust/guide/", "permanent": true }, + { + "source": "/access-controls/device-trust/auto-enrollment/", + "destination": "/access-controls/device-trust/device-management/", + "permanent": true + }, { "source": "/management/guides/teleport-operator/", "destination": "/management/dynamic-resources/teleport-operator/", diff --git a/docs/img/access-controls/device-trust/hosted-jamf.png b/docs/img/access-controls/device-trust/hosted-jamf.png new file mode 100644 index 0000000000000..a7e0ed329e0c5 Binary files /dev/null and b/docs/img/access-controls/device-trust/hosted-jamf.png differ diff --git a/docs/img/access-controls/device-trust/select-jamf.png b/docs/img/access-controls/device-trust/select-jamf.png new file mode 100644 index 0000000000000..d517f5b32fe5d Binary files /dev/null and b/docs/img/access-controls/device-trust/select-jamf.png differ diff --git a/docs/pages/access-controls/device-trust.mdx b/docs/pages/access-controls/device-trust.mdx index 3a871e13a68e0..d3b7dbac6d7fd 100644 --- a/docs/pages/access-controls/device-trust.mdx +++ b/docs/pages/access-controls/device-trust.mdx @@ -1,31 +1,97 @@ --- title: Device Trust (Preview) -description: Use and enforce trusted devices with Teleport +description: Teleport Device Trust Concepts layout: tocless-doc +videoBanner: gBQyj_X1LVw --- -Device Trust is currently in Preview mode. + Device Trust is currently in Preview mode and supports following components: + + - User devices: macOS and Windows. + - Teleport client: `tsh` and Teleport connect. + - Resources: SSH, Database and Kubernetes. + + Support for other operating systems, access from Web UI and application + access is planned for upcoming Teleport versions. +## Concepts + Device Trust allows Teleport admins to enforce the use of trusted devices. Resources protected by the device mode "required" will enforce the use of a trusted device, in addition to establishing the user's identity and enforcing the necessary roles. Furthermore, users using a trusted device leave audit trails that include the device's information. -The device trust preview works on macOS and Windows devices and supports the -following Teleport features: +Device Trust requires two of the following steps to have been configured: + +- Trusted device registered and enrolled with Teleport. +- Device enforcement mode configured via either a role or a cluster-wide config. + +Categorically, we define these two requirements as Trusted Device management +and Device Trust enforcement. + +## Trusted Device management + +Device management is divided into two separate phases: inventory management and +device enrollment. + +**Inventory management** is performed by a device admin. In this step, devices +are registered or removed from Teleport. For example, this happens when the IT +department of your company acquires new devices, or retires devices from use. + +Inventory management can be manually operated using `tctl` or automatically synced +with a Mobile Device Management (MDM) solution such as Jamf Pro. + +**Device enrollment** is performed either by a device admin or by the end-user, +at your discretion. This is the step that creates the Secure Enclave private key +in the device and registers its public key counterpart with the Teleport Auth +Server. Enrollment has to run on the actual device that you want to enroll. For +example, this happens when a user gets a new device for the first time, or when +IT prepares a new device for a user. Enrollment only needs to happen once per +user/device combination. + +Enrollment exchanges an enrollment token, created by a +device admin, for the opportunity to enroll the corresponding device. + +### How trust is established with the device + +Device Trust leverages dedicated secure hardware in devices to store device credentials +and perform device challenges. The specific implementation varies between types of devices. + +On macOS devices, Device Trust uses the Secure Enclave in order to store a +device private key. That key is used to solve device challenges issued by the +Teleport Auth Service, proving the identity of the trusted device. + +On Windows devices, a Trusted Platform Module (TPM) is used to perform an +attestation as to the state of the device. This attestation is signed by a +private key that is also protected by the TPM. + +The signed attestation ensures that the Teleport Auth Service knows both the state +of the device and that the request has come from the device. + +That said, a device is as "trustworthy" as the enrollment process. If enrollment operator +enrolls a malicious device to Teleport, establishing trust with Secure Enclave or TPM is +already defeated at this point. The more trusted the enrollment environment and operator, +the better the ongoing guarantees that the device itself is trustworthy. + +## Device Trust enforcement + +Enforcing Device Trust means configuring Teleport with device trust mode, i.e. applying +`device_trust_mode: required` rule, which tells Teleport Auth Service to only allow access +with a trusted and an authenticated device, in addition to establishing the user's identity and enforcing +the necessary roles. -- SSH access enforcement -- Database access enforcement -- Kubernetes access enforcement +Teleport supports two methods for device enforcement: Role-based +enforcement and Cluster-wide enforcement. -Support for other operating systems and access features is planned for upcoming -Teleport versions. +- **Role-based enforcement** can be used to enforce Device Trust at role level, using RBAC. +- **Cluster-wide enforcement** can be used to enforce Device Trust at cluster level. ## Guides -- [Set Up Device Trust](./device-trust/guide.mdx) -- [Set Up Auto-Enrollment](./device-trust/auto-enrollment.mdx) +- [Getting Started with Device Trust](./device-trust/guide.mdx) +- [Device Management](./device-trust/device-management.mdx) +- [Enforcing Device Trust](./device-trust/enforcing-device-trust.mdx) - [Jamf Pro Integration](./device-trust/jamf-integration.mdx) diff --git a/docs/pages/access-controls/device-trust/auto-enrollment.mdx b/docs/pages/access-controls/device-trust/auto-enrollment.mdx deleted file mode 100644 index 1e4f398405155..0000000000000 --- a/docs/pages/access-controls/device-trust/auto-enrollment.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Set Up Auto-Enrollment (Preview) -description: Set Up Automatic Enrollment for Registered Devices ---- - -Auto-enrollment allows `tsh` to automatically enroll devices already registered -in Teleport during the user's login. The registration may be -[manual](./guide.mdx#step-12-register-a-trusted-device) or performed using an -integration, like the [Jamf Pro integration](./jamf-integration.mdx). - - -Device Trust is currently in Preview mode. - - -## Prerequisites - -(!docs/pages/includes/commercial-prereqs-tabs.mdx!) - -(!docs/pages/includes/device-trust/prereqs.mdx!) - -- [A previously-registered device]( - ./guide.mdx#step-12-register-a-trusted-device) is necessary for - auto-enrollment to take place. - -## Step 1/2. Enable auto-enrollment - -Enable auto-enrollment in your cluster settings: - - - -Modify the dynamic config resource using `tctl edit cluster_auth_preference`: - -```diff -kind: cluster_auth_preference -version: v2 -metadata: - name: cluster-auth-preference -spec: - # ... - device_trust: - mode: "required" -+ auto_enroll: true -``` - - - -Edit the Auth Server's `teleport.yaml` file: - -```diff -auth_service: - authentication: - # ... - device_trust: -+ auto_enroll: true -``` - -After saving the changes, restart the Teleport service. - - - - -## Step 2/2. Login using a registered device - -Using a device previously registered in Teleport, logout and login again: - -```code -$ tsh logout -$ tsh login --proxy=teleport.example.com --user=alice -All users logged out. -Enter password for Teleport user alice: -Tap any security key -Detected security key tap -> Profile URL: https://teleport.example.com:443 - Logged in as: alice - Cluster: teleport.example.com - Roles: access, editor - Logins: alice - Kubernetes: enabled - Valid until: 2023-06-23 02:47:05 -0300 -03 [valid for 12h0m0s] - Extensions: teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id -``` - -The presence of the **teleport-device-\*** extensions shows that the device was -successfully enrolled and authenticated. - -## Troubleshooting - -(!docs/pages/includes/device-trust/auto-enroll-troubleshooting.mdx!) diff --git a/docs/pages/access-controls/device-trust/device-management.mdx b/docs/pages/access-controls/device-trust/device-management.mdx new file mode 100644 index 0000000000000..aa3a7a7b9c62e --- /dev/null +++ b/docs/pages/access-controls/device-trust/device-management.mdx @@ -0,0 +1,385 @@ +--- +title: Manage Trusted Devices (Preview) +description: Learn how to manage Trusted Devices +--- + + +The device trust preview works on macOS and Windows devices. Support for other operating +systems and access features is planned for upcoming Teleport versions. + + +### Prerequisites + +(!docs/pages/includes/no-oss-prereqs-tabs.mdx!) + +(!docs/pages/includes/device-trust/prereqs.mdx!) + +## Register a trusted device + +The `tctl` tool is used to manage the device inventory. A device admin is +responsible for managing devices, adding new devices to the inventory and +removing devices that are no longer in use. + + + Users with the preset `editor` or `device-admin` role (since v13.3.6) + can register and enroll their device in a single step with the following command: + ```code + $ tsh device enroll --current-device + ``` + + + +Teleport supports device synchronization with [Jamf Pro](./jamf-integration.mdx). Once configured, devices +are automatically updated in Teleport's device inventory. + + +Before you can enroll the device, you need to register it. To register +a device, you first need to determine its serial number. + +Retrieve device serial number with `tsh` (must be run on the device you want to register): +```code +$ tsh device asset-tag +(=devicetrust.asset_tag=) +``` + +
+ + + The serial number is visible under Apple menu -> "About This Mac" -> "Serial number". + + + + Windows devices can have multiple serial numbers depending on the configuration made by the manufacturer. + Teleport will pick the first available value from the following: + - System asset tag + - System serial number + - Baseboard serial number + + To find the value chosen by Teleport, run the following command: + + ```code + $ tsh device collect + DeviceCollectedData { + ... + "serial_number": "(=devicetrust.asset_tag=)", + ... + } + ``` + + +
+Use the serial number to register device: + + + Replace + with the serial number obtained from the device you wish to enroll and run `tctl devices add` command: + + ```code + $ tctl devices add --os=macos --asset-tag="" + Device /macos added to the inventory + ``` + + Use `tctl` to check that the device has been registered: + + ```code + $ tctl devices ls + Asset Tag OS Enroll Status Device ID + ------------ ----- ------------- ------------------------------------ + (=devicetrust.asset_tag=) macOS not enrolled (=devicetrust.device_id=) + ``` + + + + Replace + with the serial number obtained from the device you wish to enroll and run `tctl devices add` command: + + ```code + $ tctl devices add --os=windows --asset-tag="" + Device /windows added to the inventory + ``` + + Use `tctl` to check that the device has been registered: + + ```code + $ tctl devices ls + Asset Tag OS Enroll Status Device ID + ------------ ----- ------------- ------------------------------------ + (=devicetrust.asset_tag=) windows not enrolled (=devicetrust.device_id=) + ``` + + + + + For clusters created after v13.3.6, Teleport supports preset `device-admin` role to manage devices. + + For clusters created using Teleport v12 or newer, the preset `editor` role has + the necessary permissions to manage devices. For clusters created before v12, you may want + to create a dedicated [`device-admin`](#dedicated-device-admin-role) role. + + +## Create a device enrollment token + +A registered device becomes a trusted device after it goes through the +enrollment ceremony. To enroll the device, a device enrollment token is +necessary. The token is created by a device admin and sent to the person +performing the enrollment off-band (for example, via a corporate chat). + +To create an enrollment token run the command below, where `--asset-tag` is +the serial number of the device we want to enroll: + +```code +$ tctl devices enroll --asset-tag="(=devicetrust.asset_tag=)" +Run the command below on device "(=devicetrust.asset_tag=)" to enroll it: +tsh device enroll --token=(=devicetrust.enroll_token=) +``` + +## Enroll a trusted device + +To perform the enrollment ceremony, using the device specified above, type the +command printed by `tctl devices enroll`: + +```code +$ tsh device enroll --token=(=devicetrust.enroll_token=) +Device "(=devicetrust.asset_tag=)"/macOS enrolled + +$ tsh logout +$ tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=) # fetch new certificates +Enter password for Teleport user (=clusterDefaults.username=): +Tap any security key +Detected security key tap +> Profile URL: (=clusterDefaults.clusterName=):443 + Logged in as: (=clusterDefaults.username=) + Cluster: (=clusterDefaults.clusterName=) + Roles: access, editor + Logins: (=clusterDefaults.username=) + Kubernetes: enabled + Valid until: 2023-06-23 02:47:05 -0300 -03 [valid for 12h0m0s] + Extensions: teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id +``` +The presence of the `teleport-device-*` extensions shows that the device was +successfully enrolled and authenticated. The device above is now a trusted device. + +## Auto-Enrollment + +Distributing enrollment tokens to many users can be challenging. To address that, +Teleport supports auto-enrollment. When enabled, auto-enrollment automatically +enrolls the user's device in their next Teleport (`tsh`) login. + +For auto-enrollment to work, the following conditions must be met: +- A device must be registered. Registration may be +[manual](#register-a-trusted-device) or performed using an +integration, like the [Jamf Pro integration](./jamf-integration.mdx). +- Auto-enrollment must be enabled in the cluster setting. +- User must have either preset `editor` or `device-enroll` (available v13.3.6+) role assigned to them. + +Enable auto-enrollment in your cluster settings: + + + +Modify the dynamic config resource using `tctl edit cluster_auth_preference`: + +```diff +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + # ... + device_trust: + mode: "required" ++ auto_enroll: true +``` + + + +Edit the Auth Server's `teleport.yaml` file: + +```diff +auth_service: + authentication: + # ... + device_trust: ++ auto_enroll: true +``` + +After saving the changes, restart the Teleport service. + + + + +Once enabled, user's with their device registered in Teleport and with the required permission +(preset `editor` or `device-enroll` role) will have their device enrolled to Teleport in +their next login. + +```code +$ tsh logout +All users logged out. +$ tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=) +Enter password for Teleport user (=clusterDefaults.username=): +Tap any security key +Detected security key tap +> Profile URL: (=clusterDefaults.clusterName=):443 + Logged in as: (=clusterDefaults.username=) + Cluster: (=clusterDefaults.clusterName=) + Roles: access, editor + Logins: (=clusterDefaults.username=) + Kubernetes: enabled + Valid until: 2023-06-23 02:47:05 -0300 -03 [valid for 12h0m0s] + Extensions: teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id +``` + +The presence of the `teleport-device-*` extensions shows that the device was +successfully enrolled and authenticated. + +## Remove a trusted device + +A device that is no longer in use may be removed using `tctl devices rm +--device-id=` or `tctl devices rm --asset-tag=` + +First, find a device to delete: +```code +$ tctl devices ls +Asset Tag OS Enroll Status Device ID +------------ ----- ------------- ------------------------------------ +C00AA0AAAA0A macOS enrolled c9cbb327-68a8-497e-b820-6a4b2bf58269 +``` + +Now use asset-tag or device id to delete a device: +```code +# Delete using asset tag: +$ tctl devices rm --asset-tag=C00AA0AAAA0A +Device "C00AA0AAAA0A" removed + +# Delete using device id: +$ tctl devices rm --device-id=c9cbb327-68a8-497e-b820-6a4b2bf58269 +Device "c9cbb327-68a8-497e-b820-6a4b2bf58269" removed +``` + +## Dedicated device admin role + +We recommend creating a dedicated `device-admin` role for device inventory +management. + + + Teleport version 13.3.6 and above has the preset `device-admin` role, which + is a substitute for the role described below. + + +Following is an example of a role that grants permissions for the `device` resource is necessary to manage +the inventory. Save the yaml below as `device-admin.yaml` and create it in your +cluster: + +```yaml +version: v6 +kind: role +metadata: + name: device-admin +spec: + allow: + rules: + - resources: ["device"] + verbs: + - create + - read + - list + - update + - delete + - create_enroll_token + - enroll +``` + +```code +$ tctl create -f device-admin.yaml +role 'device-admin' has been created +``` + +Note that in addition to the usual CRUD verbs (create, read, list, update and +delete), we have also included `create_enroll_token` and `enroll`. The +`create_enroll_token` verb is necessary to execute the `tctl devices enroll` +command; `enroll` is necessary to execute `tsh device enroll`. + + +## Configuring a TPM EKCert CA allow-list + +This advice only applies to Device Trust on platforms that use TPMs. For now, +this is just Windows. + +Some TPMs include a certificate—known as an EKCert—signed by the +manufacturer's certificate authority (CA). This certificate allows a third party +(such a Teleport cluster) to know that the TPM it is communicating with is +legitimate. This significantly reduces the burden on the administrator to ensure +that the device has not been tampered with prior to enrollment. + +By default, the Teleport cluster does not verify the EKCert. This is because +not all TPMs include an EKCert, and it is not possible to verify an EKCert +without knowledge of the manufacturer's CA. This verification is enabled by the +inclusion of the Teleport configuration field called `ekcert_allowed_cas`. + +Once configured, only devices that include a TPM with an EKCert signed by a +CA specified in the field will be able to enroll. Previously-enrolled devices +will not be affected. + +To configure `ekcert_allowed_cas`, you must first obtain the CA certificate in +PEM format from the manufacturer of the TPM included in your devices. This step +varies from manufacturer to manufacturer. + +After you obtain the CA certificate in PEM format, there are two ways of +configuring `ekcert_allowed_cas`: + +- Statically using the Teleport configuration file. This is the simplest + option, but is not possible for Teleport Cloud clusters and not recommended + for clusters in a highly available configuration. +- Dynamically using `cluster_auth_preference` resource. This works with all + clusters and is the most flexible. + + + +Modify the dynamic config resource using `tctl edit cluster_auth_preference`: + +```diff +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + ... + device_trust: + mode: "required" # add this line ++ ekcert_allowed_cas: ++ # The CA is configured inline within the resource: ++ - | ++ -----BEGIN CERTIFICATE----- ++ --snip-- ++ -----END CERTIFICATE----- +``` + + + +Edit the Auth Server's `teleport.yaml` file and restart: + +```diff +auth_service: + authentication: + ... + device_trust: ++ ekcert_allowed_cas: ++ # The CA can be configured inline within the configuration file: ++ - | ++ -----BEGIN CERTIFICATE----- ++ --snip-- ++ -----END CERTIFICATE----- ++ # Or, it can be configured in the configuration file using a path: ++ - /path/to/my/ekcert-ca.pem +``` + + + + +## Troubleshooting + +(!docs/pages/includes/device-trust/enroll-troubleshooting.mdx!) + +## Next steps + +- [Device Trust Enforcement](./enforcing-device-trust.mdx) +- [Jamf Pro Integration](./jamf-integration.mdx) \ No newline at end of file diff --git a/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx new file mode 100644 index 0000000000000..2990f5460bcab --- /dev/null +++ b/docs/pages/access-controls/device-trust/enforcing-device-trust.mdx @@ -0,0 +1,191 @@ +--- +title: Enforce Device Trust (Preview) +description: Learn how to enforce trusted devices with Teleport +videoBanner: gBQyj_X1LVw +--- + + +The device trust preview only supports SSH, Database and Kubernetes resources. +Support for other resources is planned for upcoming Teleport versions. + + +Resources protected by the device mode "required" will enforce the use of a +trusted device, in addition to establishing the user's identity and enforcing +the necessary roles. Furthermore, users using a trusted device leave audit +trails that include the device's information. + +Device Trust enforcement can be configured with the following three modes of operation, represented +by the `device_trust_mode` authentication setting: + +- `off` - disables device trust. Device authentication is not performed and + device-aware audit logs are absent. +- `optional` - enables device authentication and device-aware audit, but does + not require a trusted device to access resources. +- `required` - enables device authentication and device-aware audit. + Additionally, it requires a trusted device for all SSH, Database and + Kubernetes connections. + +### Prerequisites +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/device-trust/prereqs.mdx!) + +## Role-based trusted device enforcement + +Role-based configuration enforces trusted device access at the role level. It +can be configured with the `spec.options.device_trust_mode` option and +applies to the resources in its `allow` rules. It +works similarly to [`require_session_mfa`](../guides/per-session-mfa.mdx). + + + Teleport version 13.3.6 and above has the preset `require-trusted-device` role. + Make sure you update the "allow" rules in the role according to your requirements. + + +To enforce authenticated device checks for a specific role, update the role with +the following: + +```diff +kind: role +version: v6 +metadata: + name: require-trusted-device +spec: + options: + # require authenticated device check for this role ++ device_trust_mode: "required" # add this line + allow: + logins: ['admin'] + kubernetes_groups: ['edit'] + node_labels: + '*': '*' + ... + +``` + +```code +$ tctl create -f device-enforcement.yaml +``` + +## Cluster-wide trusted device enforcement + +Cluster-wide configuration enforces trusted device access at the cluster level. +Enterprise clusters run in `optional` mode by default. Changing the mode to +`required` will enforce a trusted device for all SSH, Database and Kubernetes +accesses. + + +The Web UI is not capable of trusted device access during the device trust +preview. Only `tsh` and Teleport Connect are able to fulfill device mode +`required`. + + +To enable device mode `required` update your configuration as follows: + + + +Create a `cap.yaml` file or get the existing configuration using +`tctl get cluster_auth_preference`: + +```diff +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: "on" + webauthn: + rp_id: (=clusterDefaults.clusterName=) + device_trust: ++ mode: "required" # add this line +``` + +Update the configuration: + +```code +$ tctl create -f cap.yaml +cluster auth preference has been updated +``` + +You can also edit this configuration directly: + +```code +$ tctl edit cluster_auth_preference +``` + + + +Edit the Auth Server's `teleport.yaml` file and restart all Auth Services: + +```diff +auth_service: + authentication: + type: local + second_factor: "on" + webauthn: + rp_id: (=clusterDefaults.clusterName=) + device_trust: ++ mode: "required" # add this line +``` + + + + +Once the config is updated, SSH, Database and Kubernetes access without a trusted device will be forbidden. +For example, SSH access without a trusted device fails with the following error: + +```code +$ tsh ssh (=clusterDefaults.nodeIP=) +ERROR: ssh: rejected: administratively prohibited (unauthorized device) +``` + + +It is possible to use [trusted +clusters](../../management/admin/trustedclusters.mdx) to limit the impact of +device mode `required`. A leaf cluster in mode `required` will enforce access to +all of its resources, without imposing the same restrictions to the root +cluster. Likewise, a root cluster will not enforce device trust on resources in +leaf clusters. + + +## Locking a device + +Similar to [session and identity locking](../guides/locking.mdx), a device can +be locked using `tctl lock`. + +Locking blocks certificate issuance and ongoing or future accesses originating +from a locked device. Locking a device only works if device trust is enabled and +if the device is enrolled to Teleport. + +Find a device ID to lock: + +```code +$ tctl devices ls +Asset Tag OS Enroll Status Device ID +------------ ----- ------------- ------------------------------------ +(=devicetrust.asset_tag=) macOS enrolled (=devicetrust.device_id=) +``` + +Lock a device: + +```code +$ tctl lock --device=(=devicetrust.device_id=) --ttl=12h +Created a lock with name "5444970a-39a0-4814-968d-e58b4a8fa686". +``` + +Now, if a user on that device tries to access an SSH server for example, +Teleport will deny access: + +```code +$ tsh ssh (=clusterDefaults.nodeIP=) +ERROR: ssh: rejected: administratively prohibited (lock targeting Device:"(=devicetrust.device_id=)" is in force) +``` + +## Troubleshooting + +(!docs/pages/includes/device-trust/enroll-troubleshooting.mdx!) + +## Next steps +- [Device Management](./device-management.mdx) +- [Jamf Pro Integration](./jamf-integration.mdx) \ No newline at end of file diff --git a/docs/pages/access-controls/device-trust/guide.mdx b/docs/pages/access-controls/device-trust/guide.mdx index 5994dcb409e44..232e8bb4c662e 100644 --- a/docs/pages/access-controls/device-trust/guide.mdx +++ b/docs/pages/access-controls/device-trust/guide.mdx @@ -1,462 +1,205 @@ --- -title: Set Up Device Trust (Preview) -description: Learn how to use and enforce trusted devices with Teleport +title: Getting Started with Device Trust (Preview) +description: Get started with Teleport Device Trust videoBanner: gBQyj_X1LVw --- -Device Trust is currently in Preview mode. - - -## Concepts - -Device Trust leverages dedicated secure hardware in devices to store sensitive -credentials. The specific implementation varies between types of devices. - -On macOS devices, Device Trust uses the Secure Enclave in order to store a -device private key. That key is used to solve device challenges issued by the -Teleport Auth Server, proving the identity of the trusted device. - -On Windows devices, a Trusted Platform Module (TPM) is used to perform an -attestation as to the state of the device. This attestation is signed by a -private key that is also protected by the TPM. The signed attestation ensures -that the Teleport Auth Server knows both the state of the device and that the -request has come from the device. - -Device management is divided into two separate phases: inventory management and -device enrollment. - -**Inventory management** is performed by a device admin. In this step, devices -are registered or removed from Teleport. For example, this happens when the IT -department of your company acquires new devices, or retires devices from use. - -**Device enrollment** is performed either by a device admin or by the end-user, -at your discretion. This is the step that creates the Secure Enclave private key -in the device and register its public key counterpart with the Teleport Auth -Server. Enrollment has to run in the actual device that you want to enroll. For -example, this happens when a user gets a new device for the first time, or when -IT prepares a new device for a user. Enrollment only needs to happen once per -user/device combination. - - -Device enrollment is key in correctly identifying a device throughout its -lifetime. The more trusted the enrollment operator, the better the ongoing -guarantees that the device itself is trustworthy. - - -The tie between the device inventory and enrollment is a device enrollment -token. A device enrollment token needs to be created by a device admin and sent -to the person performing the enrollment ceremony. The token ties the actual -device being enrolled to the expected device in the inventory, adding an extra -layer of protection. - -## Prerequisites - -(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + Device Trust is currently in Preview mode and supports following components: -(!docs/pages/includes/device-trust/prereqs.mdx!) - -## Step 1/2. Register a trusted device - -The `tctl` tool is used to manage the device inventory. A device admin is -responsible for managing devices, adding new devices to the inventory and -removing devices that are no longer in use. - -A role that grants permissions for the `device` resource is necessary to manage -the inventory. Save the yaml below as `device-admin.yaml` and create it in your -cluster: + - User devices: macOS and Windows. + - Teleport client: `tsh` and Teleport connect. + - Resources: SSH, Database and Kubernetes. -```yaml -version: v6 -kind: role -metadata: - name: device-admin -spec: - allow: - rules: - - resources: ["device"] - verbs: - - create - - read - - list - - update - - delete - - create_enroll_token - - enroll -``` - -```code -$ tctl create -f device-admin.yaml -role 'device-admin' has been created -``` - - -For clusters created using Teleport v12 or newer, the builtin role `editor` has -the necessary permissions to manage devices. For production setups a separate -role is still recommended. + Support for other operating systems, access from Web UI and application + access is planned for upcoming Teleport versions. -Note that in addition to the usual CRUD verbs (create, read, list, update and -delete), we have also included `create_enroll_token` and `enroll`. The -`create_enroll_token` verb is necessary to execute the `tctl devices enroll` -command; `enroll` is necessary to execute `tsh device enroll`. Both are -demonstrated in the following section. +Device Trust requires two of the following steps to have been configured: -Make sure your user has the `device-admin` role: +- Device enforcement mode configured via either a role or a cluster-wide config. +- Trusted device registered and enrolled with Teleport. -(!/docs/pages/includes/add-role-to-user.mdx role="device-admin"!) +In this guide, you will update an existing user profile to assign the preset `require-trusted-device` +role and then enroll a trusted device into Teleport to access a resource (a test linux server) +protected with Teleport. -Relogin to fetch updated certificates: +### Prerequisites -```code -$ tsh logout; tsh login --proxy=teleport.example.com --user=alice -``` +(!docs/pages/includes/no-oss-prereqs-tabs.mdx!) -Before you can enroll the device, you need to register it. To register -a device, you first need to determine its serial number. - - - - The serial number of a macOS device can be determined in two ways. - - Through the UI, visible under Apple -> "About This Mac" -> "Serial number". +(!docs/pages/includes/device-trust/prereqs.mdx!) - Through the terminal: +- User with `editor` role. + ```code + $ tsh status + > Profile URL: (=clusterDefaults.clusterName=):443 + Logged in as: (=clusterDefaults.username=) + Cluster: (=clusterDefaults.clusterName=) + Roles: access, auditor, editor + Logins: root, ubuntu, ec2-user + Kubernetes: disabled + Valid until: 2023-08-22 03:30:24 -0400 EDT [valid for 11h52m0s] + Extensions: login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy + ``` +- Access to a linux server (any Linux server you can access via `tsh ssh` will do). + ```code + $ tsh ls + Node Name Address Labels + ---------------- -------------- -------------------------------------- + (=clusterDefaults.nodeIP=) ⟵ Tunnel + + # test connection to (=clusterDefaults.nodeIP=) + $ tsh ssh root@(=clusterDefaults.nodeIP=) + root@(=clusterDefaults.nodeIP=):~# + ``` + +Once the above prerequisites are met, begin with the following step. + +## Step 1/2. Update user profile to enforce Device Trust + +To enforce Device Trust, a user must be assigned with a role with Device Trust mode "required". + +For this guide, we will use the preset `require-trusted-device` role to update current user profile. + + The preset `require-trusted-device` role, as referenced in this guide, is only available + from Teleport version 13.3.6 and above. For older Teleport cluster, you will need to update + a role with `device_trust_mode: required`. + +
+ For simplicity, the example below updates the preset `access` role but you can update + any existing access granting role which the user is assigned with to enforce Device Trust. + + First, fetch a role so you can update it locally: ```code - $ ioreg -c IOPlatformExpertDevice -d 2 | grep -i IOPlatformSerialNumber | awk -F'"' '{print $4}' - (=devicetrust.asset_tag=) + $ tctl edit role/access ``` - - - - Determining the serial number for a device running Windows is a little more - complicated than on macOS. This is because Windows devices can have multiple - serial numbers depending on the configuration made by the manufacturer. - Teleport will pick the first available value from the following: + Edit the role with device trust mode: + ```diff + kind: role + metadata: + labels: + teleport.internal/resource-type: preset + name: access + spec: + allow: + logins: + - '{{internal.logins}}' + ... + options: + # require authenticated device check for this role + + device_trust_mode: "required" # add this line + ... + deny: + ... - - System asset tag - - System serial number - - Baseboard serial number - - To find the value chosen by Teleport, run the following command: - - ```code - $ tsh device collect - DeviceCollectedData { - ... - "serial_number": "(=devicetrust.asset_tag=)", - ... - } ``` - - -Replace -with the serial number obtained from the device you wish to enroll and -with `macos` or `windows`, and execute the following command: + Save your edits. -```code -$ tctl devices add --os="" --asset-tag="" -Device / added to the inventory -``` - -Use `tctl` to check that the device has been registered: - -```code -$ tctl devices ls -Asset Tag OS Enroll Status Device ID ------------- ----- ------------- ------------------------------------ -(=devicetrust.asset_tag=) macOS not enrolled (=devicetrust.device_id=) -``` - - -A device that is no longer in use may be removed using `tctl devices rm ---device-id=` or `tctl devices rm --asset-tag=`. + Now that the `access` role is configured with device mode "required", users with + this role will be enforced with Device Trust. +
-## Step 2/2. Enroll a trusted device - -A registered device becomes a trusted device after it goes through the -enrollment ceremony. Enrollment exchanges an enrollment token, created by a -device admin, for the opportunity to enroll the corresponding device. - -A device enrollment is specifically linked to the user who performed the -enrollment. If the same device is handed to a new user, that user must enroll -the device again. - -To create an enrollment token run the following command, where `--asset-tag` is -the serial number of the device we want to enroll. - -```code -$ tctl devices enroll --asset-tag="(=devicetrust.asset_tag=)" -Run the command below on device "(=devicetrust.asset_tag=)" to enroll it: -tsh device enroll --token=(=devicetrust.enroll_token=) -``` - -To perform the enrollment ceremony, using the device specified above, type the -command printed by `tctl devices enroll`: +First, let's fetch the user profile locally so we can update it with the preset `require-trusted-device` role. ```code -$ tsh device enroll --token=(=devicetrust.enroll_token=) -Device "(=devicetrust.asset_tag=)"/macOS enrolled - -$ tsh logout -$ tsh login --proxy=teleport.example.com --user=alice # fetch new certificates +$ tctl get users/(=clusterDefaults.username=) > (=clusterDefaults.username=).yaml ``` - -On Windows, the `tsh device enroll` command attempts to elevate to -administrator privileges on the device. Privilege elevation is required to -perform a TPM Credential Activation. This step is only required for -enrollment and is not required on future device authentications. - - -The device above is now a trusted device. - -## Recommended: Configuring a TPM EKCert CA allow-list - -This advice only applies to Device Trust on platforms that use TPMs. For now, -this is just Windows. - -Some TPMs include a certificate—known as an EKCert—signed by the -manufacturer's certificate authority (CA). This certificate allows a third party -(such a Teleport cluster) to know that the TPM it is communicating with is -legitimate. This significantly reduces the burden on the administrator to ensure -that the device has not been tampered with prior to enrollment. - -By default, the Teleport cluster does not verify the EKCert. This is because -not all TPMs include an EKCert, and it is not possible to verify an EKCert -without knowledge of the manufacturer's CA. This verification is enabled by the -inclusion of the Teleport configuration field called `ekcert_allowed_cas`. - -Once configured, only devices that include a TPM with an EKCert signed by a -CA specified in the field will be able to enroll. Previously-enrolled devices -will not be affected. - -To configure `ekcert_allowed_cas`, you must first obtain the CA certificate in -PEM format from the manufacturer of the TPM included in your devices. This step -varies from manufacturer to manufacturer. - -After you obtain the CA certificate in PEM format, there are two ways of -configuring `ekcert_allowed_cas`: - -- Statically using the Teleport configuration file. This is the simplest - option, but is not possible for Teleport Cloud clusters and not recommended - for clusters in a highly available configuration. -- Dynamically using `cluster_auth_preference` resource. This works with all - clusters and is the most flexible. - - - -Modify the dynamic config resource using `tctl edit cluster_auth_preference`: - +Edit the profile: ```diff -kind: cluster_auth_preference -version: v2 +kind: user metadata: - name: cluster-auth-preference + id: 1692716146877042322 + name: (=clusterDefaults.username=) spec: + created_by: + time: "2023-08-14T13:42:22.291972449Z" + expires: "0001-01-01T00:00:00Z" + roles: + - access + - auditor + - editor ++ - require-trusted-device # add this line + status: + is_locked: false ... - device_trust: - mode: "required" # add this line -+ ekcert_allowed_cas: -+ # The CA is configured inline within the resource: -+ - | -+ -----BEGIN CERTIFICATE----- -+ --snip-- -+ -----END CERTIFICATE----- -``` - - - -Edit the Auth Server's `teleport.yaml` file and restart: - -```diff -auth_service: - authentication: - ... - device_trust: -+ ekcert_allowed_cas: -+ # The CA can be configured inline within the configuration file: -+ - | -+ -----BEGIN CERTIFICATE----- -+ --snip-- -+ -----END CERTIFICATE----- -+ # Or, it can be configured in the configuration file using a path: -+ - /path/to/my/ekcert-ca.pem -``` - - - - -## Optional: Cluster-wide trusted device enforcement - -Cluster-wide configuration enforces trusted device access at the cluster level. -It can be configured with the following three modes of operation, represented -by the `device_trust.mode` authentication setting: - -- `off` - disables device trust. Device authentication is not performed and - device-aware audit logs are absent. -- `optional` - enables device authentication and device-aware audit, but does - not require a trusted device to access resources. -- `required` - enables device authentication and device-aware audit. - Additionally, it requires a trusted device for all SSH, Database and - Kubernetes connections. - -Enterprise clusters run in `optional` mode by default. Changing the mode to -`required` will enforce a trusted device for all SSH, Database and Kubernetes -accesses. - - -The Web UI is not capable of trusted device access during the device trust -preview. Only `tsh` and Teleport Connect are able to fulfill device mode -`required`. - - -To enable device mode `required` update your configuration as follows: - - - -Create a `cap.yaml` file or get the existing configuration using -`tctl get cluster_auth_preference`: - -```diff -kind: cluster_auth_preference -version: v2 -metadata: - name: cluster-auth-preference -spec: - type: local - second_factor: "on" - webauthn: - rp_id: teleport.example.com - device_trust: -+ mode: "required" # add this line ``` -Update the configuration: +Save and update user: ```code -$ tctl create -f cap.yaml -cluster auth preference has been updated +$ tctl create -f (=clusterDefaults.username=).yaml ``` -You can also edit this configuration directly: +Now that the user profile is updated to enforce Device Trust, try to access the test server +again. ```code -$ tctl edit cluster_auth_preference +$ tsh logout; tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=) +$ tsh ssh root@(=clusterDefaults.nodeIP=) +ERROR: access denied to root connecting to (=clusterDefaults.nodeIP=):0 ``` - - -Edit the Auth Server's `teleport.yaml` file and restart all Auth Services: +As you can verify from the above step, access to `(=clusterDefaults.nodeIP=)` ssh server, +which was previously accessible, is now forbidden. -```diff -auth_service: - authentication: - type: local - second_factor: "on" - webauthn: - rp_id: teleport.example.com - device_trust: -+ mode: "required" # add this line -``` +## Step 2/2. Enroll device - - +To access `(=clusterDefaults.nodeIP=)` server again, you will have to enroll your device. -SSH, Database and Kubernetes access without a trusted device is now forbidden. -For example, SSH access without a trusted device fails with the following error: +Enrolling your device is easy, and can be done using `tsh` client: ```code -$ tsh ssh server1 -ERROR: ssh: rejected: administratively prohibited (unauthorized device) +$ tsh enroll device --current-device +Device "(=devicetrust.asset_tag=)"/macOS registered and enrolled ``` - -It is possible to use [trusted -clusters](../../management/admin/trustedclusters.mdx) to limit the impact of -device mode `required`. A leaf cluster in mode `required` will enforce access to -all of its resources, without imposing the same restrictions to the root -cluster. Likewise, a root cluster will not enforce device trust on resources in -leaf clusters. + + The `--current-device` flag tells `tsh` to enroll current device. User must have the preset `editor` + or `device-admin` role to be able to self-enroll their device. For users without the `editor` or + `device-admin` roles, an enrollment token must be generated by a device admin, which can then be + used to enroll the device. Learn more about manual device enrollment in the + [device management guide](./device-management.mdx#register-a-trusted-device) -## Optional: Role-based trusted device enforcement +Relogin to fetch updated certificate with device extension: -Role-based configuration enforces trusted device access at the role level. It -can be configured with the `spec.options.device_trust_mode` (`required`, -`optional`, `off`) option and applies to the resources in its `allow` rules. It -works similar to [`require_session_mfa`](../guides/per-session-mfa.mdx). - -To enforce authenticated device checks for a specific role, update the role with -the following: - -```diff -kind: role -version: v6 -metadata: - name: example-role -spec: - options: - # require authenticated device check for this role -+ device_trust_mode: "required" # add this line - allow: - logins: ['admin'] - kubernetes_groups: ['edit'] - node_labels: - '*': '*' - ... +```code +$ tsh logout; tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=) +$ tsh status +> Profile URL: (=clusterDefaults.clusterName=):443 + Logged in as: (=clusterDefaults.username=) + Cluster: (=clusterDefaults.clusterName=):443 + Roles: access, auditor, editor + Logins: root + Kubernetes: enabled + Valid until: 2023-08-22 04:06:53 -0400 EDT [valid for 12h0m0s] + Extensions: login-ip, ... teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id ``` - -Per-role configuration let's you progressively block unauthorized device access, -and is useful for getting started with Teleport Device Trust. - -Once all the devices used are enrolled in Teleport, cluster-wide -configuration will ensure every resources can only ever be accessed with a -trusted device. - - -## Optional: Locking a device +The presence of the `teleport-device-*` extensions shows that the device was successfully authenticated. -Similar to [session and identity locking](../guides/locking.mdx), a device can -be locked using `tctl lock`. +Now, let's try to access server (`(=clusterDefaults.nodeIP=)`) again: -Locking blocks certificate issuance and ongoing or future accesses originating -from a locked device. Locking a device only works if device trust is enabled and -if the device is enrolled to Teleport. - -Find a device ID to lock: - -```code -$ tctl devices ls -Asset Tag OS Enroll Status Device ID ------------- ----- ------------- ------------------------------------ -(=devicetrust.asset_tag=) macOS enrolled (=devicetrust.device_id=) -``` - -Lock a device: - -```code -$ tctl lock --device (=devicetrust.device_id=) --ttl=12h -Created a lock with name "5444970a-39a0-4814-968d-e58b4a8fa686". +```bash +$ tsh ssh root@(=clusterDefaults.nodeIP=) +root@(=clusterDefaults.nodeIP=):~# ``` -Now, if a user on that device tries to access an SSH server for example, -Teleport will deny access: - -```code -$ tsh ssh server1 -ERROR: ssh: rejected: administratively prohibited (lock targeting Device:"(=devicetrust.device_id=)" is in force) -``` +Congratulations! You have successfully configured a Trusted Device and accessed a resource protected with +Device Trust enforcement. -## Optional: Enable auto-enrollment +## Troubleshooting -Refer to the [auto-enrollment guide](./auto-enrollment.mdx). +(!docs/pages/includes/device-trust/enroll-troubleshooting.mdx!) -## Troubleshooting +## Next steps -(!docs/pages/includes/device-trust/auto-enroll-troubleshooting.mdx!) +- [Device Management](./device-management.mdx) +- [Enforcing Device Trust](./enforcing-device-trust.mdx) +- [Jamf Pro Integration](./jamf-integration.mdx) diff --git a/docs/pages/access-controls/device-trust/jamf-integration.mdx b/docs/pages/access-controls/device-trust/jamf-integration.mdx index c4a54d7642615..4e8e1496de7c3 100644 --- a/docs/pages/access-controls/device-trust/jamf-integration.mdx +++ b/docs/pages/access-controls/device-trust/jamf-integration.mdx @@ -12,11 +12,9 @@ both incremental (called "partial") and full syncs, as well as removals from Teleport if a computer is removed from Jamf Pro. Syncing devices from Jamf Pro is an **inventory management** step, equivalent to -automatically running the corresponding `tctl devices add` commands. If you want -to automatically enroll synced devices on user login, refer to the -[auto-enrollment](#optional-enable-auto-enrollment) section. +automatically running the corresponding `tctl devices add` commands. -See the [Device Trust guide](./guide.mdx) for fundamental Device Trust concepts +See the [Device Trust guide](../device-trust.mdx) for fundamental Device Trust concepts and behavior. ## Prerequisites @@ -53,6 +51,17 @@ Create a readonly Jamf user for inventory sync. ## Step 2/4. Configure Jamf service + + Teleport Cloud users can quickly get started with Jamf integration by using + the hosted Jamf plugin in the Web UI. +
+ Select the Jamf plugin: + ![Select Jamf plugin](../../../img/access-controls/device-trust/select-jamf.png) + Fill in the required information and click "Connect Jamf" button: + ![Configure Jamf plugin](../../../img/access-controls/device-trust/hosted-jamf.png) +
+ + Jamf inventory sync is performed by a separate `teleport` process, configured using the `jamf_service` key. It is recommended to run the service isolated from other Teleport processes, as it requires the Jamf credentials created in the @@ -64,7 +73,7 @@ Save the following file as `/var/lib/teleport.yaml` and edit as needed: version: v3 teleport: # Necessary to write devices back to Teleport. - proxy_server: teleport.example.com:443 # CHANGEME + proxy_server: (=clusterDefaults.clusterName=):443 # CHANGEME jamf_service: enabled: true @@ -256,7 +265,7 @@ service has a different "jamf\_service.name". For example: ```diff version: v3 teleport: - proxy_server: teleport.example.com:443 + proxy_server: (=clusterDefaults.clusterName=):443 jamf_service: enabled: true @@ -299,6 +308,7 @@ ssh_service: enabled: false ``` -## Optional: Enable auto-enrollment +## Next steps -Refer to the [auto-enrollment guide](./auto-enrollment.mdx). +Automatically enroll synced devices on user login with +[auto-enrollment](./device-management.mdx#auto-enrollment). diff --git a/docs/pages/access-controls/guides/locking.mdx b/docs/pages/access-controls/guides/locking.mdx index e51edd869103e..a5af1c2425318 100644 --- a/docs/pages/access-controls/guides/locking.mdx +++ b/docs/pages/access-controls/guides/locking.mdx @@ -28,7 +28,7 @@ A lock can target the following objects or attributes: - a Teleport user by the user's name - a Teleport [RBAC](../reference.mdx) role by the role's name - a Teleport [trusted device]( - ../device-trust/guide.mdx#optional-locking-a-device) by the device ID + ../device-trust/enforcing-device-trust.mdx#locking-a-device) by the device ID - an MFA device by the device's UUID - an OS/UNIX login - a Teleport agent by the agent's server UUID (effectively unregistering it from the diff --git a/docs/pages/includes/device-trust/auto-enroll-troubleshooting.mdx b/docs/pages/includes/device-trust/enroll-troubleshooting.mdx similarity index 60% rename from docs/pages/includes/device-trust/auto-enroll-troubleshooting.mdx rename to docs/pages/includes/device-trust/enroll-troubleshooting.mdx index 5f7d9dbd25a6f..935b0644fe06b 100644 --- a/docs/pages/includes/device-trust/auto-enroll-troubleshooting.mdx +++ b/docs/pages/includes/device-trust/enroll-troubleshooting.mdx @@ -6,13 +6,9 @@ the problem. ### "unauthorized device" errors using a trusted device -A signed and notarized `tsh` binary is necessary to use a trusted device. Make -sure to download and use the -[macOS tsh installer](../../installation.mdx#macos). - A trusted device needs to be registered and enrolled before it is recognized by Teleport as such. Follow the [registration]( -../../access-controls/device-trust/guide.mdx#step-12-register-a-trusted-device) and +../../access-controls/device-trust/device-management.mdx#register-a-trusted-device) and [enrollment]( -../../access-controls/device-trust/guide.mdx#step-22-enroll-a-trusted-device) steps +../../access-controls/device-trust/device-management.mdx#enroll-a-trusted-device) steps and make sure to `tsh logout` and `tsh login` after enrollment is done.