Teleport
Harden your Cluster Against IdP Compromises
- Edge version
- Version 17.x
- Version 16.x
- Version 15.x
- Older Versions
How to enable WebAuthn based second-factor authentication in Teleport.
Length: 06:42
This guide aims to help you fortify your identity infrastructure and mitigate the risks associated with IdP weaknesses.
An IdP compromise occurs when an attacker gains unauthorized access to your identity management system, potentially allowing them to impersonate legitimate users, escalate privileges, or access sensitive information. This can happen through various means, such as exploiting software vulnerabilities, stealing credentials, or social engineering attacks.
While many organizations have implemented basic security measures like single sign-on (SSO) and multi-factor authentication (MFA), these alone may not be sufficient to protect against sophisticated attacks targeting your IdP. Attackers are constantly evolving their techniques, and traditional security measures may have limitations or vulnerabilities that can be exploited.
To enhance your defense against IdP compromises, we recommend implementing the following comprehensive security measures.
Set up cluster-wide WebAuthn
Implement strong, phishing-resistant authentication across your entire infrastructure using WebAuthn standards. WebAuthn, a W3C standard and part of FIDO2, enables public-key cryptography for web authentication. Teleport supports WebAuthn as a multi-factor for logging into Teleport (via tsh login or Web UI) and accessing SSH nodes or Kubernetes clusters. It's compatible with hardware keys (e.g., YubiKeys, SoloKeys) and biometric authenticators like Touch ID and Windows Hello.
Prerequisites
-
A running Teleport cluster or Teleport Cloud, version 16 or later. If you want to get started with Teleport, sign up for a free trial.
-
The
tctl
admin tool andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
. -
WebAuthn hardware device, such as YubiKey or SoloKey
-
A Web browser with WebAuthn support
-
To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials.For example:
tsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.4.10
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
If you can connect to the cluster and run the
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/3. Enable WebAuthn support
WebAuthn is disabled by default. To enable WebAuthn support, update your Teleport configuration as below:
Edit the cluster_auth_preference
resource:
tctl edit cap
Update the cluster_auth_preference
definition to include the following content:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
# To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
second_factor: "on"
webauthn:
# Required, replace with proxy web address (example.com, example.teleport.sh).
# rp_id is the public domain of the Teleport Proxy Service, *excluding* protocol
# (https://) and port number.
rp_id: example.com
# Optional, attestation_allowed_cas is an optional allow list
# of certificate authorities.
attestation_allowed_cas:
# Entries can be paths to certificate files:
- "/path/to/allowed_ca.pem"
# Entries can also be inline certificates:
- |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
# Optional, attestation_denied_cas is an optional deny list
# of certificate authorities.
attestation_denied_cas:
# Entries can be paths to certificate files:
- "/path/to/denied_ca.pem"
# Entries can also be inline certificates:
- |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
Save and exit the file. tctl
will update the remote definition:
cluster auth preference has been updated
webauthn
fields definitions
rp_id
is the public domain of the Teleport Proxy Service, excluding protocol
(https://
) and port number.
attestation_allowed_cas
is an optional allow list of certificate authorities
(as local file paths or inline PEM certificate strings) for
device verification.
This field allows you to restrict which device models and vendors you trust.
Devices outside of the list will be rejected during registration. By default all
devices are allowed. If you must use attestation, consider using
attestation_denied_cas
to forbid troublesome devices instead.
attestation_denied_cas
is an optional deny list of certificate authorities (as
local file paths or inline PEM certificate strings) for device verification.
This field allows you to forbid specific device models and vendors, while
allowing all others (provided they clear attestation_allowed_cas
as well).
Devices within this list will be rejected during registration. By default no
devices are forbidden.
Step 2/3. Register WebAuthn devices as a user
A user can register multiple WebAuthn devices using tsh
:
tsh mfa addChoose device type [TOTP, WEBAUTHN]: webauthn
Enter device name: desktop yubikey
Tap any *registered* security key or enter a code from a *registered* OTP device:
Tap your *new* security key
MFA device "desktop yubikey" added.
Step 3/3. Log in using WebAuthn
Once a WebAuthn device is registered, the user will be prompted for it on login:
tsh login --proxy=example.teleport.shEnter password for Teleport user codingllama:
Tap any security key or enter a code from a OTP device:
> Profile URL: https://example.teleport.sh
Logged in as: codingllama
Cluster: example.teleport.sh
Roles: access, editor, reviewer
Logins: codingllama
Kubernetes: enabled
Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
WebAuthn for logging in to Teleport is only required for local users. SSO users should configure multi-factor authentication in their SSO provider.
Configure per-session MFA
Ensure that multi-factor authentication is required for each session, not just at initial login, to maintain continuous security. Teleport's per-session MFA enhances security by protecting against compromised on-disk certificates. It requires additional MFA checks when initiating new SSH, Kubernetes, database, or desktop sessions.
Teleport supports requiring additional multi-factor authentication checks when starting new:
- SSH connections (a single
tsh ssh
call, Web UI SSH session or Teleport Connect SSH session) - Kubernetes sessions (a single
kubectl
call) - Database sessions (a single
tsh db connect
call) - Application sessions
- Desktop sessions
In addition to per-session MFA, enable login MFA in your SSO provider and/or for all local Teleport users to improve security.
To enforce MFA checks for all roles, edit your cluster authentication configuration:
Edit your cluster_auth_preference
resource:
tctl edit cap
Ensure that the resource contains the following content:
kind: cluster_auth_preference
metadata:
name: cluster-auth-preference
spec:
require_session_mfa: true
version: v2
Save and close the file in your editor to apply your changes.
Per role
To enforce MFA checks for a specific role, update the role to contain:
kind: role
version: v7
metadata:
name: example-role-with-mfa
spec:
options:
# require per-session MFA for this role
require_session_mfa: true
allow:
...
deny:
...
Implement cluster-wide Device Trust
Develop a system to verify and manage trusted devices across your organization, reducing the risk of unauthorized access from unknown or compromised devices. Device Trust adds an extra layer of security by requiring the use of trusted devices for accessing protected resources, complementing user identity and role enforcement. This can be configured cluster-wide or via RBAC. Supported resources include apps (role-based only), SSH nodes, databases, Kubernetes clusters, and first MFA device enrollment. The latter helps prevent auto-provisioning of new users through compromised IdPs.
We do not currently support Machine ID and Device Trust. Requiring Device Trust cluster-wide or for roles impersonated by Machine ID will prevent credentials produced by Machine ID from being used to connect to resources.
As a work-around, configure Device Trust enforcement on a role-by-role basis and ensure that it is not required for roles that you will impersonate using Machine ID.
Prerequisites
- To enroll a macOS device, you need:
- A signed and notarized
tsh
binary. Download the macOS tsh installer.
- A signed and notarized
- To enroll a Windows device, you need:
- A device with TPM 2.0.
- A user with administrator privileges. This is only required during enrollment.
tsh
v13.1.2 or newer. Download the Windows tsh installer.
- To enroll a Linux device, you need:
- A device with TPM 2.0.
- A user with permissions to use the /dev/tpmrm0 device (typically done by
assigning the
tss
group to the user). tsh
v15.0.0 or newer. Install tsh for Linux.
- To authenticate a Web UI session you need Teleport Connect
- Correct end-user IP propagation to your Teleport deployment: X-Forwarded-For header (L7 load balancer) or PROXY protocol (L4 load balancer)
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:
tsh device enroll --current-device
Step 1/3. Register a trusted device
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):
tsh device asset-tagC00AA0AAAA0A
The serial number is visible under Apple menu -> "About This Mac" -> "Serial number".
Windows and Linux 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:
tsh device asset-tagC00AA0AAAA0A
Replace C00AA0AAAA0A with the serial number of the device you wish to enroll and run
the tctl devices add
command:
tctl devices add --os='macos' --asset-tag='C00AA0AAAA0A'Device C00AA0AAAA0A/macos added to the inventory
Use tctl
to check that the device has been registered:
tctl devices lsAsset Tag OS Enroll Status Device ID------------ ----- ------------- ------------------------------------C00AA0AAAA0A macOS not enrolled 9cdfc0ad-64b7-4d9c-this-is-an-example
Step 2/3. 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:
tctl devices enroll --asset-tag="C00AA0AAAA0A"Run the command below on device "C00AA0AAAA0A" to enroll it:tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example
Step 3/3. Enroll a trusted device
To perform the enrollment ceremony, using the device specified above, type the
command printed by tctl devices enroll
:
tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-exampleDevice "C00AA0AAAA0A"/macOS enrolledtsh logouttsh login --proxy=teleport.example.com --user=myuser # fetch new certificatesEnter password for Teleport user myuser:Tap any security keyDetected security key tap> Profile URL: teleport.example.com:443 Logged in as: myuser Cluster: teleport.example.com Roles: access, editor Logins: myuser 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 or performed using an integration, like the Jamf Pro integration.
- Auto-enrollment must be enabled in the cluster setting.
- User must have either preset
editor
ordevice-enroll
(available v13.3.6+) role assigned to them.
Since Teleport v16.1.1 users don't need the device/enroll permission to benefit from auto-enrollment.
Step 1/2. Enable auto-enrollment in your cluster settings
Modify the dynamic config resource using tctl edit cluster_auth_preference
:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
# ...
device_trust:
mode: "required"
+ auto_enroll: true
Step 2/2. Log out and back in
Once enabled, users with their device registered in Teleport will have their device enrolled to Teleport in their next login.
tsh logoutAll users logged out.tsh login --proxy=teleport.example.com --user=myuserEnter password for Teleport user myuser:Tap any security keyDetected security key tap> Profile URL: teleport.example.com:443 Logged in as: myuser Cluster: teleport.example.com Roles: access, editor Logins: myuser 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.
Require MFA for administrative actions
Add an extra layer of security for sensitive administrative operations by requiring multi-factor authentication for these high-privilege actions. Teleport enforces additional MFA verification for administrative actions across all clients (tctl, tsh, Web UI, and Connect). This feature adds an extra security layer by re-verifying user identity immediately before any admin action, mitigating risks from compromised admin accounts.
By adopting these advanced security measures, you can create a robust defense against IdP compromises and significantly reduce your organization's attack surface. In the following sections, we'll dive deeper into each of these recommendations, providing step-by-step guidance on implementation and best practices.
When MFA for administrative actions is enabled, user certificates produced
with tctl auth sign
will no longer be suitable for automation due to the
additional MFA checks.
We recommend using Machine ID to issue certificates for automated workflows, which uses role impersonation that is not subject to MFA checks.
Certificates produced with tctl auth sign
directly on an Auth Service instance using the super-admin
role are not subject to MFA checks to support legacy self-hosted setups.
Prerequisites
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.4.10
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions. - WebAuthn configured on this cluster
- Multi-factor hardware device, such as YubiKey or SoloKey
- A Web browser with WebAuthn support (if using SSH or desktop sessions from the Teleport Web UI).
MFA for administrative actions is automatically enforced for clusters where WebAuthn is the only form of multi-factor allowed.
In a future major version, Teleport may enforce MFA for administrative actions for a wider range of cluster configurations.
Examples of administrative actions include, but are not limited to:
- Resetting or recovering user accounts
- Inviting new users
- Updating cluster configuration resources
- Modifying access management resources
- Approving Access Requests
- Generating new join tokens
- Impersonation
- Creating new bots for Machine ID
This is an advanced security feature that protects users against compromises of their on-disk Teleport certificates.
Step 1/2. Edit the resource
Edit the cluster_auth_preference
resource:
tctl edit cap
Update the cluster_auth_preference
definition to include the following content:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
# To make webauthn the only form of multi-factor allowed, set this field to 'webauthn'.
second_factor: "webauthn"
webauthn:
rp_id: example.com
Step 2/2. Save and exit the file
The command tctl
will update the remote definition:
cluster auth preference has been updated
Next steps
For additional cluster hardening measures, see:
- Passwordless Authentication: Provides passwordless and usernameless authentication.
- Locking: Lock access to active user sessions or hosts.
- Moderated Sessions: Require session auditors and allow fine-grained live session access.
- Hardware Key Support: Enforce the use of hardware-based private keys.