Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

Teleport Device Trust ensures that only known, registered devices can access your infrastructure — not just authenticated users. Even if an attacker obtains a user’s credentials or certificates, they cannot open a session to a protected resource without the private key that lives inside the device’s Secure Enclave (macOS) or Trusted Platform Module (TPM) on Windows and Linux. Device Trust adds a third dimension to Teleport’s security model: who the user is (identity), what they can access (RBAC), and now which device they are using.

​
How Device Trust works

Trusted device enforcement requires two things to be configured:
  1. Device registration: The device is added to Teleport’s inventory (manually via tctl or automatically via an MDM integration).
  2. Device enrollment: The device completes a cryptographic ceremony that creates a private key in the device’s secure hardware and registers its public key with the Teleport Auth Service.
At session time, Teleport issues a device challenge that only the enrolled device can sign. The Auth Service verifies the signature and, if the user’s role requires a trusted device, denies the session if the challenge fails.

​
TPM-based attestation (Windows and Linux)

On Windows and Linux, Teleport uses the Trusted Platform Module (TPM) to perform an attestation — a signed statement about the device’s hardware state. The attestation is signed by a key that never leaves the TPM, so Teleport can verify both that the request came from a specific physical device and that the device is in a known-good state.

​
Secure Enclave attestation (macOS)

On macOS, Teleport stores a device private key in the Secure Enclave and uses it to sign device challenges. The Secure Enclave prevents the key from being exported, ensuring that only that specific Mac can satisfy the challenge.

​
Device Trust enforcement modes

Device Trust operates in four modes, controlled by the device_trust_mode setting:
ModeBehavior
offDevice authentication is disabled. No device data appears in audit logs.
optionalDevices are authenticated and device data appears in audit logs, but unregistered devices are still permitted.
requiredAll SSH, database, and Kubernetes sessions require a trusted device. Unregistered devices are rejected.
required-for-humansSame as required, but bot/machine users are exempt.

​
Role-based device enforcement

Apply device trust to specific roles using the device_trust_mode option. This is the recommended approach when you want to enforce trusted devices only for access to sensitive environments. 
kind: role
version: v7
metadata:
  name: require-trusted-device
spec:
  options:
    device_trust_mode: "required"
  allow:
    # SSH servers
    node_labels:
      '*': '*'
    logins:
      - '{{internal.logins}}'

    # Kubernetes clusters
    kubernetes_labels:
      '*': '*'
    kubernetes_groups:
      - '{{internal.kubernetes_groups}}'
      - developers

    # Databases
    db_labels:
      '*': '*'
    db_names:
      - '*'
    db_users:
      - '*'
Apply the role and assign it to users who must use trusted devices: 
$ tctl create -f require-trusted-device.yaml
$ tctl users update alice --set-roles=access,require-trusted-device

​
Cluster-wide device enforcement

To require trusted devices for all users across all resources in the cluster, update the cluster_auth_preference: 
$ tctl edit cluster_auth_preference

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factors: ["webauthn"]
  webauthn:
    rp_id: example.teleport.sh
  device_trust:
    mode: "required"
After saving, any SSH, Kubernetes, or database access attempt from an unenrolled device will be rejected: 
$ tsh ssh user@prod-server
ERROR: ssh: rejected: administratively prohibited (unauthorized device)
Setting cluster-wide mode to required will block all sessions from unenrolled devices immediately. Ensure all expected user devices are registered and enrolled before enabling this setting cluster-wide.

​
Device registration

Device registration adds a device to Teleport’s inventory. It is an administrative step, equivalent to IT running an asset register.

​
Manual registration

# Register a macOS device by serial number
$ tctl devices add --os=macos --asset-tag=C02XJ0ABHX87

# Register a Windows device
$ tctl devices add --os=windows --asset-tag=WIN-ABC12345

# List registered devices
$ tctl devices ls
To find a device’s serial number (asset tag) from the device itself: 
$ tsh device asset-tag
C02XJ0ABHX87

​
Auto-enrollment

When auto-enrollment is enabled, a device that is already registered automatically completes enrollment on the user’s next tsh login — no enrollment token needed. Enable auto-enrollment in the cluster settings: 
$ tctl edit cluster_auth_preference

spec:
  device_trust:
    mode: "optional"
    auto_enroll: true

​
Device enrollment

Enrollment creates the secure hardware key on the device and registers its public key with Teleport. Enrollment must be performed on the physical device being enrolled.

​
Manual enrollment flow

1

Generate an enrollment token

A device administrator creates a time-limited enrollment token for the device:
$ tctl devices enroll --asset-tag=C02XJ0ABHX87
Run the command below on device "C02XJ0ABHX87" to enroll it:
tsh device enroll --token=abc123...xyz
2

Send the token to the user

Deliver the token to the user via a secure channel (corporate chat, email, or in person).
3

User runs tsh device enroll

On the device to be enrolled, the user runs:
$ tsh device enroll --token=abc123...xyz
Device "C02XJ0ABHX87"/macOS enrolled
4

User re-logs in to get device-aware certificates

After enrollment, the user logs in again so Teleport issues certificates that include device extensions:
$ tsh logout
$ tsh login --proxy=example.teleport.sh --user=alice
# Extensions: teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id
The presence of teleport-device-* extensions confirms the device is trusted.

​
Self-enrollment for editors and device admins

Users with the preset editor or device-admin role can register and enroll their own current device in a single step: 
$ tsh device enroll --current-device
Device "C02XJ0ABHX87"/macOS enrolled

​
MDM integrations

For organizations managing fleets of devices, Teleport integrates with leading Mobile Device Management (MDM) solutions to automatically sync device inventories.
Teleport’s Jamf Pro integration periodically reads your Jamf device inventory and syncs it to Teleport. It supports macOS computers and optionally iOS/iPadOS mobile devices.The Teleport Jamf service performs both incremental (partial) and full syncs, and removes devices from the Teleport inventory when they are retired from Jamf.How it works: The Jamf service is a dedicated teleport process (or a hosted plugin in Teleport Enterprise Cloud). It authenticates to Jamf using API credentials with the Read Computers privilege and calls tctl devices add on your behalf for each discovered device.Setup overview:
  1. Create a Jamf API role with Read Computers privilege and generate a client ID and secret.
  2. Configure the Teleport Jamf service with your Jamf API endpoint, client ID, and client secret.
  3. Start the service and verify the device inventory is synced with tctl devices ls.
MDM integrations handle device registration (inventory management) only. Users must still complete device enrollment to establish the secure hardware key — unless auto-enrollment is enabled.

​
Verifying device trust in audit logs

Once device trust is active, session audit events include device metadata: 
{
  "event": "session.start",
  "user": "alice",
  "device": {
    "asset_tag": "C02XJ0ABHX87",
    "device_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "os": "macOS",
    "credential_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
  }
}
This ensures a complete audit trail that identifies not just who accessed a resource, but from which physical device.

​
Next steps

RBAC

Combine device enforcement with label-based role policies.

MFA

Layer per-session MFA on top of device trust for defence-in-depth.

Access Requests

Require both a trusted device and an approved request for the most sensitive resources.

SSO

Integrate IdP identity with device-aware access policies.

Build docs developers (and LLMs) love

Get started for freeTalk to us