
Teleport
Machine ID with Application Access
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise
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.
This guide demonstrates how to configure an automated service to use Machine ID to access a web application protected by Teleport.
With Machine ID, Teleport issues short-lived certificates, tied to a machine identity, that can be rotated, audited, and managed with the same access controls that Teleport provides for human users.
Prerequisites
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.0.See Installation for details.
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 13.3.9.You can download these tools from the Cloud Downloads page.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
- If you have not already connected your application to Teleport, follow the Application Access Getting Started Guide.
- If you're not already familiar with Machine ID, follow the
Getting Started Guide to familiarize yourself with
Machine ID. You'll also need
tctl
access to initially configure the bot. - To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions. - Ensure the
tbot
binary is installed on your Machine ID client system. The client system is any system from which you want to access your Teleport cluster and the resources it protects from an automated service. Refer to our Installation guide for instructions on installing Teleport, which includes the necessarytbot
binary.
Step 1/3. Create a Machine ID bot and assign permissions
In this example you'll start by creating a bot named "example" and assign it a role granting access to some set of apps by label.
First, on a node with tctl
access (such as your local machine), create a file
named role.yaml
with the following content:
kind: role
metadata:
name: machine-id-app-role
version: v5
spec:
allow:
app_labels:
'*': '*'
This role allows access to all apps. You might consider restricting the label selector here, especially for production deployments.
Once finished, create the role on your Teleport cluster:
tctl create -f role.yaml
Step 2/3. Configure and start Machine ID
First, on a node with tctl
access, create a new Machine ID bot using the role
created in the previous step:
tctl bots add example --roles=machine-id-app-role
The creates a bot named example
with permissions to access the apps as you
configured above. Be sure to note the bot join token and CA PIN.
Next, on the bot node, create a Machine ID configuration file at
/etc/tbot.yaml
:
version: v2
auth_server: "example.teleport.sh:443"
onboarding:
join_method: "token"
token: "00000000000000000000000000000000"
ca_pins:
- "sha256:1111111111111111111111111111111111111111111111111111111111111111"
storage:
type: directory
path: /var/lib/teleport/bot
outputs:
- type: application
destination:
type: directory
path: /opt/machine-id
app_name: grafana-example
Be sure to configure the token
and ca_pins
fields to match the output from
tctl bots add ...
, and set app
to match the desired name as shown in
tsh apps ls
. For this example, we're using the grafana-example
app.
Machine ID also allows you to use Linux ACLs to control access to certificates on disk. You will use this to ensure only your automated service has access to the short-lived certificates Machine ID uses.
We'll work with the assumption you will be running Machine ID as the Linux user
teleport
and your automated service as the Linux user app
. Create and
initialize the output destination by running this tbot init
command either
as root
or as the teleport
user:
tbot init \ -c /etc/tbot.yaml \ --init-dir=/opt/machine-id \ --bot-user=teleport \ --owner=teleport:teleport \ --reader-user=app
Create the bot data directory and grant permissions to access it to the Linux user (in our example, teleport
) which tbot
will run as.
Make the bot directory and assign ownership to teleport user
sudo mkdir -p /var/lib/teleport/botsudo chown teleport:teleport /var/lib/teleport/botAllow teleport user to open directory
sudo chmod +x /var/lib/teleport /var/lib/teleport/bot
Next, you will use systemd to run Machine ID in the background on your
bot node. Create a systemd.unit file at
/etc/systemd/system/machine-id.service
:
[Unit]
Description=Teleport Machine ID Service
After=network.target
[Service]
Type=simple
User=teleport
Group=teleport
Restart=on-failure
Environment="TELEPORT_ANONYMOUS_TELEMETRY=1"
ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/machine-id.pid
LimitNOFILE=524288
[Install]
WantedBy=multi-user.target
TELEPORT_ANONYMOUS_TELEMETRY
enables the submission of anonymous usage
telemetry. This helps us shape the future development of tbot
. You can disable
this by omitting this.
Finally, run the following commands to start Machine ID:
sudo systemctl enable machine-idsudo systemctl start machine-idsudo systemctl status machine-id
Step 3/3. Connect to your web application with the Machine ID identity
With Machine ID up and running, there should be certificates in
/opt/machine-id
that your automated service will use to connect to your web
application. This can be verified by examining the tbot
log:
journalctl -u machine-id | grep -i appJul 29 12:34:56 example tbot[29177]: INFO [TBOT] Generated identity for app {"grafana-example"} tbot/renew.go:429
Given the output destination directory /opt/machine-id
, the following
certificate files can be used:
/opt/machine-id/tlscert
: the client TLS certificate/opt/machine-id/key
: the TLS certificate's private key
You may use these credentials with any client application that supports them.
Please use the latest version of Teleport Enterprise documentation.
The Teleport Proxy makes apps available via subdomains of its public web
address. Given an app named grafana-example
and a Teleport Proxy at
https://teleport.example.com:443
, the app may be accessed at
https://grafana-example.teleport.example.com:443
.
For example, to access the Grafana API using curl
:
curl --user admin:admin \ --cert /opt/machine-id/tlscert \ --key /opt/machine-id/key \ https://grafana-example.teleport.example.com/api/users
Note that in the example above, we include --user
to provide a local username
and password to our Grafana instance. This is not necessary if your application
either requires no additional authentication, or if you've configured
JWT authentication for your
app.
No CA certificate needs to be specified so long as your Teleport Proxy is configured with a valid wildcard CA from Let's Encrypt or another public certificate authority.
Note that if the certificates are invalid or otherwise misconfigured, clients will be redirected to the Teleport login page when attempting to access the app.
While it's usually best to access apps through the public Teleport Proxy
Service, it's also possible to open a local proxy to the app using
tbot proxy app ...
in situations where the Teleport Proxy Service's app endpoints are
unavailable:
Please use the latest version of Teleport Enterprise documentation.
tbot proxy --destination-dir=/opt/machine-id --proxy=teleport.example.com:443 app --port=1234 grafana-example
You may now connect to the app via a local proxy at http://localhost:1234
:
curl --user admin:admin http://localhost:1234/api/users
Note that any clients with access to localhost
may connect to this proxy
without additional authentication, so this should only be run in trusted
environments.
Troubleshooting
Client application requires certificates with standard extensions
If your automated service requires TLS certificates with a specific file
extension, you may also enable the specific_tls_naming
option for the output:
outputs:
- type: application
destination:
type: directory
path: /opt/machine-id
app_name: grafana-example
specific_tls_naming: true
This will generate tls.crt
and tls.key
inside /opt/machine-id
with identical content to the certificate files listed above.
The tls
configuration template is one of several supported template types;
refer to the Configuration Reference for a
list of all possible configuration templates.
Be sure to re-run tbot init ...
to configure permissions for the new file if
config templates are changed.
Clients are redirected to the Teleport login page
As with human users, scripted clients will be redirected to the Teleport login page when attempting to access an app through the Teleport Proxy Service without valid credentials.
Ensure the bot's certificates have not expired and that the client application has been configured to use both the client certificate and key.
Next steps
- Review the Access Controls Reference to learn about restricting which Applications and other Teleport resources your bot may access.
- Configure JWTs for your Application to remove the need for additional login credentials.