Using Teleport with OpenSSH in agentless mode (manual installation)

In this guide, we will show you how to configure 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.

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. teleport SSH servers have support for multiple features that are incompatible with OpenSSH:

• RBAC and resource filtering based on dynamically updated labels
• Session recording without SSH connection termination
• Session sharing
• Advanced session recording

Teleport supports OpenSSH by proxying SSH connections through the Proxy Service. When a Teleport user requests to connect to an OpenSSH node, the Proxy Service checks the user's Teleport roles.

If the RBAC checks succeed, the Proxy Service authenticates to the OpenSSH node with a dynamically generated certificate signed by a Teleport CA. This allows the Proxy Service to record and audit connections to OpenSSH nodes.

The Proxy Service prevents Teleport users from bypassing auditing by requiring a certificate signed by a Teleport CA that only the Auth Service possesses.

In this setup, the Teleport SSH Service performs RBAC checks as well as audits and records sessions on its host, which eliminates the need for connection termination when recording SSH sessions.

Prerequisites

• OpenSSH version 6.9 or above on your local machine. View your OpenSSH version with the command:

  ssh -V

• A running Teleport cluster version 15.2.4 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• A Linux host with the OpenSSH server sshd version 7.4 or above installed, but not Teleport. The SSH port on this host must be open to traffic from the Teleport Proxy Service host.
• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example:

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

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Upgrading to v14 from legacy OpenSSH nodes

If you have previously configured OpenSSH nodes to trust a Teleport CA without registering them and you upgrade your Teleport cluster to Teleport 14, you won't be able to connect to them anymore by default. This is because open dialing to OpenSSH servers not registered with the cluster is no longer allowed in Teleport 14. To ensure that you will retain access to your OpenSSH nodes you will need to follow this guide to register every OpenSSH node with Teleport that you previously configured. This must be done before your Teleport cluster is upgraded to Teleport 14.

If you are having issues registering OpenSSH nodes or need to upgrade your Teleport cluster to Teleport 14 before registering all of your OpenSSH nodes, you can pass the TELEPORT_UNSTABLE_UNLISTED_AGENT_DIALING environment variable to your Proxy Service and set it to yes. This will allow connections to unregistered OpenSSH nodes but will be removed in Teleport v15.

Step 1/5. Add a node resource to your Teleport cluster

When you request an SSH connection to a OpenSSH node, Teleport needs to be able to find the node's IP address so it can establish a connection to it.

Declare a node resource so Teleport knows how to reach your OpenSSH server. On your local machine, create a file called openssh-node-resource.yaml with the following content:

kind: node
version: v2
sub_kind: openssh
metadata:
  name: a100fdd0-52db-4eca-a7ab-c3afa7a1564a
  labels:
    env: prod
spec:
  addr: 1.2.3.4:22
  hostname: openssh-node

spec.addr and spec.hostname are mandatory. Assign spec.addr to the address and port of your node and spec.hostname to the name of the node as you would like users to see it in Teleport.

The metadata.labels field labels the SSH Service instance so you can apply RBAC rules to it.

The metadata.name field isn't mandatory, but setting it here will save you some work later.

To generate a new universal unique identifier (UUID) suitable for a node name, use the uuidgen on Linux or MacOS, or use the New-Guid cmdlet in Powershell on Windows.

Create the node resource:

tctl create openssh-node-resource.yaml

Step 2/5. Configure sshd to trust the Teleport CA

Later in this guide, we will generate an SSH client configuration that will use a certificate signed by the Teleport Auth Service to authenticate to your SSH server. For this to work, sshd must be told to allow users to log in with certificates generated by the Teleport Auth Service.

Start by exporting the Teleport CA public key.

On the host where you are running sshd, run the following commands, assigning proxy to the address of your Teleport Proxy Service:

export KEY=$(curl 'https://proxy/webapi/auth/export?type=openssh' | sed "s/cert-authority\ //")

Make the public key accessible to sshd:

sudo bash -c "echo \"$KEY\" > /etc/ssh/teleport_openssh_ca.pub"
sudo bash -c "echo 'TrustedUserCAKeys /etc/ssh/teleport_openssh_ca.pub' >> /etc/ssh/sshd_config"

Restart sshd. For systemd-enabled hosts, run the following command:

sudo systemctl restart sshd

Now, sshd will trust users who present a Teleport-issued certificate.

Step 3/5. Configure host authentication

Next, ask Teleport to issue a valid host certificate for your sshd host. Later in this guide, we will configure your SSH client to trust the certificate, authenticating your sshd host for your SSH client. Like the user certificate we created earlier, the host certificate will be signed by the Teleport Auth Service.

Ensure that your user has the correct privileges

Your user must be authorized to read and write host certificates.

On your local machine, create a file called host-certifier.yaml with the following content:

kind: role
version: v5
metadata:
  name: host-certifier
spec:
  allow:
    rules:
      - resources:
          - host_cert
        verbs:
          - list
          - create
          - read
          - update
          - delete

Create the role resource:

tctl create host-certifier.yaml
role 'host-certifier' has been created

Assign the host-certifier role to your Teleport user by running the appropriate commands for your authentication provider:

You will now have the required permissions to export a host key for your sshd host.

Issue a host certificate

tctl get node/openssh-node --format text

tctl get node/openssh-node --format=json | jq -r ".[0].metadata.name"

tctl get node/openssh-node

Create the host certificate

When creating host certificates, it is important to specify all the domain names and addresses that refer to your node. If you try to connect to a node with a name or address that was not specified when creating it's host certificate, Teleport will reject the SSH connection.

On your local machine, assign the IP address, fully qualified domain name of your node, and the node's UUID to an environment variable. If you won't be connecting to your node with its hostname, you can safely omit it.

ADDR=1.2.3.4,openssh-node,a100fdd0-52db-4eca-a7ab-c3afa7a1564a

Run the following tctl command to generate a host certificate:

tctl auth sign \      --host=${ADDR?} \      --format=openssh \      --out=myhost

The credentials have been written to myhost, myhost-cert.pub

The above command will result in a private key and certificate.

Use ssh-keygen to verify the contents of the certificate:

ssh-keygen -L -f myhost-cert.pub

The Principals section should contain the address you assigned to ADDR earlier:

myhost-cert.pub:
        Type: [email protected] host certificate
        Public key: RSA-CERT SHA256:nHkp6SnrAW4AV00VUaqPgR6SgdyvV9MmjUrYnwZ779A
        Signing CA: RSA SHA256:euqx2Y8Pq+r0c94GKVNXAklBVTmAJtaQUn3/ehrfEJE (using rsa-sha2-512)
        Key ID: ""
        Serial: 0
        Valid: after 2022-04-22T11:14:16
        Principals:
                1.2.3.4
                openssh-node
                a100fdd0-52db-4eca-a7ab-c3afa7a1564a
        Critical Options: (none)
        Extensions:
                x-teleport-authority UNKNOWN OPTION (len 33)
                x-teleport-role UNKNOWN OPTION (len 8)

Copy the host key and certificate to your sshd host, placing them in the directory /etc/ssh.

Make sure these files have the correct permissions:

sudo chmod 0600 /etc/ssh/myhost
sudo chmod 0600 /etc/ssh/myhost-cert.pub

Then add the following lines to /etc/ssh/sshd_config on your sshd host:

HostKey /etc/ssh/myhost
HostCertificate /etc/ssh/myhost-cert.pub

Restart sshd.

Step 4/5. Generate an SSH client configuration

The next step is to configure your OpenSSH client to connect to your sshd host using credentials managed by Teleport. This configuration will use your user's Teleport-issued certificate to authenticate to the sshd host. It will also authenticate the sshd host using the host certificate you generated earlier.

First, make sure you have logged in to your Teleport cluster:

tsh status
> Profile URL:        https://teleport.example.com:443  Logged in as:       myuser  Cluster:            teleport.example.com  Roles:              access, auditor, editor, host-certifier  Logins:             ubuntu, root  Kubernetes:         enabled  Valid until:        2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s]  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

tsh status
> Profile URL:        https://teleport.example.com:443  Logged in as:       myuser  Cluster:            teleport.example.com  Roles:              access, auditor, editor, reviewer, host-certifier  Logins:             ubuntu, root  Kubernetes:         enabled  Valid until:        2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s]  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

tsh status
> Profile URL:        https://mytenant.teleport.sh:443  Logged in as:       myuser  Cluster:            mytenant.teleport.sh  Roles:              access, auditor, editor, reviewer, host-certifier  Logins:             ubuntu, root  Kubernetes:         enabled  Valid until:        2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s]  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

On your local machine, run the following tsh command. This will print a configuration block that tells your SSH client to use credentials managed by Teleport to connect to hosts in your cluster.

tsh config > ssh_config_teleport

This command creates an SSH configuration file at a nonstandard location in order to make it easier to clean up, but you can append the output of tsh config to the default SSH config file (~/.ssh/config) if you wish.

# Common flags for all {{ .ClusterName }} hosts
Host *.{{ .ClusterName }} {{ .ProxyHost }}
    UserKnownHostsFile "{{ .KnownHostsPath }}"
    IdentityFile "{{ .IdentityFilePath }}"
    CertificateFile "{{ .CertificateFilePath }}"

# Flags for all {{ .ClusterName }} hosts except the proxy
Host *.{{ .ClusterName }} !{{ .ProxyHost }}
    Port 3022
    ProxyCommand "{{ .TSHPath }}" proxy ssh --cluster={{ .ClusterName }} --proxy={{ .ProxyHost }} %r@%h:%p

/usr/bin/ssh -l root -A -o UserKnownHostsFile=/root/.tsh/known_hosts -p 11105 teleport.example.com -s proxy:mynode:[email protected]

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

Step 5/5. Connect to your sshd host

Once you have appended the new text to your OpenSSH client configuration file, you can log in to your sshd host using the configuration we generated earlier.

First, define environment variables for the address of your Teleport cluster, the username you will use to log in to your sshd host, and the port on your sshd host you are using for SSH traffic:

See the available logins you can use to access your sshd host
tsh status | grep Logins
Logins:             ubuntu, root
USER=ubuntu
CLUSTER=teleport.example.com
PORT=22

See the available logins you can use to access your sshd host
tsh status | grep Logins
Logins:             ubuntu, root
USER=ubuntu
CLUSTER=mytenant.teleport.sh
PORT=22

Next, SSH in to your remote host:

ssh -p ${PORT?} -F ssh_config_teleport "${USER?}@${ADDR?}.${CLUSTER?}"

This name does not need to be resolvable via DNS as the connection will be routed through your Teleport Proxy Service.

ssh -F ssh_config_teleport ${USER?}@node2.leafcluster.${CLUSTER}