# Harden your Cluster Against IdP Compromises 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. ![IdP threat vector tree](/docs/assets/images/idp-graph-1879ca6d00a5550eeaa1491135988fe5.png) 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. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial. - The `tctl` admin tool and `tsh` client tool. Visit [Installation](https://goteleport.com/docs/installation.md) for instructions on downloading `tctl` and `tsh`. - WebAuthn hardware device, such as YubiKey or SoloKey - A Web browser with [WebAuthn support](https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) - To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.7.3 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 subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. ### Step 1/3. Enable WebAuthn support 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, include "webauthn" as a second factor method. second_factors: ["webauthn"] 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](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html). 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](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html). 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 add Choose 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.sh Enter 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 ``` --- NOTE WebAuthn for logging in to Teleport is only required for [local users](https://goteleport.com/docs/reference/access-controls/authentication.md#local-no-authentication-connector). 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 --- NOTE In addition to per-session MFA, enable login MFA in your SSO provider and/or for all [local Teleport users](https://goteleport.com/docs/reference/access-controls/authentication.md) 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. --- MACHINE & WORKLOAD IDENTITY AND DEVICE TRUST We do not currently support Machine & Workload Identity and Device Trust. Requiring Device Trust cluster-wide or for roles impersonated by Machine & Workload Identity will prevent credentials produced by Machine & Workload Identity 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 & Workload Identity --- ### Prerequisites - To enroll a macOS device, you need: - A signed and notarized `tsh` binary. [Download the macOS tsh installer](https://goteleport.com/docs/installation/macos.md). - To enroll a Windows device, you need: - A device with TPM 2.0. - A user with administrator privileges. This is only required during enrollment. - The `tsh` client. [Download the Windows tsh installer](https://goteleport.com/docs/installation/windows.md). - 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). - The `tsh` client. [Install tsh for Linux](https://goteleport.com/docs/installation/linux.md). WSL users should use the Windows binary instead. [Download the Windows tsh installer](https://goteleport.com/docs/installation/windows.md). - To authenticate a Web UI session you need [Teleport Connect](https://goteleport.com/docs/connect-your-client/teleport-clients/teleport-connect.md#installation--upgrade) - Correct end-user IP propagation to your Teleport deployment: [X-Forwarded-For header](https://goteleport.com/docs/reference/deployment/config.md#proxy-service) (L7 load balancer) or [PROXY protocol](https://goteleport.com/docs/zero-trust-access/management/security/proxy-protocol.md) (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. --- SELF ENROLLMENT Users with the preset `editor` or `device-admin` role 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-tag C00AA0AAAA0A ``` Manually retrieving device serial **macOS** The serial number is visible under Apple menu -> "About This Mac" -> "Serial number". **Windows and Linux** 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-tag C00AA0AAAA0A ``` Replace C00AA0AAAA0A with the serial number of the device you wish to enroll, and macos with your operating system. 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 ls Asset Tag OS Source Enroll Status Owner 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-example Device "C00AA0AAAA0A"/macOS enrolled $ tsh logout $ tsh login --proxy=teleport.example.com --user=myuser # fetch new certificates Enter password for Teleport user myuser: Tap any security key Detected 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](#implement-cluster-wide-device-trust) or performed using [an MDM integration](https://goteleport.com/docs/zero-trust-access/device-trust.md#mdm-integrations). - Auto-enrollment must be enabled in the cluster setting. ### 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 logout All users logged out. $ tsh login --proxy=teleport.example.com --user=myuser Enter password for Teleport user myuser: Tap any security key Detected 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. --- WARNING 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 run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.7.3 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 subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. - [WebAuthn configured](#set-up-cluster-wide-webauthn) on this cluster - Multi-factor hardware device, such as YubiKey or SoloKey - A Web browser with [WebAuthn support](https://developers.yubico.com/WebAuthn/WebAuthn_Browser_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. --- NOTE 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 & Workload Identity 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 second_factors: ["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](https://goteleport.com/docs/zero-trust-access/authentication/passwordless.md): Provides passwordless and usernameless authentication. - [Locking](https://goteleport.com/docs/identity-governance/locking.md): Lock access to active user sessions or hosts. - [Moderated Sessions](https://goteleport.com/docs/zero-trust-access/authentication/joining-sessions.md): Require session auditors and allow fine-grained live session access. - [Hardware Key Support](https://goteleport.com/docs/zero-trust-access/authentication/hardware-key-support.md): Enforce the use of hardware-based private keys. - [Configuring SSO for MFA checks](https://goteleport.com/docs/zero-trust-access/sso/sso-for-mfa.md): Delegate per-session MFA to your IdP.