Teleport supports WebAuthn as a second authentication
factor. WebAuthn can be used for logging in to Teleport (tsh login
or the login
page on the Web UI) and for logging in to individual SSH nodes or Kubernetes
clusters (tsh ssh
and kubectl
).
WebAuthn support includes hardware devices, such as YubiKeys or SoloKeys (tsh
and Web UI), as well as biometric authenticators like Touch ID and Windows Hello
(Web UI only).
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 >= 9.3.7.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport v9.3.7 go1.17
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 >= 9.3.7, which you can download by visiting the customer portal.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport v9.3.7 go1.17
-
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 >= 9.3.8. To download these tools, visit the Downloads page.tctl versionTeleport v9.3.8 go1.17
tsh versionTeleport v9.3.8 go1.17
- WebAuthn hardware device, such as YubiKey or SoloKey
- A Web browser with WebAuthn support
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 9.3.7
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 9.3.8
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
Step 1/3. Enable WebAuthn support
WebAuthn is disabled by default. To enable WebAuthn support, update your Teleport configuration as below:
Auth Server teleport.yaml
file:
# snippet from /etc/teleport.yaml:
auth_service:
authentication:
type: local
# To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
second_factor: on
webauthn:
rp_id: example.com
attestation_allowed_cas:
- "/path/to/allowed_ca.pem"
attestation_denied_cas:
- "/path/to/denied_ca.pem"
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
includes the following content:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
# To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
second_factor: on
webauthn:
rp_id: example.com
attestation_allowed_cas:
- "/path/to/allowed_ca.pem"
attestation_denied_cas:
- "/path/to/denied_ca.pem"
Update the configuration:
tctl create -f cap.yamlcluster auth preference has been updated
You will need to include the following configuration fields.
rp_id
is the public domain of the Teleport Proxy Service, excluding protocol
(https://
) and port number.
attestation_allowed_cas
is an optional allow list of certificate authorities
(as local file paths or inline PEM certificate strings) for
device verification.
This field allows you to restrict which device models and vendors you trust.
Devices outside of the list will be rejected during registration. By default all
devices are allowed. If you must use attestation, consider using
attestation_denied_cas
to forbid troublesome devices instead.
attestation_denied_cas
is an optional deny list of certificate authorities (as
local file paths or inline PEM certificate strings) for device verification.
This field allows you to forbid specific device models and vendors, while
allowing all others (provided they clear attestation_allowed_cas
as well).
Devices within this list will be rejected during registration. By default no
devices are forbidden.
Step 2/3. Register WebAuthn devices as a user
A user can register multiple WebAuthn devices using tsh
:
tsh mfa addChoose device type [TOTP, WEBAUTHN]: webauthn
Enter device name: desktop yubikey
Tap any *registered* security key or enter a code from a *registered* OTP device:
Tap your *new* security key
MFA device "desktop yubikey" added.
WebAuthn devices are currently not supported in tsh
on Windows.
Step 3/3. Log in using WebAuthn
Once a WebAuthn device is registered, the user will be prompted for it on login:
tsh login --proxy=example.comEnter password for Teleport user codingllama:
Tap any security key or enter a code from a OTP device:
> 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
WebAuthn for logging in to Teleport is only required for local users. SSO users should configure multi-factor authentication in their SSO provider.