Using Teleport with OpenSSH | teleport documents (2023)

In this guide we will show you how to configure the OpenSSH server.sshdto join a teleport group. Existing fleets of OpenSSH servers can be configured to accept dynamically issued SSH certificates from a teleport CA.

Using Teleport and OpenSSH has the benefit of being up and running, but in the long run we recommend replacing themsshdimpostorteleportWe describe these reasons in¿OpenSSH vs. Teleport SSH for servers?

previous requirements

OpenSSH version 6.9 or higher on your local machine. Check your OpenSSH version with the command:
```
ssh-V
```

A running teleport cluster. See one of our for details on how to set it upbeginningFührer
Ötctlmanagement tool andchClient-Tool-Version >= 11.1.4.
```
tctl-Version
Teleport v11.1.4 go1.19
tsh-Version
Teleport v11.1.4 go1.19
```
verInstallationfor details.

A running teleport cluster. See our Enterprise for setup detailsbeginningManual.
Ötctlmanagement tool andchClient tool version >= 11.1.4 which you can download by visiting thecustomer portal.
```
tctl-Version
Teleport v11.1.4 go1.19
tsh-Version
Teleport v11.1.4 go1.19
```

A Teleport Cloud account. If you don't have one, visit themregistration pageto start your free trial.
Ötctlmanagement tool andchClient tool version >= 11.1.3. To download these tools, visit theDownloadsSide.
```
tctl-Version
Teleport v11.1.3 go1.19
tsh-Version
Teleport v11.1.3 go1.19
```

A Linux host with an OpenSSH serversshdinstalled but not teleport. The SSH port on this host must be open for traffic from the Teleport Proxy Service host.

To connect to Teleport, log in to your cluster withch, then usetctlfrom far:

tsh login --proxy=teleport.example.com[email protected]
Status tctl
teleport.example.com-Cluster
Version 11.1.4
Pin CA sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can then runtctlCommands in this guide on your local computer.

For full rights you can also runtctlCommands on your authentication service host.

To connect to Teleport, log in to your cluster withch, then usetctlfrom far:

tsh-Login --proxy=miinstancia.teleport.sh[email protected]
(Video) Using Teleport with OpenSSH
Status tctl
Bundle my instance.teleport.sh
Version 11.1.3
CA Pine sha256: sha-hash-hier

Must be executed afterwardstctlCommands in this guide on your local computer.

Step 1/4. settings`sshd`confie no CA teleport

Later in this guide, we'll generate an SSH client configuration that uses a certificate signed by the Teleport authentication service to authenticate with your SSH server. for this to work,sshdmust be set to allow users to log in with certificates generated by the teleport authentication service.

Begin by exporting the Teleport CA's public key.

On your local machine, print the Teleport CA certificate to tostdout:

tctl authentication export --type=user | sed "no/cert-authority\ //"

Copy the output.

On the host it is running onsshd, run the following commands.

Assign the exitTctl authentication exportCommand for an environment variable:

Step 2/4. Configure host authentication

Then ask Teleport to issue a valid host certificate for yousshdHost. Later in this guide, we'll configure your SSH client to trust and authenticate the certificatesshdHost for your SSH client. Just like the user certificate created earlier, the host certificate is signed by the Teleport AuthService.

Make sure your user has the correct permissions

Your user must have permission to read and write host certificates.

Create a file named on your local computerhost-certifier.yamlwith the following content:

Class: professionExecution: v5metadata: Name: Host CertificateSpecifications: to allow: the rules: - Resources: - host_cert verbs: - list - cry - archive - To update - remover

Create the role resource:

Create tctl host-certifier.yaml
The Host Certifier role has been created

Assign theHost CertificateRole for the teleport user by running the following commands depending on whether you are authenticating as a local teleport user or via thegithub,low, ÖoidcAuthentication Ports:

Get the local user configuration resource:

tctl get users / $ ( tsh status - f json | jq - r ' . active . username ' ) > out . Yaml

To editout.yaml, AddHost Certificateto the list of available functions:

Features: - Access - Auditor - Editor+ - Host Certifier

Apply your changes:

tctl create -f out.yaml

recover yourgithubConfiguration function:

tctl obtener github/github > github.yaml

(Video) Manage all your SSH servers with teleport

To editgithub.yaml, AddHost CertificateAllteams_to_rolesSection. The team you assign to this role depends on how you designed your organization's RBAC, but it should be as small a team as possible within your organization. This team must also include your user.

Here is an example:

teams_to_roles: - Organization: Team Octocats: Administrators Roles: - Access+ - Host Certifier

Apply your changes:

tctl criar -f github.yaml

recover yourlowConfiguration function:

tctl obtener saml/mysaml > saml.yaml

To editsaml.yaml, AddHost CertificateAllattribute_to_rolesSection. The attribute you assign to this role depends on how you designed your organization's RBAC, but it should be the smallest possible group within your organization. This group must also contain your user.

Here is an example:

attribute_to_roles: - name: "groups" value: "my-group" roles: - access+ - Host Certifier

Apply your changes:

tctl criar -f saml.yaml

recover youroidcConfiguration function:

tctl get oidc/myoidc > oidc.yaml

To editoidc.yaml, AddHost CertificateAllClaims_to_rolesSection. The claim you assign to this role depends on how you designed your organization's RBAC, but it should be as small a group within your organization as possible. This group must also contain your user.

Here is an example:

Claims_to_roles: - name: "groups" value: "my group" roles: - access+ - Host Certifier

Apply your changes:

tctl criar -f saml.yaml

Log out of your teleport cluster and log back in to assume the new role.

You now have the necessary permissions to export a host key to yourssshdHost.

Issue a host certificate

On your local machine, assign your node's IP address or FQDN to an environment variable.

ADDRESS=203.0.113.0

do the followingtctlCommand to generate a host certificate:

tctl authentication character \--host=${ADDRESS?} \--format=abresh \--out=mihost
Credentials were written to myhost, myhost-cert.pub

The above command generates a private key and certificate.

To generate certificates for multiple hosts, assign thehostFlag for a comma-separated list of addresses. OpenSSH does not support certificates for wildcard domains, so each domain must be fully qualified.

Usessh-keygento check the content of the certificate:

ssh-keygen -L -f myhost-cert.pub
(Video) How I secure my Server Access with Teleport (for SSH, K8S, and Web)

ÖdirectorsThe section must contain the address you assignedDIRECTIONearly:

myhost-cert.pub: He writes: [email protected] host certificate Public key: RSA-ZERT SHA256:nHkp6SnrAW4AV00VUaqPgR6SgdyvV9MmjUrYnwZ779A Company CA: RSA SHA256:euqx2Y8Pq+r0c94GKVNXAklBVTmAJtaQUn3/ehrfEJE (under use rsa-sha2-512) ID von Chave: "" Serial number: 0 Valid: after this 2022-04-22T11:14:16 Directors: 203.0.113.0 critical options: (none) Extensions: x teleport authority A FOREIGN POSSIBILITY (len 33) x-Teleport-Rolle A FOREIGN POSSIBILITY (len 8)

Copy the host key and certificate to yourssshdhost and puts them in the directory/etc/ssh.

Make sure these files have the correct permissions:

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

Then add the following lines/etc/ssh/sshd_configin themsshdHost:

host key /etc/ssh/mihostHost Certificate /etc/ssh/myhost-cert.pub

rebootsshd.

Step 3/4. Generate an SSH client configuration

The next step is to configure your OpenSSH client to connect to yourssshdHosting credentials managed by Teleport. This configuration uses the SSH agent and the certificate issued by your user's teleport to authenticate with thesshdHost. It will also authenticate yousshdHost with the previously generated host certificate.

First, make sure you're running OpenSSHssh-agentand you are connected to your teleport cluster:

Status tsh
> Profile URL: https://teleport.example.com:443
Introduced as: myusername
Cluster: teleport.example.com
Roles: Access, Reviewer, Editor, Host Certifier
Logins: ubuntu, root
Kubernetes: enabled
Valid until: 05/06/2022 22:54:01 -0400 EDT [valid for 11h53m0s]
Erweiterungen: Permission-Agent-Forwarding, Permission-Port-Forwarding, Permission-Pty
eval `ssh-agent`
Agent PID 5931

Össh-agentThe command prints additional commands for exporting theSSH_AUTH_SOCKjSSH_AGENT_PIDenvironment variables. These variables allow OpenSSH clients to find the SSH agent. Hurry upssh-agentimpostorEvaluateRun these commands.

Run the following on your local computerchDomain. This will print a configuration block that tells your SSH client to use Teleport-managed credentials to connect to the hosts in your cluster.

tsh config > ssh_config_teleport

This command creates an SSH configuration file in a non-default location for easier cleanup, but you can add the output oftsh-configinto the default SSH configuration file (~/.ssh/config) If you wish.

Teleport implements an SSH server containing severalSubsysteme, or predefined commands that are executed when the server processes a connection. The ProxyService implements aLawyerSubsystem that forwards SSH traffic to remote hosts and trusted clusters.

Here is a brief explanation of the configuration thattsh-configGenres:

# Common flags for all hosts {{ .ClusterName }}Host *.{{ .ClusterName }} {{ .ProxyHost }} UserKnownHostsFile"{{ .Known host path }}"identity file"{{ .IdentityFilePath }}"CertificateArchive"{{ .CertificateFilePath }}"

if you are the hostsching en belongs to your Teleport cluster (i.e. its address is a subdomain of your cluster domain), use a well-known hosts file managed by Teleport, a private key and a certificate stored in.tshDirectory.

# Flags for all {{ .ClusterName }} hosts except the proxyHost *.{{ .ClusterName }} !{{ .ProxyHost }} Porto 3022 ProxyCommand "{{ .TSHPath }}" Proxy ssh--Group={{ .ClusterName }} --proxy={{ .ProxyHost }} %[email protected]%h:%p

If you are the hostsching en belongs to your teleport cluster, the OpenSSH client first runs a command thatproxy command, which establishes an SSH connection to the proxy service. this command,Proxy tsh ssh, request theLawyerSubsystem to forward SSH traffic to the selected host (including a host in a TrustedCluster) through the proxy service.

ÖProxy tsh sshcommand calls for theLawyerSubsystem via a command similar to the following, which assumes you are logging in to a node namedMinodolikeThosewith a group calledteleport.ejemplo.com:

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

Note that theknown_hostThe file used by the command is managed bych.SincesshdThe host information is listed in this file, your SSH client can authenticate the host via the certificate generated earlier.

If you're using PowerShell on Windows, be aware that normal shell redirection can write the file with the wrong encoding. To make sure it's spelled correctly, try the following:

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

Proxy-Hop

In the configuration of the generated OpenSSH client, theproxy commandFor each leaf cluster, it connects through the root cluster proxy service. In scenarios where the SSH client can access the leaf cluster's proxy services, you may prefer to connect directly through the leaf proxies to reduce latency.

(Video) Is Teleport a replacement for OpenSSH?

To enable direct connections to a proxy service on a leaf cluster, open and update the previously generated SSH configuration fileproxy commandfrom the leaf cluster configuration block to use the leaf proxy service as a jump host by using the-JBandera.

Host *.{{ .NodeName }}.leaf1.example.com Puerto 3022 ProxyBefehl tsh proxy ssh -J proxy.leaf1.example.com:443 %[email protected]%h:%p

Proxy Templates

With proxy templateschdynamically determines the address of the proxy service to connect to based on the destination host address in yourschDomain.

To use proxy templates, add-J {{Proxy}}Allproxy commandline on your~/.ssh/config.

Host *.example.com Porto 3022 ProxyBefehl tsh proxy ssh -J {{proxy}} %[email protected]%h:%p

then addplantillas_proxyFor herchconfiguration file (~/.tsh/config/config.yamlor globally/etc/tsh.yaml).

plantillas_proxy:- Model: '^(\w+)\.(sheet1\.example\.com):([0-9]+)$' Lawyer: "$ 2:443"

tsh-Proxy ssh -J {{Proxy}}will attempt to match the host server address%h:%pwith the configured templates. If there is a match, the hop proxy address{{Lawyer}}is replaced by the templateLawyerfield and host server address%h:%pis replaced by the templatehostfield is defined.

campo	description
`model`	(Required) Regular expression specifying the address of the host server`%h:%p`is paired against.
`Lawyer`	(Required) Address of the proxy service to use for the proxy hop. You can refer to the regular expression capturing groups in`model`(Physical education.,`$ 1`Ö`$ 2`).
`host`	(Optional) Host server address to connect to. You can refer to the regular expression capturing groups in`model`(Physical education.,`$ 1`Ö`$ 2`). Standards are complete host specifications`%h:%p`.

configuration example

plantillas_proxy:- Model: '^(\w+)\.(sheet1\.example\.com):([0-9]+)$' Lawyer: "$ 2:443"- Model: '^(\w+)\.(sheet2\.example\.com):([0-9]+)$' Lawyer: "$ 2:3080" Host: "$1:$3"- Model: '(\w+(\.\w+)*)\.(Example\.com):([0-9]+)$' Lawyer: "hoja1.ejemplo.com:443" Host: "$ 1:22"Data a context Above, a Next Domain or associate one a Es`nodo-1.hoja1.ejemplo.com:3022` over a Lawyer service `hoja1.ejemplo.com:443`:```CodePS sch [email protected]

The following command connects to Nodeit-1:3022via proxy servicehoja2.ejemplo.com:3080:

sch[email protected]

The last model can be used to connect to openssh hosts with their own FQDN. For example, you can connect to the hostabresh.external.com:22via proxy servicehoja1.ejemplo.com:443with the following command:

sch[email protected]

multiple clusters

If you switch between multiple teleport proxies, you'll need to run them againtsh-configfor each to generate the cluster-specific configuration.

If trusted clusters are added or removed, be sure to rerun them as welltsh-configand replace the old settings.

Step 4/4. connect to yours`sshd`host

After adding the new text to the OpenSSH client configuration file, you can log in to yoursshdHost with the previously generated configuration.

First, set the environment variables to the address of your teleport cluster, the username you use to log in to yoursshdhost and port of yoursshdHost you use for SSH traffic:

Check out the available logins you can use to access your sshd host
Status tsh | grep logins
Logins: ubuntu, root
USER=free
CLUSTER=teleport.example.com
Porto=22

Then SSH into your remote host:

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

This establishes a connection to the node.nodo1in your teleport group. This name does not need to be resolved via DNS as the connection is routed through your teleport proxy service.

By default, the OpenSSH client configuration is generated bytsh-configtells the teleport proxy service to dial up port 3022 from a node in your teleport cluster. This works if the node's SSH service is listening on port 3022 and means you can connect to the Teleport SSH service using your OpenSSH client.

When a Teleport node joins a cluster, the node creates a reverse tunnel to the cluster proxy service. When running aschcommand to access a host in your Teleport cluster using the configuration we generated, the TeleportProxy service will try to connect to the host through this reverse tunnel, and if that fails, try dialing the address directly.

In our case thesshdThe host does not teleport, so there is no reverse tunnel. Instead, the proxy service connects directly on the host's SSH port.

You can log in to a host on a trusted cluster by inserting the cluster name between the node name and the teleport root cluster name:

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

Use

Teleport uses OpenSSH certificates instead of keys. When you connect to a remote host, OpenSSH checks if the host address is under thedirectorsOpenSSH certificate section. Typically, this is a fully qualified domain name rather than an IP address.

Revoke an SSH certificate

Run to revoke the current teleport CA and generate a new oneTctl authentication rotation. Unless you have heavily automated your infrastructure, we recommend proceeding with caution as this will invalidate the user and host CAs, which means the new CAs will have to be re-exported to each OpenSSH-based machineTctl authentication exportas before.

Using Teleport with OpenSSH | teleport documents (2023)

previous requirements

Step 1/4. settingssshdconfie no CA teleport

Step 2/4. Configure host authentication

Make sure your user has the correct permissions

Issue a host certificate

Step 3/4. Generate an SSH client configuration

Proxy-Hop

Proxy Templates

configuration example

Step 4/4. connect to yourssshdhost

Revoke an SSH certificate

Videos

Step 1/4. settings`sshd`confie no CA teleport

Step 4/4. connect to yours`sshd`host