# Passwordless This guide shows you how to provide passwordless and usernameless authentication for Teleport (called "passwordless" below for simplicity). With passwordless, users can authenticate to Teleport with only WebAuthn or Touch ID, and do not need to provide a username and password. ## How it works In passwordless, a user registers a WebAuthn or Touch ID device with Teleport using the Web UI or `tsh` client. When the user authenticates to Teleport, Teleport issues an authentication challenge for the client to sign with an authenticator, i.e., their local device. The authenticator signs the challenge, and the Teleport Auth Service verifies the signature against a trusted certificate authority. 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, multi-factor authentication keys are encrypted by the authenticator and stored in the Teleport Auth Service backend. Regardless of your device type, passwordless registrations may also be used for regular MFA. ## Prerequisites - A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * Teleport must be configured for WebAuthn. See the [Harden your Cluster Against IdP Compromises](https://goteleport.com/docs/zero-trust-access/management/security/idp-compromise.md) 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](https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) page. * A signed and notarized version of `tsh` is required for Touch ID. This means versions installed from Homebrew or compiled from source will not work. [Download the macOS tsh installer](https://goteleport.com/docs/installation/macos.md). * To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.7.3 CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` 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 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. ``` You may pick either `WEBAUTHN` or `TOUCHID` as the device type. Make sure to answer `YES` to "Allow passwordless logins". --- IMPORTANT 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. --- Details Registering Touch ID for tsh 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: **Teleport Community Edition** ``` $ tsh login --proxy=example.com --auth=passwordless Tap 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 ``` **Commercial** ``` $ tsh login --proxy=example.com --auth=passwordless Tap 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. --- WEB UI 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. Edit your cluster authentication preference configuration using the following command: ``` $ tctl edit cluster_auth_preference ``` Ensure that the configuration includes the `connector_name` field as shown below: ``` kind: cluster_auth_preference version: v2 metadata: name: cluster-auth-preference spec: type: local second_factors: ["webauthn"] webauthn: rp_id: example.com connector_name: passwordless # passwordless by default ``` ## 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](https://goteleport.com/docs/installation.md). ### 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 on 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](https://github.com/yubico/libfido2#installation), 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](https://goteleport.com/docs/installation.md). Touch ID support requires Macs with a Touch ID sensor and Secure Enclave. 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 diag Has 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 diag WebauthWin 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. Edit your cluster authentication preference using the following command: ``` $ tctl edit cluster_auth_preference ``` In your editor, ensure that your `cluster_auth_preference` includes a `passwordless` field similar to the following: ``` kind: cluster_auth_preference version: v2 metadata: name: cluster-auth-preference spec: type: local second_factors: ["webauthn"] webauthn: rp_id: example.com passwordless: false # disable passwordless ``` Save and close your editor to apply your changes. ### Why did my multi-factor authentication (MFA) device become a passkey? If your MFA authenticator suddenly started being listed as a passkey, that is because it was always a passkey. Certain devices or applications (like Chrome or Safari Touch ID keys) are always created as passkeys, despite instructions from Teleport. If an authenticator replies with the [credProps extension](https://w3c.github.io/webauthn/#sctn-authenticator-credential-properties-extension) during registration, or is used for a successful passwordless login, Teleport will automatically mark it as a passkey if that wasn't the case before.