Fork me on GitHub

Teleport

Machine ID Getting Started Guide

Improve

In this getting started guide, you will configure Machine ID to issue certificates that enable a bot user to connect to a remote host.

Here's an overview of what you will do:

  1. Download and install tbot 11.3.2 on the host that will run Machine ID.
  2. Create a bot user.
  3. Start Machine ID.
  4. Use certificates issued by Machine ID to connect to a remote machine.

Prerequisites

  • A host that you wish to assign an identity to using Machine ID.
  • A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.

  • The tctl admin tool and tsh client tool version >= 11.3.2.

    tctl version

    Teleport v11.3.2 go1.19

    tsh version

    Teleport v11.3.2 go1.19

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 11.3.2, which you can download by visiting the customer portal.

    tctl version

    Teleport v11.3.2 go1.19

    tsh version

    Teleport v11.3.2 go1.19

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 11.2.1. To download these tools, visit the Downloads page.

    tctl version

    Teleport v11.2.1 go1.19

    tsh version

    Teleport v11.2.1 go1.19

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 11.3.2

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 11.2.1

CA pin sha256:sha-hash-here

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

Machine ID and TLS Routing

TLS Routing support was added to Machine ID in Teleport 9.3. For earlier versions, the Teleport Proxy Server will need to be configured with a dedicated SSH listener.

version: v1
proxy_service:
  enabled: "yes"
  listen_addr: "0.0.0.0:3023"
  ...

Step 1/4. Download and install Teleport 11.3.2

In this step, you will be downloading and installing Teleport binaries onto the machine you wish to assign an identity to.

Each Teleport package hosted on our downloads page ships with several useful binaries, including teleport, tctl, tsh, and tbot:

  • teleport is the daemon used to initialize a Teleport cluster; this binary is not used in this guide
  • tctl is the administrative tool you will use to create the bot user (step 1/4)
  • tsh is the client tool you will use to log in to the Teleport Cluster (steps 2/4 and 4/4)
  • tbot is the Machine ID tool you will use to associate a bot user with a machine (step 3/4)

Machine ID is available starting from the Teleport 9.0.0 release.

Download the appropriate Teleport package for your platform:

Next, use the appropriate commands for your environment to install your package.

Teleport Edition

Add the Teleport repository to your repository list:

Download Teleport's PGP public key

sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc

Source variables about OS version

source /etc/os-release

Add the Teleport APT repository for v11. You'll need to update this

file for each major release of Teleport.

Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67

echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v11" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport

Source variables about OS version

source /etc/os-release

Add the Teleport YUM repository for v11. You'll need to update this

file for each major release of Teleport.

Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID'

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153

sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v11/teleport.repo")
sudo yum install teleport

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Optional: Use DNF on newer distributions

$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

$ sudo dnf install teleport

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

curl https://get.gravitational.com/teleport-v11.3.2-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-v11.3.2-linux-
-bin.tar.gz
shasum -a 256 teleport-v11.3.2-linux-
-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-v11.3.2-linux-
-bin.tar.gz
cd teleport
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_11.3.2_
.deb

Selecting previously unselected package teleport-ent.

(Reading database ... 30810 files and directories currently installed.)

Preparing to unpack teleport-ent_11.3.2_$SYSTEM_ARCH.deb ...

Unpacking teleport-ent 11.3.2 ...

Setting up teleport-ent 11.3.2 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-11.3.2.
.rpm

warning: teleport-ent-11.3.2.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.3.2-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v11.3.2-linux-
-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.2-linux-
-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v11.3.2-linux-
-bin.tar.gz
cd teleport-ent
sudo ./install

For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

curl https://get.gravitational.com/teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz
cd teleport-ent
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_11.2.1_
.deb

Selecting previously unselected package teleport-ent.

(Reading database ... 30810 files and directories currently installed.)

Preparing to unpack teleport-ent_11.2.1_$SYSTEM_ARCH.deb ...

Unpacking teleport-ent 11.2.1 ...

Setting up teleport-ent 11.2.1 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-11.2.1.
.rpm

warning: teleport-ent-11.2.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.2.1-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v11.2.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-ent-v11.2.1-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v11.2.1-linux-amd64-bin.tar.gz
cd teleport-ent
sudo ./install

Before installing a teleport binary with a version besides v11, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

When running multiple teleport binaries within a cluster, the following rules apply:

  • Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
  • Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
  • Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

Step 2/4. Create a bot user

Before you create a bot user, you need to determine which role(s) you want to assign to it. You can use the tctl command below to examine what roles exist on your system.

Connect to the Teleport Auth Server and use tctl to examine what roles exist on your system.

tctl get roles --format=text

You will see something like the output below on a fresh install of Teleport with the default roles—your cluster may have different roles. In this example, let's assume you want to give the bot the access role to allow it to connect to machines within your cluster.

Role    Allowed to login as                           Node Labels Access to resources
------- --------------------------------------------- ----------- ----------------------------------------
access  {{internal.logins}}                           <all nodes> event:list,read,session:read,list
auditor no-login-6566121f-b602-47f1-a118-c9c618ee5aec             session:list,read,event:list,read
editor                                                            user:list,create,read,update,delete,...

Machine ID can join with a token or the IAM Method on AWS.

Assuming that you are using the default access role, ensure that you use the --logins flag when adding your bot to specify the SSH logins that you wish to allow the bot to access on hosts. For our example, we will be using root.

tctl bots add robot --roles=access --logins=root

First, create an IAM method token that specifies the AWS account from which the bot can join. Create the below file as iam-token.yaml then run tctl create -f iam-token.yaml.

kind: token
version: v2
metadata:
  # The token name is not a secret because instances must prove that they are
  # running in your AWS account to use this token.
  name: iam-token
  # Set a long expiry time for how long you want to support IAM method for
  # joining. It is safe to set this value to a very long time.
  expires: "3000-01-01T00:00:00Z"
spec:
  # Only allow bots to join using this token.
  roles: [Bot]

  # Set the join method to be IAM.
  join_method: iam

  # Define the name of the bot that will be allowed to use this token.
  bot_name: robot

  allow:
  # Restrict the AWS account and (optionally) ARN that can use this token.
  # This information can be obtained from running the
  # "aws sts get-caller-identity" command from the CLI.
  - aws_account: "111111111111"
    aws_arn: "arn:aws:sts::111111111111:assumed-role/teleport-bot-role/i-*"

Next, create the bot user.

$ tctl bots add robot --token=iam-token --roles=access --logins=root

Step 3/4. Start Machine ID

Now start Machine ID using the tbot binary. The tbot start command will start running Machine ID in a loop, writing renewable certificates to /var/lib/teleport/bot and the short-lived certificates your application will use to /opt/machine-id.

In a production environment you will want to run Machine ID in the background using a service manager like systemd. However, in this guide you will run it in the foreground to better understand how it works.

tbot start \ --data-dir=/var/lib/teleport/bot \ --destination-dir=/opt/machine-id \ --token=abcd123-insecure-do-not-use-this \ --join-method=token \ --ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \ --auth-server=auth.example.com:3025
tbot start \ --data-dir=/var/lib/teleport/bot \ --destination-dir=/opt/machine-id \ --token=iam-token \ --join-method=iam \ --ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \ --auth-server=auth.example.com:3025

Replace the following fields with values from your own cluster.

  • token is the token output by the tctl bots add command or the name of your IAM method token.
  • ca-pin is the CA Pin for your Teleport cluster, and is output by the tctl bots add command.
  • destination-dir is where Machine ID writes user certificates that can be used by applications and tools.
  • data-dir is where Machine ID writes its private data, including its own short-lived renewable certificates. These should not be used by applications and tools.
  • auth-server is the address of your Teleport Auth Server, for example auth.example.com:3025. If your Machine ID host is in a different network than your Auth Server, use the public web address of your Proxy Service instead (e.g., auth.example.com:443).

Now that Machine ID has successfully started, let's investigate the /opt/machine-id directory to see what was written to disk.

tree /opt/machine-id

machine-id

├── key

├── key.pub

├── known_hosts

├── ssh_config

├── sshcacerts

├── sshcert

├── tlscacerts

└── tlscert

0 directories, 8 files

This directory contains private key material in the key.* files, SSH certificates in the ssh* files, X.509 certificates in the tls* files, and OpenSSH configuration in the ssh_config and known_hosts files to make it easy to integrate Machine ID with external applications and tools.

Step 4/4. Use certificates issued by Machine ID

To use Machine ID, find a host that you want to connect to within your cluster using tsh ls. You might see output like the following on your system.

tsh ls

Node Name Address Labels

--------- -------------- -----------------------------

node-name 127.0.0.1:3022 arch=x86_64,group=api-servers

When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to display Nodes in the Web UI or via tsh ls), it only returns the Nodes that the current user is authorized to view.

For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:

  • None of the user's roles contain a deny rule that matches the Node's labels.
  • None of the user's roles contain a deny rule that matches the user's login.
  • At least one of the user's roles contains an allow rule that matches the Node's labels.
  • At least one of the user's roles contains an allow rule that matches the user's login.

If you are not seeing Nodes when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Teleport Access Controls Reference.

To use Machine ID with the OpenSSH integration, run the following command to connect to node-name within cluster example.com.

ssh -F /opt/machine-id/ssh_config [email protected]
Roles must have logins defined

The below error can occur when the bot does not have permission to log in to a node as the requested user:

ssh -F /opt/machine-id/ssh_config [email protected]

[email protected]: Permission denied (publickey).

kex_exchange_identification: Connection closed by remote host

This can happen in two circumstances:

  • The user you are trying to log in as is not specified under logins in the role you are using
  • If you have used --logins when creating the bot user, the role the bot is impersonating does not have the {{ internal.logins }} variable specified.

If you have been following along with the access role, do the following.

  • Export the role by running tctl get roles/access > access.yaml
  • Edit the logins field in access.yaml
  • Update the role by running tctl create -f access.yaml

Now you can replace any invocations of ssh with the above command to provide your applications and tools a machine identity that can be rotated, audited, and controlled with all the familiar Teleport access controls.

Next Steps

Now that you know how to create a bot user to access resources in your infrastructure, dive deeper into the topics relevant to your Machine ID use-case, for example: