
Teleport
Passwordless
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise

Introducing Teleport 10 Passwordless
Length: 02:12
Passwordless takes advantage of WebAuthn to provide passwordless and usernameless authentication for Teleport.
Prerequisites
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.0.See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
- Teleport must be configured for WebAuthn. See the Second Factor: WebAuthn guide.
- A hardware device with support for WebAuthn and resident keys. As an alternative, you can use a Mac with biometrics / Touch ID or device that supports Windows Hello (Windows 10 19H1 or later).
- A web browser with WebAuthn support. To see if your browser supports WebAuthn, check the WebAuthn Compatibility page.
- A signed and notarized version of
tsh
is required for Touch ID. This precludes versions installed from Homebrew. Download the macOS tsh installer. - To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
A Teleport cluster capable of WebAuthn is automatically capable of passwordless.
Step 1/2. Register
Register your passwordless device using tsh
:
tsh mfa addChoose 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.
You may pick either WEBAUTHN
or TOUCHID
as the device type. Make sure to
answer YES
to "Allow passwordless logins".
If you are using a hardware device, a passwordless registration will occupy a resident key slot. Resident keys, also called discoverable credentials, are stored in persistent memory in the authenticator (i.e., the device that is used to authenticate). In contrast, MFA keys are encrypted by the authenticator and stored in the Teleport Auth Server. Regardless of your device type, passwordless registrations may also be used for regular MFA.
If you plan on relying exclusively on passwordless, it's recommended to register
more than one device. A portable hardware device is ideal, as it can be shared
between tsh
, the Teleport Web UI, and different computers.
Touch ID registrations are isolated by application. A Touch ID registration
for tsh
is different from a registration made from Chrome or Safari. You may
register the same Touch ID device from multiple applications to get
passwordless access in all of them.
Step 2/2. Authenticate
Authenticate using your passwordless credential:
tsh login --proxy=example.com --auth=passwordlessTap your security key
> Profile URL: https://example.com
Logged in as: codingllama
Cluster: example.com
Roles: access, editor
Logins: codingllama
Kubernetes: enabled
Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
tsh login --proxy=example.com --auth=passwordlessTap your security key
> Profile URL: https://example.com
Logged in as: codingllama
Cluster: example.com
Roles: access, editor, reviewer
Logins: codingllama
Kubernetes: enabled
Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
A fully passwordless cluster defaults to passwordless logins, making
--auth=passwordless
unnecessary. See the next section to learn how to enable
passwordless by default.
You can also execute passwordless logins in the Teleport Web UI. To do so, look for the passwordless link in the Web UI.
Optional: Enable passwordless by default
Passwordless enthusiasts may enable passwordless by default in their clusters.
Note that this configuration changes Teleport's behavior even for users without
a passwordless device registered, so existing users may need to authenticate
using tsh login --proxy=example.com --auth=local
in order to get their first
passwordless registration.
To enable passwordless by default, add connector_name: passwordless
to your
cluster configuration:
Auth Server teleport.yaml
file:
auth_service:
authentication:
type: local
second_factor: on
webauthn:
rp_id: example.com
connector_name: passwordless # passwordless by default
Create a cap.yaml
file or get the existing configuration using
tctl get cluster_auth_preference
:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
webauthn:
rp_id: example.com
connector_name: passwordless # passwordless by default
Update the configuration:
tctl create -f cap.yamlcluster auth preference has been updated
Please use the latest version of Teleport Enterprise documentation.
Troubleshooting
"Allow passwordless logins" doesn't appear
If you don't see the "Allow passwordless logins" prompt during tsh mfa add
,
you may be using an older version of tsh
. Download the latest tsh
from our
installation page.
Hardware device not usable
tsh
only prompts for hardware devices with certain capabilities for
passwordless registrations. If your device isn't blinking it may not be capable
of passwordless logins.
Below is a non-comprehensive list of requirements:
- Device must support WebAuthn (sometimes also called FIDO2 or CTAP2).
- Device must be capable of user verification (biometrics or PIN).
- Device must have a PIN set.
- Device must have fingerprints enrolled (if biometric). This typically means both a PIN and fingerprints.
tsh
relies in an embedded libfido2 to access hardware devices. If you are
running on Linux, you may be missing the necessary udev rules to access your
device. Try following the installation instructions for libfido2, which may provide you the
necessary udev rules.
Touch ID not usable
If you are having trouble with Touch ID, make sure that you are using the latest
standalone version of tsh
. Download the macOS tsh installer.
Touch ID support requires Macs with a Touch ID sensor and Secure Enclave. It also requires macOS >= 10.13 (macOS High Sierra).
You can run the tsh touchid diag
command to verify requirements. A capable
device and tsh
binary should show an output similar to the one below:
tsh touchid diagHas compile support? true
Has signature? true
Has entitlements? true
Passed LAPolicy test? true
Passed Secure Enclave test? true
Touch ID enabled? true
Windows Webauthn not usable
Windows Webauthn support for tsh
requires Windows 10 19H1 or later.
You can run the tsh webauthnwin diag
command to verify requirements. A capable
device and tsh
binary should show the following output:
tsh webauthnwin diagWebauthWin available: true
Compile support: true
DLL API version: 4
Has platform UV: true
Register successful: true
Login successful: true
Disable passwordless
If you want to forbid passwordless access to your cluster, add passwordless: false
to your configuration:
Auth Server teleport.yaml
file:
# snippet from /etc/teleport.yaml:
auth_service:
authentication:
type: local
second_factor: on
webauthn:
rp_id: example.com
passwordless: false # disable passwordless
Create a cap.yaml
file or get the existing configuration using
tctl get cluster_auth_preference
:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
webauthn:
rp_id: example.com
passwordless: false # disable passwordless
Update the configuration:
tctl create -f cap.yamlcluster auth preference has been updated
Please use the latest version of Teleport Enterprise documentation.