Per-session MFA

Report an issue with this page

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

This is an advanced security feature that protects users against compromises of their on-disk Teleport certificates.

note

In addition to per-session MFA, enable login MFA in your SSO provider and/or for all local Teleport users to improve security.

Prerequisites

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

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• 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.4.8
  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
• Hardware device for multi-factor authentication, such as YubiKey or SoloKey
• A Web browser with WebAuthn support (if using SSH or desktop sessions from the Teleport Web UI).

Per-session MFA with FIPS

Teleport FIPS builds disable local users. To configure WebAuthn in order to use per-session MFA with FIPS builds, provide the following in your teleport.yaml:

teleport:
  auth_service:
    local_auth: false
    second_factor: "webauthn"
    webauthn:
      rp_id: teleport.example.com

Configure per-session MFA

Per-session MFA can be enforced cluster-wide or only for some specific roles.

Cluster-wide

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

Apply your changes by saving and closing the file in your editor.

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:
    ...

Role-specific enforcement only applies when accessing resources matching a role's allow section.

Roles example

Let's walk through an example of setting up per-session MFA checks for roles.

Jerry is an engineer with access to the company infrastructure. The infrastructure is split into development and production environments. Security engineer Olga wants to enforce MFA checks for accessing production servers. Development servers don't require this to reduce engineers' friction.

Olga defines two Teleport roles: access-dev and access-prod:

# access-dev.yaml
kind: role
version: v7
metadata:
  name: access-dev
spec:
  allow:
    node_labels:
      env: dev
    logins:
      - jerry
---
# access-prod.yaml
kind: role
version: v7
metadata:
  name: access-prod
spec:
  options:
    # require per-session MFA for production access
    require_session_mfa: true
  allow:
    node_labels:
      env: prod
    logins:
      - jerry
  deny: {}

Olga then assigns both roles to all engineers, including Jerry.

When Jerry logs into node dev1.example.com (with label env: dev as login jerry), nothing special happens:

tsh ssh jerry@dev1.example.com

jerry@dev1.example.com >

But when Jerry logs into node rod3.example.com (with label env: prod as login jerry), he gets prompted for an MFA check:

tsh ssh jerry@prod3.example.com
Tap any security key <tap>

jerry@prod3.example.com >

OTP

If you are using tsh in a constrained environment, you can tell it to use OTP by doing tsh --mfa-mode=otp ssh prod3.example.com.

OTP can only be used with per-session MFA when using tsh or Teleport Connect to establish connections. A hardware MFA key is required for using per-session MFA with Teleport's Web UI.

If per-session MFA was enabled cluster-wide, Jerry would be prompted for MFA even when logging into dev1.example.com.

Per-session MFA for Database Access

The Teleport Database Service supports per-connection MFA. When Jerry connects to the database prod-mysql-instance (with label env: prod), he gets prompted for an MFA check for each tsh db connect or tsh proxy db call:

tsh db connect prod-mysql-instance
Tap any security key

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 10002
Server version: 8.0.0-Teleport (Ubuntu)
Copyright (c) 2000, 2021, Oracle and/or its affiliates.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>

Limitations

Current limitations for this feature are:

• For SSH connections besides the Web UI, the tsh or Teleport Connect client must be used for per-session MFA. (The OpenSSH ssh client does not work with per-session MFA).
• Only kubectl supports per-session WebAuthn authentication for Kubernetes.
• For desktop access, only WebAuthn devices are supported.
• When accessing a multi-port TCP application through VNet, the first connection over each port triggers an MFA check.

Next steps

• Require MFA for administrative actions