Teleport

Using Teleport with OpenSSH

Length: 16:04

Teleport is fully compatible with OpenSSH and can be quickly set up to record and audit all SSH activity.

Using Teleport and OpenSSH has the advantage of getting you up and running, but in the long run, we would recommend replacing sshd with teleport. We've outlined these reasons in OpenSSH vs Teleport SSH for Servers?

Teleport is a standards-compliant SSH proxy and can work in environments with existing SSH implementations, such as OpenSSH. This guide will cover:

Configuring the OpenSSH server sshd to join a Teleport cluster. Existing fleets of OpenSSH servers can be configured to accept SSH certificates dynamically issued by a Teleport CA.
Configuring the OpenSSH client ssh to log in to Nodes inside a Teleport cluster.

Note

OpenSSH 6.9 is the minimum OpenSSH version compatible with Teleport. View your OpenSSH version with the command:

ssh -V

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.2.4
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.2.4
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Configure an OpenSSH server to join a Teleport cluster

sshd must be told to allow users to log in with certificates generated by the Teleport User CA. Start by exporting the Teleport CA public key.

Export the Teleport certificate authority certificate into a file and update your SSH configuration to trust Teleport's CA:

tctl needs to be run on the Auth Server.
sudo tctl auth export --type=user | sed s/cert-authority\ // > teleport_user_ca.pub
sudo mv ./teleport_user_ca.pub /etc/ssh/teleport_user_ca.pub
echo "TrustedUserCAKeys /etc/ssh/teleport_user_ca.pub" | sudo tee -a /etc/ssh/sshd_config

Restart sshd.

Now, sshd will trust users who present a Teleport-issued certificate. The next step is to configure host authentication.

The recommended solution is to ask Teleport to issue valid host certificates for all OpenSSH nodes. To generate a host certificate, run the following tctl command:

Creating host certs, with an array of every host to be accessed.
Wildcard certs aren't supported by OpenSSH. The domain must be fully
qualified.
Management of the host certificates can become complex. This is another
reason we recommend using Teleport SSH on nodes.
sudo tctl auth sign \      --host=api.example.com,ssh.example.com,64.225.88.175,64.225.88.178 \      --format=openssh \      --out=api.example.com
The credentials have been written to api.example.com, api.example.com-cert.pub
You can use ssh-keygen to verify the contents.
ssh-keygen -L -f api.example.com-cert.pub
api.example.com-cert.pub:
Type: [email protected] host certificate
Public key: RSA-CERT SHA256:ireEc5HWFjhYPUhmztaFud7EgsopO8l+GpxNMd3wMSk
Signing CA: RSA SHA256:/6HSHsoU5u+r85M26Ut+M9gl+HventwSwrbTvP/cmvo
Key ID: ""
Serial: 0
Valid: after 2020-07-29T20:26:24
Principals:
api.example.com
ssh.example.com
64.225.88.175
64.225.88.178
Critical Options: (none)
Extensions:
x-teleport-authority UNKNOWN OPTION (len 47)
x-teleport-role UNKNOWN OPTION (len 8)

Then add the following lines to /etc/ssh/sshd_config on all OpenSSH nodes, and restart sshd.

HostKey /etc/ssh/api.example.com
HostCertificate /etc/ssh/api.example.com-cert.pub

Use the OpenSSH client to access Teleport Nodes

It is possible to use the OpenSSH client ssh to connect to Nodes within a Teleport cluster. Teleport supports SSH subsystems and includes a proxy subsystem that can be used like netcat is with ProxyCommand to connect through a jump host.

OpenSSH client configuration may be generated automatically by tsh, or it can be configured manually. In either case, make sure you are running OpenSSH's ssh-agent, and have logged in to the Teleport Proxy Service:

eval `ssh-agent`
tsh --proxy=root.example.com login

ssh-agent will print environment variables into the console. Either eval the output as in the example above, or copy and paste the output into the shell you will be using to connect to a Teleport Node. The output exports the SSH_AUTH_SOCK and SSH_AGENT_PID environment variables that allow OpenSSH clients to find the SSH agent.

Automatic setup

Note

Automatic OpenSSH client configuration is supported on Linux and macOS as of Teleport 7.0 and on Windows as of Teleport 7.2.

tsh can automatically generate the necessary OpenSSH client configuration to connect using the standard OpenSSH client:

On the machine where you want to run the SSH client
tsh --proxy=root.example.com config

This will generate an OpenSSH client configuration block for the root cluster and all currently-known leaf clusters (if you are using Trusted Clusters). Append this to your local OpenSSH config file (usually ~/.ssh/config) using your text editor of choice.

Warning

If using PowerShell on Windows, note that normal shell redirection may write the file with the incorrect encoding. To ensure it's written properly, try the following:

tsh.exe config | out-file .ssh\config -encoding utf8 -append

Once configured, log in to any Node in the root.example.com cluster:

ssh [email protected]

This will connect to the node node1 on the root.example.com cluster. This name does not need to be DNS accessible as the connection will be routed through your Teleport Proxy Service.

If any Trusted Clusters exist, they are also configured:

ssh [email protected]

When connecting to Nodes with Teleport daemons running on non-standard ports (other than 3022), a port may be specified:

ssh -p 4022 [email protected]

Automatic OpenSSH and Multiple Clusters

If you switch between multiple Teleport Proxy Servers, you'll need to re-run tsh config for each to generate the cluster-specific configuration.

Similarly, if Trusted Clusters are added or removed, be sure to re-run the above command and replace the previous configuration.

Manual setup

On your client machine, you need to import the public key of Teleport's host certificate. This will allow your OpenSSH client to verify that host certificates are signed by Teleport's trusted host CA:

tctl auth export --type=host > teleport_host_ca.pub
On the machine where you want to run the ssh client
cat teleport_host_ca.pub >> ~/.ssh/known_hosts

If you have multiple Teleport clusters, you have to export and set up these certificate authorities for each cluster individually.

OpenSSH and Trusted Clusters

If you use Recording Proxy Mode and Trusted Clusters, you need to set up the certificate authority from the root cluster to match all Nodes, even those that belong to leaf clusters.

For example, if your Node naming scheme is *.root.example.com, *.leaf1.example.com, *.leaf2.example.com, then the @certificate-authority entry should match *.example.com and use the CA from the root Auth Server only.

Lastly, configure the OpenSSH client to use the Teleport Proxy Service when connecting to Nodes with matching names. Edit ~/.ssh/config for your user or /etc/ssh/ssh_config for global changes:

# root.example.com is the jump host (Proxy Service). Credentials will be
# obtained from the SSH agent.
Host root.example.com
    HostName 192.168.1.2
    Port 3023

# Connect to Nodes in the root.example.com cluster through the jump
# host (Proxy Service). Credentials will be obtained from the
# SSH agent.
Host *.root.example.com
    HostName %h
    Port 3022
    ProxyCommand tsh proxy ssh %[email protected]%h:%p

# Connect to Nodes within a Trusted Cluster with the name "leaf1.example.com".
Host *.leaf1.example.com
   HostName %h
   Port 3022
   ProxyCommand tsh proxy ssh --cluster=leaf1.example.com %[email protected]%h:%p

When everything is configured properly, you can use SSH to connect to any Node behind root.example.com:

ssh [email protected]

Note

Teleport uses OpenSSH certificates instead of keys, which means you cannot ordinarily connect to a Teleport Node by IP address. You have to connect by DNS name. This is because OpenSSH ensures the DNS name of the Node you are connecting to is listed under the Principals section of the OpenSSH certificate to verify you are connecting to the correct Node.

To connect to the OpenSSH server via tsh, add --port=<ssh port> with the tsh ssh command:

Example tsh ssh command to access database.work.example.com as root with an OpenSSH server on port 22 via tsh:

tsh ssh --port=22 [email protected]

Warning

The principal/username ([email protected] in the example above) being used to connect must be listed in the Teleport user/role configuration.

Revoke an SSH certificate

To revoke the current Teleport CA and generate a new one, run tctl auth rotate. Unless you've highly automated your infrastructure, we would suggest you proceed with caution as this will invalidate the user and host CAs, meaning that the new CAs will need to be exported to every OpenSSH-based machine again using tctl auth export as above.

Have a suggestion or can’t find something?

IMPROVE THE DOCS