Skip to main content
Version: 14.x

Machine ID with Server Access

This version of the guide uses the v2 tbot configuration. This version is only supported by Teleport 14 and beyond. Change the selected version of the documentation to view the guide for previous Teleport versions.

Teleport protects and controls SSH access to servers. Machine ID can be used to grant machines secure, short-lived access to these servers.

In this guide, you will configure tbot to produce credentials that can be used to access a Linux server enrolled in Teleport. The guide will cover access using the Teleport CLI tsh as well as the OpenSSH client.

Prerequisites​

  • A running Teleport cluster version 14.3.33 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.

    Visit Installation for instructions on downloading tctl and tsh.

  • If you have not already connected your server to Teleport, follow the Server Access Getting Started Guide.
  • 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@example.com
    $ tctl status
    # Cluster  teleport.example.com
    # Version  14.3.33
    # 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.
  • tbot must already be installed and configured on the machine that will connect to Linux hosts with SSH. For more information, see the deployment guides.

Step 1/3. Configure RBAC​

First, Teleport must be configured to allow the credentials produced by the bot to connect to SSH servers in your infrastructure. In this example, access will be granted to all SSH nodes for the username root.

If you have followed an access guide, you will have created a role and granted the bot the ability to impersonate it already. This role just needs to have the additional privileges added to it.

Use tctl edit role/example-bot to add the following to the role:

spec:
  allow:
    # Allow login to the Linux user 'root'.
    logins: ['root']
    # Allow connection to any node. Adjust these labels to match only nodes
    # that ansible needs to access.
    node_labels:
      '*': '*'

You may also wish to adjust this to grant access to a user other than root depending on what commands will need to be executed with the credentials.

For production use, you should adjust node_labels to restrict this access to only the hosts that the bot will need to access. This is known as the principle of least privilege and limits the damage that exfiltrated credentials can do.

Step 2/3. Configure the tbot output​

Now, tbot needs to be configured with an output that will produce an SSH certificate and OpenSSH configuration. For this we use the identity output type.

Outputs must be configured with a destination. In this example, the directory destination will be used. This will write these credentials to a specified directory on disk. Ensure that this directory can be written to by the Linux user that tbot runs as, and that it can be read by the Linux user that needs to use SSH.

Modify your tbot configuration to add an identity output:

outputs:
- type: identity
  destination:
    type: directory
    # For this guide, /opt/machine-id is used as the destination directory.
    # You may wish to customize this. Multiple outputs cannot share the same
    # destination.
    path: /opt/machine-id

If operating tbot as a background service, restart it. If running tbot in one-shot mode, it must be executed before you attempt to use the credentials produced by tbot to connect to nodes via SSH.

Step 3/3. Using the output credentials​

Once tbot has been run or restarted, you should now see several files under /opt/machine-id:

  • identity: this is a bundle of credentials that can be used by tsh to authenticate.
  • ssh_config: this can be used with OpenSSH and other tools to configure them to use the Teleport Proxy Service with the correct credentials when making connections.
  • known_hosts: this contains the Teleport SSH host CAs and allows the SSH client to validate a host's certificate.
  • key-cert.pub: this is an SSH certificate signed by the Teleport SSH user CA.
  • key: this is the private key needed to use the SSH certificate.

These credentials can be used with Teleport's CLI tsh or with OpenSSH client tools like ssh and sftp.

Connecting using tsh​

To use tsh with a tbot identity output, the path to the identity file must be specified using the -i flag. In addition, --proxy must be used to specify the address of the Teleport Proxy Service that should be used when making connections.

In this example, tsh is used to connect to a node called my-host via the proxy example.teleport.sh:443 and to execute the command hostname:

$ tsh -i /opt/machine-id/identity --proxy example.teleport.sh:443 ssh root@my-host hostname
my-host

Connecting using OpenSSH​

To use OpenSSH with the identity output, the path to the ssh_config should be provided to ssh with the -F flag.

With the generated ssh_config you must append the name of the Teleport cluster to the name of the node - in this example, the command hostname is executed as root on the node my-host belonging to the cluster example.teleport.sh.

$ ssh -F /opt/machine-id/ssh_config root@my-host.example.teleport.sh hostname
my-host
warning

The ssh_config for OpenSSH requires that tsh is installed. This is necessary as tsh is used to make the OpenSSH client compatible with Teleport's port multiplexing.

Connecting using other tools​

To integrate with other SSH tools, first determine whether the ssh_config is compatible with them. This is the case for many tools such as Ansible and the guidance provided under "Connecting using OpenSSH" should be sufficient.

If you wish to integrate with Ansible, check out the Ansible-specific guide.

If your tool is not compatible with ssh_config, it may still be possible to configure it to use the credentials produced by Machine ID. It must support SSH client certificates and either ProxyCommand or ProxyJump functionality.

Next steps​