diff --git a/docs/pages/connect-your-client/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-connect.mdx index 2a20411f4a3a0..987fb0834ce74 100644 --- a/docs/pages/connect-your-client/teleport-connect.mdx +++ b/docs/pages/connect-your-client/teleport-connect.mdx @@ -620,7 +620,7 @@ Below is the list of the supported config properties. | `keymap.openClusters` | `Command+E` on macOS `Ctrl+Shift+E` on Windows/Linux | Shortcut to open the cluster selector. | | `keymap.openProfiles` | `Command+I` on macOS `Ctrl+Shift+I` on Windows/Linux | Shortcut to open the profile selector. | | `keymap.openSearchBar` | `Command+K` on macOS `Ctrl+Shift+K` on Windows/Linux | Shortcut to open the search bar. | -| `headless.skipConfirm` | `false` | Skips the confirmation prompt for Headless WebAuthn approval and instead prompts for WebAuthn immediately. | +| `headless.skipConfirm` | `false` | Skips the confirmation prompt for Headless Authentication approval and instead prompts for MFA immediately. | | `ssh.noResume` | `false` | Disables SSH connection resumption. | | `ssh.forwardAgent` | `false` | Enables agent forwarding. | | `sshAgent.addKeysToAgent` | `auto` | Controls how keys are added to a local SSH agent. "auto" adds the keys only if the agent supports SSH certificates, "no" never attempts to add them, "yes" always attempts to add them, "only" always attempts to add the keys to the agent but it does not save them on disk. | diff --git a/docs/pages/faq.mdx b/docs/pages/faq.mdx index bc77c5eae7b03..01227402a2afe 100644 --- a/docs/pages/faq.mdx +++ b/docs/pages/faq.mdx @@ -75,7 +75,7 @@ look at [Using OpenSSH Guide](enroll-resources/server-access/openssh/openssh-age ## Can I copy files from one Teleport node to another? -Yes, Teleport supports [Headless WebAuthn authentication](zero-trust-access/authentication/headless.mdx), +Yes, Teleport supports [Headless Authentication](zero-trust-access/authentication/headless.mdx), which allows you to perform operations like `tsh ssh` or `tsh scp` from remote systems where you are not logged in to Teleport or may not have access to a browser. diff --git a/docs/pages/reference/cli/tsh.mdx b/docs/pages/reference/cli/tsh.mdx index 536202b9f21be..67caae29db6e3 100644 --- a/docs/pages/reference/cli/tsh.mdx +++ b/docs/pages/reference/cli/tsh.mdx @@ -47,7 +47,7 @@ Environment variables configure your tsh client and can help you avoid using fla | `--skip-version-check` | none | none | Skip version checking between server and client. | | `-d, --debug` | none | none | Verbose logging to stdout | | `-J, --jumphost` | none | A jump host | SSH jumphost | -| `--headless` | none | none | Use Headless WebAuthn for authentication | +| `--headless` | none | none | Use Headless Authentication | | `--mlock` | `auto` | `auto`, `off`, `best_effort`, `strict` | Lock process memory to protect client secrets stored in memory from being swapped to disk. | ## tsh apps ls diff --git a/docs/pages/zero-trust-access/authentication/headless.mdx b/docs/pages/zero-trust-access/authentication/headless.mdx index 687f2af1bada3..33f3869d7af78 100644 --- a/docs/pages/zero-trust-access/authentication/headless.mdx +++ b/docs/pages/zero-trust-access/authentication/headless.mdx @@ -1,41 +1,40 @@ --- -title: Headless WebAuthn -description: Headless WebAuthn +title: Headless Authentication +description: Headless Authentication tags: - how-to - zero-trust --- -Headless WebAuthn provides a secure way to authenticate with WebAuthn from a -machine without access to a WebAuthn device. This enables the use of WebAuthn -features which are usually not usable in WebAuthn-incompatible environments. +Headless Authentication provides a secure way to authenticate with Teleport on +a machine that does not have the ability to authenticate directly with the +required mechanisms. + For example: -- Logging into Teleport with WebAuthn from a remote dev box -- Connecting to a Teleport SSH Service from a remote dev box with per-session MFA -- Performing `tsh scp` from one Teleport SSH Service to another with per-session MFA -- Logging into Teleport on a machine without a WebAuthn-compatible browser +- Authenticating with [WebAuthn](./webauthn.mdx#set-up-cluster-wide-webauthn) or [SSO MFA](../sso/sso.mdx#allowing-sso-as-an-mfa-method-in-your-cluster) from a remote dev box +- Authenticating with WebAuthn on a machine without a WebAuthn-compatible browser +- Authenticating with SSO MFA from a browser that is not supported by your SSO provider - - Headless WebAuthn only supports the following `tsh` commands: + + Headless Authentication only supports the following `tsh` commands: - `tsh ls` - `tsh ssh` - `tsh scp` - In the future, Headless WebAuthn will be extended to other `tsh` commands. + In the future, Headless Authentication will be extended to other `tsh` commands. ## How it works -In the Headless WebAuthn flow, a user on a remote machine requests headless +In the Headless Authentication flow, a user on a remote machine requests headless authentication when running `tsh` commands. `tsh` sends a request to an API path on the Teleport Proxy Service, `/webapi/login/headless`, and the Teleport Proxy Service sends a request to the Teleport Auth Service to store a headless authentication request on its backend. `tsh` then obtains the ID of the request and prints a URL containing the ID in the user's terminal. The user accesses the -URL on their browser and completes a WebAuthn flow with the Teleport Auth -Service. +URL on their browser and completes an MFA flow with the Teleport Auth Service. Once the Teleport Auth Service authenticates the user, `tsh` generates a new private key in memory, and shares its public key only to obtain user @@ -44,23 +43,21 @@ to reduce the impact of exfiltration. ## Prerequisites -- A Teleport cluster with WebAuthn configured. - See the [Harden your Cluster Against IdP Compromises](./webauthn.mdx) guide. -- WebAuthn hardware device, such as YubiKey. -- Machines for Headless WebAuthn activities have [Linux](../../installation/installation.mdx), [macOS](../../installation/installation.mdx) or [Windows](../../installation/installation.mdx) `tsh` binary installed. -- Machines used to approve Headless WebAuthn requests have a Web browser with [WebAuthn support]( +- A Teleport cluster with [WebAuthn](./webauthn.mdx#set-up-cluster-wide-webauthn) or [SSO MFA](../sso/sso.mdx#allowing-sso-as-an-mfa-method-in-your-cluster) configured. +- Machines for Headless Authentication activities have [Linux](../../installation/installation.mdx), [macOS](../../installation/installation.mdx) or [Windows](../../installation/installation.mdx) `tsh` binary installed. +- Machines used to approve Headless Authentication requests have a Web browser with [WebAuthn support]( https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) or `tsh` binary installed. -- Optional: Teleport Connect for [seamless Headless WebAuthn approval](#optional-teleport-connect). +- Optional: Teleport Connect for [seamless Headless Authentication approval](#optional-teleport-connect). ## Step 1/3. Configuration -A Teleport cluster capable of WebAuthn is automatically capable of -Headless WebAuthn without any additional configuration. +A Teleport cluster capable of WebAuthn or SSO MFA is automatically capable of +Headless Authentication without any additional configuration.
-Optional: make Headless WebAuthn the default auth connector +Optional: make Headless Authentication the default auth connector -To make Headless WebAuthn the default authentication method for your Teleport +To make Headless Authentication the default authentication method for your Teleport Cluster, add `connector_name: headless` to your cluster configuration. Create a `cap.yaml` file or get the existing configuration using @@ -88,10 +85,10 @@ $ tctl create -f cap.yaml
-Alternative: disable Headless WebAuthn +Alternative: disable Headless Authentication -Headless WebAuthn is enabled automatically when WebAuthn is configured. If you -want to forbid Headless WebAuthn in your cluster, add `headless: false` to your +Headless Authentication is enabled automatically when WebAuthn or SSO MFA is configured. +If you want to forbid Headless Authentication in your cluster, add `headless: false` to your configuration. Create a `cap.yaml` file or get the existing configuration using @@ -107,7 +104,7 @@ spec: second_factors: ["webauthn"] webauthn: rp_id: example.com - headless: false # disable Headless WebAuthn + headless: false # disable Headless Authentication ``` Update the configuration: @@ -119,7 +116,7 @@ $ tctl create -f cap.yaml
-## Step 2/3. Initiate Headless WebAuthn +## Step 2/3. Initiate Headless Authentication Run a headless `tsh` command with the `--headless` flag. This will initiate headless authentication, printing a URL and `tsh` command. @@ -135,16 +132,16 @@ $ tsh ls --headless --proxy=proxy.example.com --user=alice # tsh headless approve --user=alice --proxy=proxy.example.com 86172f78-af7c-5935-a7c1-ed06b94f17dc ``` -## Step 3/3. Approve Headless WebAuthn +## Step 3/3. Approve Headless Authentication To approve the headless authentication, click or copy+paste the URL printed by `tsh` in your local web browser. You will be prompted to approve the log in with -WebAuthn verification. Once approved, your initial `tsh --headless ` +MFA verification. Once approved, your initial `tsh --headless ` should continue as if you had logged in locally. Unlike a standard login session, headless sessions are only available for the lifetime of a single `tsh` request. This means that for each `tsh --headless` -command, you will need to go through the Headless WebAuthn flow: +command, you will need to go through the Headless Authentication flow: ### Example: Listing SSH servers ```code @@ -177,34 +174,34 @@ alice@server01 $ ``` - The Teleport user, `--user` parameter, is the Teleport user requesting Headless WebAuthn activity. + The Teleport user, `--user` parameter, is the Teleport user requesting Headless Authentication activity. If no `--user` parameter or environment variables set the OS user in the machine terminal is used. The login username, `--login` parameter or login@hostname, for `tsh ssh` commands is the user to open a SSH session as. If no login username for the SSH session is set the OS terminal username is used. A Teleport user must have access to that login user for that server or they will receive an access denied message. The user could receive an access denied message after being approved - for their Headless WebAuthn activity since the same access rights are granted or denied as if running from + for their Headless Authentication activity since the same access rights are granted or denied as if running from your local terminal. ## Optional: Teleport Connect -Teleport Connect can also be used to approve Headless WebAuthn logins. Teleport -Connect will automatically detect the Headless WebAuthn login attempt and allow +Teleport Connect can also be used to approve Headless Authentication logins. Teleport +Connect will automatically detect the Headless Authentication login attempt and allow you to approve or cancel the request. ![Headless Confirmation](../../../img/headless/confirmation.png) You will be prompted to tap your MFA key to complete the approval process. -![Headless WebAuthn Approval](../../../img/headless/approval.png) +![Headless Authentication Approval](../../../img/headless/approval.png) ## Troubleshooting ### "WARN: Failed to lock system memory for headless login: ..." -When using Headless WebAuthn, `tsh` does not write private key and certificate data +When using Headless Authentication, `tsh` does not write private key and certificate data to disk(`~/.tsh`). Instead, `tsh` holds these secrets in memory for the duration of the request. Additionally, it will try to lock the process memory to further protect the secrets from being stolen by other users on a shared machine. @@ -223,7 +220,7 @@ the line ` hard memlock unlimited` to your `/etc/security/limits.co The `mlockall` syscall is only supported on Linux operating systems. This means that on other operating systems, the memory lock attempt will always fail and -output the warning. We recommend only using Headless WebAuthn on Linux machines +output the warning. We recommend only using Headless Authentication on Linux machines for the best level of security on shared machines. #### Disable mlock