Skip to main content
Version: 18.x (unreleased)

MFA for Administrative Actions

Report an issue with this page

Teleport can be configured to require additional multi-factor authentication checks to perform administrative actions through tctl, tsh, the Web UI, Teleport Connect, and any other Teleport client.

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.

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​

  • A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Details

    Installing tctl and tsh clients

    Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

    curl -O https://cdn.teleport.dev/teleport-17.0.0-dev.pkg

    In Finder double-click the pkg file to begin installation.

    danger

    Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

    The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/ping and use a JSON query tool to obtain your cluster version:

    curl https://example.teleport.sh/v1/webapi/ping | jq -r '.server_version'
    17.0.0-dev
  • 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  17.0.0-dev
    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 on this cluster
  • Multi-factor authentication hardware device, such as YubiKey or SoloKey
  • A Web browser with WebAuthn support (if using SSH or desktop sessions from the Teleport Web UI).

Require MFA for administrative actions​

MFA for administrative actions is automatically enforced for clusters where WebAuthn is the only form of multi-factor authentication allowed.

note

In a future major version, Teleport may enforce MFA for administrative actions for a wider range of cluster configurations.

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

Save and exit the file. tctl will update the remote definition:

cluster auth preference has been updated