Teleport - Multi-Factor SSH and Kubectl Authentication
Length: 01:29
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 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
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 11.3.2.tctl versionTeleport v11.3.2 go1.19
tsh versionTeleport v11.3.2 go1.19
See Installation for details.
-
A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 11.3.2, which you can download by visiting the customer portal.tctl versionTeleport v11.3.2 go1.19
tsh versionTeleport v11.3.2 go1.19
-
A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
-
The
tctl
admin tool andtsh
client tool version >= 11.2.1. To download these tools, visit the Downloads page.tctl versionTeleport v11.2.1 go1.19
tsh versionTeleport v11.2.1 go1.19
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 11.3.2
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent tctl
commands in this guide on your local machine.
For full privileges, you can also run tctl
commands on your Auth Service host.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 11.2.1
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
- WebAuthn configured on this cluster
- Second factor hardware device, such as YubiKey or SoloKey
- A Web browser with WebAuthn support (if using SSH from the Teleport Web UI).
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
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
Per role
To enforce MFA 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 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: v5
metadata:
name: access-dev
spec:
allow:
node_labels:
env: dev
kubernetes_labels:
env: dev
db_labels:
'env': dev
db_users:
- '*'
db_names:
- '*'
deny: {}
---
# access-prod.yaml
kind: role
version: v5
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
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
But when Jerry logs into node prod3.example.com
(with label env: prod
), he
gets prompted for an MFA check:
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-instanceTap 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 OpenSSHssh
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.