Skip to content

Latest commit

 

History

History
309 lines (242 loc) · 7.31 KB

per-session-mfa.mdx

File metadata and controls

309 lines (242 loc) · 7.31 KB
Raw
title description videoBanner
Per-session MFA
Require MFA checks to initiate sessions.
j8Ze7HhjFGw

Teleport supports requiring additional multi-factor authentication checks when starting new:

  • SSH connections (a single tsh call)
  • Kubernetes sessions (a single kubectl call)
  • Database sessions (a single tsh db connect call)
  • Desktop sessions

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

In addition to per-session MFA, enable login MFA in your SSO provider and/or for all [local Teleport users](../../reference/authentication.mdx#local-no-authentication-connector) to improve security.
Per-session MFA checks were introduced in Teleport v6.1. To enforce the checks, you must update **all** `teleport` binaries in your deployment. If only Auth and Proxy services are updated, these checks will *not* be properly enforced. Additionally, only v6.1 or newer `tsh` binaries implement per-session MFA checks.

Per-session MFA for Desktop Access was introduced in Teleport 9.

Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

(!docs/pages/includes/tctl.mdx!)

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

<ScopedBlock scope={["oss", "enterprise"]}>

To enforce MFA checks for all roles, edit your cluster authentication configuration:

Update teleport.yaml on the Auth Server to include the following content:

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

Obtain your existing cluster_auth_preference resource:

$ tctl get cap > cap.yaml

If you have not defined a cluster_auth_preference, cap.yaml will be blank.

Ensure that cap.yaml contains the following content:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  require_session_mfa: true
version: v2

Create the resource:

$ tctl create -f cap.yaml

Obtain your existing cluster_auth_preference resource:

$ tctl get cap > cap.yaml

If you have not defined a cluster_auth_preference, cap.yaml will be blank.

Ensure that cap.yaml contains the following content:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  require_session_mfa: true
version: v2

Create the resource:

$ tctl create -f cap.yaml

Per role

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

kind: role
version: v6
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: v6
metadata:
  name: access-dev
spec:
  allow:
    node_labels:
      env: dev
    kubernetes_labels:
      env: dev
    kubernetes_resources:
      - kind: pod
        namespace: "*"
        name: "*"
    db_labels:
      'env': dev
    db_users:
    - '*'
    db_names:
    - '*'
  deny: {}
---
# access-prod.yaml
kind: role
version: v6
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
    kubernetes_resources:
      - kind: pod
        namespace: "*"
        name: "*"
    db_labels:
      'env': prod
    db_users:
    - '*'
    db_names:
    - '*'
  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 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 the tsh client 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.

Database Access 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, the tsh 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.
  • Application access clients don't support per-session MFA authentication yet, although cluster and role configuration applies to them. If you enable per-session MFA checks cluster-wide, you will not be able to use Application access. We're working on integrating per-session MFA checks for these clients.
  • For Desktop Access, only WebAuthn devices are supported.