How to Connect to Teleport from Windows Client Pre and Post Teleport 6.1.x

[deusxanima]

Assumptions:

• We will assume that your windows username is User. If your Windows username is different, please replace User with your own username throughout these examples.
• We will assume that teleport.example.com is the name of the Teleport proxy server - please change this to your own server.
• We will assume that the target host to connect to is examplehost - please change this to the name of the host you actually wish to access.

Requirements:

• Windows 10 version 1809 or higher

Assumptions:

• We will assume that your windows username is User. If your Windows username is different, please replace User with your own username throughout these examples.
• We will assume that teleport.example.com is the name of the Teleport proxy server - please change this to your own server.
• We will assume that the target host to connect to is examplehost - please change this to the name of the host you actually wish to access.

Requirements:

• Windows 10 version 1809 or higher

Installing the OpenSSH client

Firstly, you'll need to install the OpenSSH client by following the instructions from Microsoft here: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse

Once this is done, when you open Command Prompt and type ssh.exe you should get some output describing how to use the ssh command:

Microsoft Windows [Version 10.0.17763.973]
(c) 2018 Microsoft Corporation. All rights reserved.

C:\Users\User>ssh.exe
usage: ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface]
           [-b bind_address] [-c cipher_spec] [-D [bind_address:]port]
           [-E log_file] [-e escape_char] [-F configfile] [-I pkcs11]
           [-i identity_file] [-J [user@]host[:port]] [-L address]
           [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]
           [-Q query_option] [-R address] [-S ctl_path] [-W host:port]
           [-w local_tun[:remote_tun]] destination [command]

Downloading the Teleport client - tsh.exe

Once this is done, download the latest version of Teleport for Windows from https://goteleport.com/teleport/download - you're looking for the one titled "
Windows (64-bit, tsh client only)".

This will download a ZIP file. Open the ZIP file, open the "teleport" directory and find the "tsh.exe" file - you should copy this file to C:\Users\User so that it's easily accessible when opening a Command Prompt.

Logging into a Teleport cluster

To authenticate with Teleport, you'll need to run tsh.exe login --proxy=teleport.example.com and follow the authentication flow. Once done, you should get some output:

C:\Users\User>tsh.exe login --proxy=teleport.example.com
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:49820/0605ae8e-e941-4ee5-8266-5d2d3677cd2e
> Profile URL:  https://teleport.example.com:3080
  Logged in as: exampleuser
  Cluster:      teleport.example.com
  Roles:        admin*
  Logins:       unixuser
  Valid until:  2020-02-03 19:37:31 -0800 PST [valid for 12h0m0s]
  Extensions:   permit-agent-forwarding, permit-port-forwarding, permit-pty


* RBAC is only available in Teleport Enterprise
  https://gravitational.com/teleport/docs/enterprise

Logging into the Teleport cluster will saves your SSH certificate to your local machine under C:\Users\User\.tsh\keys\teleport.example.com - let's look at the contents of this directory.

Pre-6.1.x this directory should look something like this:

C:\Users\User>dir "C:\Users\User\.tsh\keys\teleport.example.com"
 Volume in drive C is Windows 10
 Volume Serial Number is 1234-5678

 Directory of C:\Users\User\.tsh\keys\teleport.example.com

02/03/2020  06:43 AM    <DIR>          .
02/03/2020  06:43 AM    <DIR>          ..
02/03/2020  07:37 AM             1,286 certs.pem
02/03/2020  07:37 AM             1,675 exampleuser
02/03/2020  07:37 AM             1,534 exampleuser-cert.pub
02/03/2020  07:37 AM             1,277 exampleuser-x509.pem
02/03/2020  07:37 AM               381 exampleuser.pub
               5 File(s)          6,153 bytes
               2 Dir(s)  22,982,397,952 bytes free

In this directory setup, exampleuser is the private key and exampleuser-cert.pub is the SSH certificate encapsulating our user identity. We'll need to use these files when connecting to other hosts via Teleport.

Post-6.1.x this directory should look something like this:

C:\Users\User>dir "C:\Users\User\.tsh\keys\teleport.example.com"
 Volume in drive C is Windows 10
 Volume Serial Number is 1234-5678

 Directory of C:\Users\User\.tsh\keys\teleport.example.com

02/03/2020  06:43 AM    <DIR>          .
02/03/2020  06:43 AM    <DIR>          ..
02/03/2020  07:37 AM             1,286 certs.pem
02/03/2020  07:37 AM             1,675 exampleuser
02/03/2020  07:37 AM    <DIR>    1,534 exampleuser-ssh
02/03/2020  07:37 AM             1,277 exampleuser-x509.pem
02/03/2020  07:37 AM               381 exampleuser.pub
               5 File(s)          6,153 bytes
               2 Dir(s)  22,982,397,952 bytes free

In this directory setup, exampleuser is the private key. If we go one layer deeper into the exampleuser-ssh directory we will also find an teleport.example.com-cert.pub cert file, which is the SSH certificate encapsulating our user identity. We'll need to use these files when connecting to other hosts via Teleport.

Making an SSH connection

Here's an example command using Teleport as an SSH proxy/bastion host:

ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser -o "ProxyCommand=ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser -p 3023 [email protected] -s proxy:%h:%p" unixuser@examplehost -p 3022

Here's what happens when you run it:

C:\Users\User>ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser -o "ProxyCommand=ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser -p 3023 [email protected] -s proxy:%h:%p" unixuser@examplehost -p 3022 
The authenticity of host '[teleport.example.com]:3023 ([1.2.3.4]:3023)' can't be established.
RSA key fingerprint is SHA256:ff6AcuwDoF6AiNlUxCbk9pqJu8n9gEVX6Ek1fH6sYEI.
Are you sure you want to continue connecting (yes/no)?
Warning: Permanently added '[teleport.example.com]:3023,[1.2.3.4]:3023' (RSA) to the list of known hosts.
The authenticity of host 'examplehost (<no hostip for proxy command>)' can't be established.
RSA key fingerprint is SHA256:0pUmlsntyE6fNcOkxA5GwAMo56M8geOypnwwyYVeHT4.
Are you sure you want to continue connecting (yes/no)? yes 
Warning: Permanently added 'examplehost' (RSA) to the list of known hosts.
unixuser@examplehost:~$

For the curious, let's break down the different parts of this command and what they do.

-i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser: tells SSH to use this file as the identity to connect to the remote host (examplehost) - as this is a private key associated with an SSH certificate, SSH will automatically also use the exampleuser-cert.pub file here in the background.

-o "ProxyCommand=ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser: sets up a command that will be run before the main SSH connection as a ProxyCommand

-p 3023: the SSH connection for the ProxyCommand should connect to port 3023 (Teleport's SSH proxy service)

[email protected]: The system username and proxy hostname to connect to for the ProxyCommand. This system username must be one that you're allowed to use to log in with Teleport - see the Logins: field in the output of tsh login or tsh status for usernames you can use.

-s proxy:%h:%p": when connected to the proxy host, invoke the proxy subsystem. %h is automatically replaced with the hostname of the remote host as (examplehost in this case) and %p is automatically replaced with the target port for the remote host connection (3022 in this case)

unixuser@examplehost: The system username and hostname to connect to after making the proxy connection - this is the host your shell will actually be connected to once the SSH command runs.

-p 3022: The port listening for SSH connections on the remote host - this is the default port for the Teleport 'node' service.

Using the SSH config file

The SSH command above is very long and complicated, so typing or copying this every time you want to connect to a host will get old quickly. You can tell SSH to automatically apply a configuration whenever you connect to a certain host by editing the SSH client configuration file, found at C:\Users\User\.ssh\config

Here's an example of how to automatically apply our settings from the command line via the SSH client config file:

Host examplehost
    User unixuser
    Port 3022
    IdentityFile C:\Users\User\.tsh\keys\teleport.example.com\exampleuser
    ProxyCommand ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser [email protected] -p 3023 -s proxy:%h:%p"

When this file is saved to C:\Users\User\.ssh\config, SSH will automatically read it and apply the settings before connecting. This means that instead of typing the long-winded ssh -i "C:\Users\User\.tsh\keys\teleport.example.com\exampleuser" -o "ProxyCommand=ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser -p 3023 [email protected] -s proxy:%h:%p" unixuser@examplehost -p 3022, you can type ssh examplehost instead:

When this file is saved to C:\Users\User\.ssh\config, SSH will automatically read it and apply the settings before connecting. This means that instead of typing the very long-winded ssh -i "C:\Users\User\.tsh\keys\teleport.example.com\exampleuser" -o "ProxyCommand=ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser -p 3023 [email protected] -s proxy:%h:%p" unixuser@examplehost -p 3022, you can type ssh examplehost instead:

C:\Users\User>ssh examplehost
unixuser@examplehost:~$

Much shorter!

Advanced use cases: ssh-agent

If you start the OpenSSH authentication agent service on your Windows machine, this will automatically receive certificates from Teleport so that you don't need to explicitly specify an identity file each time you connect.

You can start ssh-agent from the Windows services menu - services.msc

C:\Users\IUser>ssh-add -l
C:\Users\User>ssh-add -l
The agent has no identities.

C:\Users\User>tsh.exe login --proxy=teleport.example.com
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:49884/cab847d1-ecf7-4310-bdbe-73d75a4e4878
> Profile URL:  https://teleport.example.com:3080
  Logged in as: exampleuser
  Cluster:      teleport.example.com
  Roles:        admin*
  Logins:       unixuser
  Valid until:  2020-02-03 19:37:31 -0800 PST [valid for 12h0m0s]
  Extensions:   permit-agent-forwarding, permit-port-forwarding, permit-pty


* RBAC is only available in Teleport Enterprise
  https://gravitational.com/teleport/docs/enterprise

The agent has no identities.

C:\Users\User>tsh.exe login --proxy=teleport.example.com
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:49884/cab847d1-ecf7-4310-bdbe-73d75a4e4878
> Profile URL:  https://teleport.example.com:3080
  Logged in as: exampleuser
  Cluster:      teleport.example.com
  Roles:        admin*
  Logins:       unixuser
  Valid until:  2020-02-03 19:37:31 -0800 PST [valid for 12h0m0s]
  Extensions:   permit-agent-forwarding, permit-port-forwarding, permit-pty


* RBAC is only available in Teleport Enterprise
  https://gravitational.com/teleport/docs/enterprise

C:\Users\IEUser>ssh-add -l
C:\Users\User>ssh-add -l
2048 SHA256:b3hPwiIenc9ckOO4548xK3tkLvXt2ehCGXPHZZejjOY teleport:exampleuser (RSA-CERT)

This can be useful if you need to connect onward from examplehost to other machines and still want to use your SSH identity.This can be useful if you need to connect onward from examplehost to other machines and still want to use your SSH identity. You can use the -A command line argument to ssh to forward your ssh-agent identity on to the server you connect to, or specify ForwardAgent yes in your .ssh/config file.

Advanced use cases: IdentitiesOnly

If we want to specify and limit which keys your SSH client should look for (this can be useful in cases of being logged into multiple clusters simultaneously), we can pass the IdentitiesOnly flag along with the IdentityFile flag either in the SSH command or via config. Starting with Teleport 6.1.x we will want to specify the full path to the cert and not the private key as we did in the example above. Below is an example of how this would look like in an updated SSH config:

Host examplehost
    User unixuser
    Port 3022
    IdentitiesOnly yes
    IdentityFile C:\Users\User\.tsh\keys\teleport.example.com\exampleuser-ssh\teleport.example.com-cert.pub
    ProxyCommand ssh.exe -i C:\Users\User\.tsh\keys\teleport.example.com\exampleuser-ssh\teleport.example.com-cert.pub [email protected] -p 3023 -s proxy:%h:%p"

[nickbrennan1]

With tsh releases 7.0.0 onwards, there is additional functionality included that will auto-generate the text for your~\.ssh\config file.

To generate, simply login to your proxy (tsh.exe --proxy=example.teleport.com --user=username), and once authenticated run tsh.exe config. This will generate the configuration relevant to your login for the config file - you should then copy and past this information into the file manually (or alternatively run the command with a redirect to the file).

With release 7.2, you no longer need to install OpenSSH for tsh.exe to work, as the SSH functionality is build in to the Windows client. You can then run tsh.exe in the same was as the *nix client with no additional software. However, if you use 3rd party editing software such as VSCode, you will still need to install SSH as the tsh SSH functionality won't be recognized.