Fork me on GitHub

Teleport

Machine ID with Application Access

Improve

In this guide, we will demonstrate 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

You will need a running Teleport cluster version 10.1.0 or later.

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 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 10.3.1

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 10.2.2

CA pin sha256:sha-hash-here

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

Lastly, 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 necessary tbot 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:

auth_server: "teleport.example.com:443"
onboarding:
  join_method: "token"
  token: "abcd123-insecure-do-not-use-this"
  ca_pins:
  - "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678"
storage:
  directory: /var/lib/teleport/bot
destinations:
  - directory: /opt/machine-id
    app: 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 destination directory 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

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
ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/machine-id.pid
LimitNOFILE=8192

[Install]
WantedBy=multi-user.target

Finally, run the following commands to start Machine ID:

sudo systemctl daemon-reload
sudo systemctl start machine-id
sudo 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 app

Jul 29 12:34:56 example tbot[29177]: INFO [TBOT] Generated identity for app {"grafana-example"} tbot/renew.go:429

Given the 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.

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.

Proxy Note

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:

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 tls config template in tbot.yaml:

destinations:
  - directory: /opt/machine-id
    app: grafana-example

    configs:
      - tls

This will generate tls.crt and tls.key inside /opt/machine-id with identical content to the certificate files listed above.

Config Templates

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.