How to connect to Teleport hosts using Windows

Here’s an example of how to connect to Teleport hosts from Windows machines.

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://gravitational.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.

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

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 unixuser@teleport.example.com -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 unixuser@teleport.example.com -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)

unixuser@teleport.example.com: 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 unixuser@teleport.example.com -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 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 unixuser@teleport.example.com -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\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

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