Per-session MFA

Teleport supports U2F authentication on every SSH and Kubernetes "connection" (a single tsh ssh or kubectl call). This is an advanced security feature that protects users against compromises of their on-disk Teleport certificates.

Prerequisites

• Installed Teleport or Teleport Cloud >= 7.1.3
• U2F configured on this cluster
• U2F hardware device, such as Yubikey or Solokey
• Web browser that supports U2F (if using SSH from the Teleport Web UI)

Configuration

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

Cluster-wide

To enforce U2F checks cluster-wide, update teleport.yaml on the Auth server to contain:

auth_service:
  authentication:
    # require per-session MFA cluster-wide
    require_session_mfa: yes

Per role

To enforce U2F checks for a specific role, update the role to contain:

kind: role
version: v3
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 SSH nodes or Kubernetes clusters matching that role's allow section.

Roles example

Let's walk though 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: v4
metadata:
  name: access-dev
spec:
  allow:
    node_labels:
      env: dev
    kubernetes_labels:
      env: dev
  deny: {}
---
# access-prod.yaml
kind: role
version: v4
metadata:
  name: access-prod
spec:
  options:
    # require per-session MFA for production access
    require_session_mfa: true
  allow:
    node_labels:
      env: prod
    kubernetes_labels:
      env: prod
  deny: {}

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

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

tsh ssh dev1.example.com
[email protected] >

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

tsh ssh prod3.example.com
Tap any security key <tap>
[email protected] >

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

Limitations

Current limitations for this feature are:

• U2F devices aren't currently supported in tsh on Windows.
• Only tsh ssh supports per-session U2F authentication for SSH (OpenSSH ssh does not).
• Only kubectl supports per-session U2F authentication for Kubernetes.
• Database and Application access clients don't support per-session U2F authentication yet, although cluster and role configuration applies to them. If you enable per-session U2F checks cluster-wide, you will not be able to use Database or Application access. We're working on integrating per-session U2F checks for these clients.