In this getting started guide, you will use Machine ID to create a bot user for a machine and use that identity to connect to said machine.
Here's an overview of what you will do:
- Download and install Teleport 9.2.4
- Create a bot user
- Start Machine ID
- Use certificates issued by Machine ID to connect to a remote machine
Prerequisites
Before using Machine ID, you will need an existing Teleport cluster or a Teleport Cloud account.
If you have not set up a Teleport cluster before, follow the Getting started guide.
TLS Routing support will be added to Machine ID in Teleport 9.3. Until that time, 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 9.2.4
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 guidetctl
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 from our
downloads page.
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.
tctl bots add robot --roles=access
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
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=00000000000000000000000000000000 \ --join-method=token \ --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ --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:1111111111111111111111111111111111111111111111111111111111111111 \ --auth-server=auth.example.com:3025
Replace the following fields with values from your own cluster.
token
is the token output by thetctl bots add
command or the name of your IAM method tokenca-pin
is the CA Pin for your Teleport cluster, and is output by thetctl bots add
commanddestination-dir
is where Machine ID writes renewable certificates, which are only used by Machine ID and should not be used by applications and toolsdata-dir
is where Machine ID writes the short-lived certificate. This certificate should be used by applications and toolsauth-server
is the address of your Teleport Auth Server, for exampleauth.example.com:3025
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-idmachine-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 lsNode Name Address Labels
--------- -------------- -----------------------------
node-name 127.0.0.1:3022 arch=x86_64,group=api-servers
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]
If you see the below error, it means the user you are trying to log in as is
not specified under logins
in the role you are using.
ssh -F /opt/machine-id/ssh_config [email protected][email protected]: Permission denied (publickey).
kex_exchange_identification: Connection closed by remote host
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 inaccess.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: