Machine ID with Application Access

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

• 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.
• Make sure you can 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  13.0.3
  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.

• 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

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/bot
sudo chown teleport:teleport /var/lib/teleport/bot
Allow 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-id
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.

tbot proxy --destination-dir=/opt/machine-id --proxy=teleport.example.com:443 app --port=1234 grafana-example

curl --user admin:admin http://localhost:1234/api/users

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.

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.

More information about TELEPORT_ANONYMOUS_TELEMETRY.