Machine ID with Application Access

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

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport 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 run tctl commands on your administrative workstation using your current credentials. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  14.0.0
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl 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 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:

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/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 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.

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

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.