# Deploying tbot on Azure In this guide, you will install Machine & Workload Identity'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. ## How it works 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 its 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 Service. This allows joining to occur without the use of a long-lived secret. ## Prerequisites - A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * 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. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 19.0.0-dev 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 & Workload Identity onto with the managed identity configured as a user-assigned managed identity. ## Step 1/5. 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 & Workload Identity on. Download and install the appropriate Teleport package for your platform: To install a Teleport Agent on your Linux server: The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster. 1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://). 2. Run your cluster's install script: ``` $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash ``` ## Step 2/5. Create a Bot **This step is completed on your local machine.** Next, you need to create a Bot. A Bot is a Teleport identity for a machine or group of machines. Like users, bots have a set of roles and traits which define what they can access. Create `bot.yaml`: ``` kind: bot version: v1 metadata: # name is a unique identifier for the Bot in the cluster. name: example spec: # roles is a list of roles to grant to the Bot. Don't worry if you don't know # what roles you need to specify here, the Access Guides will walk you through # creating and assigning roles to the already created Bot. roles: [] ``` Make sure you replace `example` with a unique, descriptive name for your Bot. Use `tctl` to apply this file: ``` $ tctl create bot.yaml ``` ## Step 3/5. Create a join token **This step is completed on your local machine.** 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 should match the name of the bot created earlier 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 - `example` with the name of the bot you created in the second step - `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 ``` ## Step 4/5. 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 # services will be filled in during the completion of an access guide. services: [] ``` Replace: - `example.teleport.sh:443` with the address of your Teleport Proxy or Auth Service. 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 third 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. **If tbot was installed using the Teleport install script or `teleport-update` command, the `tbot` systemd service is automatically created for you.** After `tbot.yaml` is created, enable and start the service: ``` $ sudo systemctl enable tbot --now ``` Check the service has started successfully: ``` $ sudo systemctl status tbot ``` Service properties like `User` and `Group` may be configured using `systemctl edit tbot`. **If tbot was installed manually, service configuration will need to be performed manually as well.** For this guide, systemd will be demonstrated but `tbot` should be compatible with all common alternatives. Use `tbot install systemd` to generate a systemd service file: ``` $ sudo tbot install systemd \ --write \ --config /etc/tbot.yaml \ --user teleport \ --group teleport \ --pid-file /run/tbot.pid \ --anonymous-telemetry ``` 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. - `/run/tbot.pid` with a path that the user configured for `tbot` has write access to. By default, `tbot` writes its PID file to `/run/tbot.pid`. You can omit `--write` to print the systemd service file to the console instead of writing it to disk. `--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 --now ``` 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 proxy_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 5/5. Configure services 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](https://goteleport.com/docs/machine-workload-identity/access-guides.md) to configure a service that meets your access needs. ## Next steps - Follow the [access guides](https://goteleport.com/docs/machine-workload-identity/access-guides.md) to finish configuring `tbot` for your environment. - Read the [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available configuration options. - [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](https://goteleport.com/docs/reference/machine-workload-identity/telemetry.md)