Fork me on GitHub

Teleport

Machine ID with Application Access

  • 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 and tsh 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 and tsh 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 and tsh client tool version >= 14.0.0.

    You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

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.

Cloud is not available for Teleport v.
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.

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:

Cloud is not available for Teleport v.
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.

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.

More information about TELEPORT_ANONYMOUS_TELEMETRY.