Multi-Factor Authentication and Passwordless Login

Teleport supports multiple forms of multi-factor authentication (MFA) to protect both the login flow and individual infrastructure sessions. You can require a hardware security key tap before every SSH connection, allow biometric passwordless login via Touch ID or Windows Hello, or delegate MFA enforcement to your SSO provider.

MFA methods

Teleport supports the following second-factor types:

TOTP
WebAuthn
Passwordless

Time-based One-Time Passwords (TOTP) are six-digit codes generated by an authenticator app such as Google Authenticator, Authy, or 1Password. TOTP implements the RFC 6238 standard and is the default for self-hosted Teleport deployments.To enroll a TOTP device:

$ tsh mfa add
# Choose device type [TOTP, WEBAUTHN, TOUCHID]: TOTP
# Enter device name: google-auth
# Open your authenticator app and scan the QR code
# Enter the 6-digit code: 123456
# MFA device "google-auth" added.

WebAuthn implements the Web Authentication standard and supports hardware security keys (YubiKey, SoloKey, or any FIDO2/U2F device) as well as platform authenticators (Touch ID on macOS, Windows Hello). WebAuthn is the default for Teleport Enterprise Cloud accounts.To enroll a WebAuthn device:

$ tsh mfa add
# Choose device type [TOTP, WEBAUTHN, TOUCHID]: WEBAUTHN
# Enter device name: yubikey
# Tap any *registered* security key (if you already have one)
# Tap your *new* security key
# MFA device "yubikey" added.

Passwordless login uses WebAuthn resident keys (also called discoverable credentials) stored on your hardware device or platform authenticator. Users authenticate with only a biometric gesture or hardware key tap — no username or password required.To register a passwordless credential:

$ tsh mfa add
# Choose device type [TOTP, WEBAUTHN, TOUCHID]: WEBAUTHN
# Enter device name: bio
# Allow passwordless logins [YES, NO]: YES
# Tap any *registered* security key
# Tap your *new* security key
# MFA device "bio" added.

To authenticate passwordlessly:

$ tsh login --proxy=example.teleport.sh --auth=passwordless
# Tap your security key
# > Logged in as: alice

If you plan to rely exclusively on passwordless login, register at least two devices — ideally a portable hardware key alongside a platform authenticator — so you always have a backup.

Cluster-wide MFA configuration

Configure MFA options in your teleport.yaml under auth_service, or via the dynamic cluster_auth_preference resource.

Static configuration (`teleport.yaml`)

auth_service:
  authentication:
    type: local
    # second_factors accepts: "otp", "webauthn", "sso"
    # Use "on" to require at least one MFA device (TOTP or WebAuthn)
    # Use "optional" to allow MFA but not require it
    second_factors: ["webauthn"]
    webauthn:
      rp_id: example.teleport.sh

Value	Behavior
`otp`	TOTP only; default for self-hosted deployments
`webauthn`	WebAuthn hardware keys and biometrics only; default for Enterprise Cloud
`on`	Both TOTP and WebAuthn required; users must register at least one device
`optional`	Both TOTP and WebAuthn enabled but not required
`off`	MFA disabled (not recommended for production)

Dynamic resource (`cluster_auth_preference`)

$ tctl edit cap

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factors: ["webauthn"]
  webauthn:
    rp_id: example.teleport.sh

Per-session MFA

Per-session MFA requires users to authenticate with a second factor at the start of each individual session — not just at login. This protects against scenarios where an attacker steals on-disk Teleport certificates: even with the certificate, they cannot open a new session without physical access to the MFA device. Per-session MFA is supported for:

SSH connections (tsh ssh, Web UI, Teleport Connect)
Kubernetes sessions (kubectl, tsh proxy kube)
Database sessions (tsh db connect, tsh proxy db)
Application sessions
Desktop sessions

Enable cluster-wide per-session MFA

$ tctl edit cap

spec:
  require_session_mfa: true

Enable per-session MFA for a specific role

Apply per-session MFA only to users accessing production resources:

kind: role
version: v7
metadata:
  name: access-prod
spec:
  options:
    require_session_mfa: true
  allow:
    node_labels:
      env: prod
    logins:
      - '{{internal.logins}}'
  deny: {}

With this configuration, accessing a development server proceeds without an MFA prompt, but accessing a production server requires a security key tap or TOTP code for each session.

Passwordless cluster configuration

To configure a fully passwordless cluster, enable passwordless as the default authentication method:

$ tctl edit cap

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factors: ["webauthn"]
  webauthn:
    rp_id: example.teleport.sh
  allow_passwordless: true

Passwordless login requires WebAuthn to be configured on the cluster. It works with any device that supports resident keys: YubiKey 5 series, Touch ID on macOS, or Windows Hello on Windows 10 (19H1 or later).

SSO MFA

If your users authenticate via an SSO provider, you can delegate MFA challenges to that provider. When a user initiates a session that requires per-session MFA, Teleport redirects the challenge to the IdP instead of prompting for a local device. Configure SSO MFA by including sso in second_factors:

spec:
  second_factors: ["webauthn", "sso"]

For SSO users, Teleport does not prompt for MFA at login — that responsibility belongs to the IdP. The sso second factor only applies to per-session MFA challenges.

Managing MFA devices

# List registered MFA devices
$ tsh mfa ls

# Add a new device
$ tsh mfa add

# Remove a device
$ tsh mfa rm yubikey

Administrators can manage MFA devices for other users via the Teleport Web UI under Account Settings → Multi-factor Devices, or by locking a specific MFA device:

# Lock a specific MFA device by its UUID (disables the device cluster-wide)
$ tctl lock --mfa-device=<device-uuid> --message="Device locked by admin" --ttl=24h

Next steps

RBAC

Enforce per-session MFA at the role level with require_session_mfa.

SSO

Integrate with your IdP and delegate login MFA to the provider.

Device Trust

Go beyond MFA by requiring registered, attested devices.

Access Requests

Combine MFA with just-in-time elevated access.

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Multi-Factor Authentication and Passwordless Login

MFA methods

Cluster-wide MFA configuration

Static configuration (`teleport.yaml`)

Dynamic resource (`cluster_auth_preference`)

Per-session MFA

Enable cluster-wide per-session MFA

Enable per-session MFA for a specific role

Passwordless cluster configuration

SSO MFA

Managing MFA devices

Next steps

RBAC

SSO

Device Trust

Access Requests

Build docs developers (and LLMs) love

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Documentation Index

​MFA methods

​Cluster-wide MFA configuration

​Static configuration (teleport.yaml)

​Dynamic resource (cluster_auth_preference)

​Per-session MFA

​Enable cluster-wide per-session MFA

​Enable per-session MFA for a specific role

​Passwordless cluster configuration

​SSO MFA

​Managing MFA devices

​Next steps

RBAC

SSO

Device Trust

Access Requests

Build docs developers (and LLMs) love

MFA methods

Cluster-wide MFA configuration

Static configuration (`teleport.yaml`)

Dynamic resource (`cluster_auth_preference`)

Per-session MFA

Enable cluster-wide per-session MFA

Enable per-session MFA for a specific role

Passwordless cluster configuration

SSO MFA

Managing MFA devices

Next steps