Skip to main content
Version: 14.x

Deploying Machine ID on Azure

In this guide, you will install Machine ID's agent, tbot on an Azure VM. The bot will be configured to use the azure delegated joining method to authenticate to your Teleport cluster. This eliminates the need for long-lived secrets.

On the Azure platform, virtual machines can be assigned a managed identity. The Azure platform will then make available to the virtual machine an attested data document and JWT that allows the virtual machine to act as this identity. This identity can be validated by a third party by attempting to use this token to fetch it's own identity from the Azure identity service.

The azure join method instructs the bot to use this attested data document and JWT to prove its identity to the Teleport Auth Server. This allows joining to occur without the use of a long-lived secret.

Prerequisites​

  • A running Teleport cluster version 14.3.33 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example: 
    $ tsh login --proxy=teleport.example.com --user=email@example.com
    $ tctl status
    # Cluster  teleport.example.com
    # Version  14.3.33
    # 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.
  • An Azure managed identity with a role granting the Microsoft.Compute/virtualMachines/read permission. You will need to know the UID of this identity.
  • An Azure VM you wish to install Machine ID onto with the managed identity configured as a user-assigned managed identity.

Step 1/4. Install tbot​

This step is completed on the Azure VM.

First, tbot needs to be installed on the VM that you wish to use Machine ID on.

Download and install the appropriate Teleport package for your platform:

Select an edition, then follow the instructions for that edition to install Teleport.

The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

$ curl https://cdn.teleport.dev/install-v14.3.33.sh | bash -s 14.3.33

Step 2/4. Create a join token, role and bot user​

This step is completed on your local machine.

Now, a role must be created that will be encoded into the credentials output by tbot. This role will specify what the credentials will grant access to. For now, this role will be "empty" - the access guides you complete after this platform guide will instruct you to modify this role to grant the correct privileges.

Create bot-role.yaml:

kind: role
version: v5
metadata:
  name: example-bot
spec:
  allow: {}
  deny: {}
  options: {}

Use tctl to apply this file:

$ tctl create -f bot-role.yaml

Create bot-token.yaml:

kind: token
version: v2
metadata:
  # name will be specified in the `tbot` to use this token
  name: example-bot
spec:
  roles: [Bot]
  # bot_name will match the name of the bot created later in this guide.
  bot_name: example
  join_method: azure
  azure:
    allow:
      # subscription should be the UID of an Azure subscription. Only VMs within
      # this subscription will be able to join.
    - subscription: 11111111-1111-1111-1111-111111111111
      # resource_groups allows joining to be restricted to VMs in a specific
      # resource group. It can be omitted to allow joining from any VM within
      # a subscription.
      resource_groups: ["group1"]

Replace:

  • 11111111-1111-1111-1111-111111111111 with the UID of your Azure subscription
  • group1 with the name of the resource group that the VM resides within or omit this entirely to allow joining from any VM within the subscription

Use tctl to apply this file:

$ tctl create -f bot-token.yaml

Create the bot, specifying the token and role that you have created:

$ tctl bots add example --token example-bot --roles example-bot

Step 3/4. Configure tbot​

This step is completed on the Azure VM.

Create /etc/tbot.yaml:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: azure
  token: example-bot
  azure :
    client_id: 22222222-2222-2222-2222-222222222222
storage:
  type: memory
# outputs will be filled in during the completion of an access guide.
outputs: []

Replace:

  • example.teleport.sh:443 with the address of your Teleport Proxy or Auth Server. Prefer using the address of a Teleport Proxy.
  • 22222222-2222-2222-2222-222222222222 with the ID of the Azure managed identity that has been assigned to the VM.
  • example-bot with the name of the token you created in the second step.

Now, you must decide if you want to run tbot as a daemon or in one-shot mode.

In daemon mode, tbot runs continually, renewing the short-lived credentials for the configured outputs on a fixed interval. This is often combined with a service manager (such as systemd) in order to run tbot in the background. This is the default behaviour of tbot.

In one-shot mode, tbot generates short-lived credentials and then exits. This is useful when combining tbot with scripting (such as in CI/CD) as it allows further steps to be dependent on tbot having succeeded. It is important to note that the credentials will expire if not renewed and to ensure that the TTL for the certificates is long enough to cover the length of the CI/CD job.

Configuring tbot as a daemon​

By default, tbot will run in daemon mode. However, this must then be configured as a service within the service manager on the Linux host. The service manager will start tbot on boot and ensure it is restarted if it fails. For this guide, systemd will be demonstrated but tbot should be compatible with all common alternatives.

Create a systemd unit file /etc/systemd/system/tbot.service:

[Unit]
Description=Teleport Machine ID Service
After=network.target

[Service]
Type=simple
User=teleport
Group=teleport
Restart=always
RestartSec=5
Environment="TELEPORT_ANONYMOUS_TELEMETRY=1"
ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/tbot.pid
LimitNOFILE=524288

[Install]
WantedBy=multi-user.target

Ensure that you replace:

  • teleport with the name of Linux user you wish to run tbot as.
  • /etc/tbot.yaml with the path to the configuration file you have created

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.

Next, enable the service so that it will start on boot and then start the service:

$ sudo systemctl daemon-reload
$ sudo systemctl enable tbot
$ sudo systemctl start tbot

Check the service has started successfully:

$ sudo systemctl status tbot

Configuring tbot for one-shot mode​

To use tbot in one-shot mode, modify /etc/tbot.yaml to add oneshot: true:

version: v2
oneshot: true
auth_server: ...

Now, you should test your tbot configuration. When started, several log messages will be emitted before it exits with status 0:

$ export TELEPORT_ANONYMOUS_TELEMETRY=1
$ tbot start -c /etc/tbot.yaml

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.

Step 4/4. Configure outputs​

You have now prepared the base configuration for tbot. At this point, it identifies itself to the Teleport cluster and renews its own credentials but does not output any credentials for other applications to use.

Follow one of the access guides to configure an output that meets your access needs.

Next steps​