Here’s an example of how to connect to Teleport hosts from Windows machines.
- We will assume that your windows username is
User. If your Windows username is different, please replace
Userwith your own username throughout these examples.
- We will assume that
teleport.example.comis 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.
- Windows 10 version 1809
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
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 -
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 email@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 firstname.lastname@example.org -s proxy:%h:%p" unixuser@examplehost -p 3022 The authenticity of host '[teleport.example.com]:3023 ([126.96.36.199]: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,[188.8.131.52]: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
-p 3023: the SSH connection for the
ProxyCommand should connect to port 3023 (Teleport’s SSH proxy service)
email@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
%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
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 firstname.lastname@example.org -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@example.com -s proxy:%h:%p" unixuser@examplehost -p 3022, you can type
ssh examplehost instead:
C:\Users\User>ssh examplehost unixuser@examplehost:~$
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 -
C:\Users\IUser>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\IEUser>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.