Meet us at KubeCon + CloudNativeCon: Paris, France - March 19
Book Demo
Teleport logoTry For Free
Fork me on GitHub

Teleport

Passwordless

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise
Introducing Teleport 10 Passwordless

Introducing Teleport 10 Passwordless

Length: 02:12

Passwordless takes advantage of WebAuthn to provide passwordless and usernameless authentication for Teleport.

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 15.0.2.

    See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.3.6.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.6 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.6 go1.21

Proxy version: 14.3.6Proxy: teleport.example.com
  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 15.0.2.

    You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.6.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.6 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.6 go1.21

Proxy version: 14.3.6Proxy: 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 run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example:
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 15.0.2

    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".

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.

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.

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=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

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:

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.yaml

cluster auth preference has been updated

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.yaml

cluster auth preference has been updated

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

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.yaml

cluster auth preference has been updated

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.yaml

cluster auth preference has been updated