# Deploying tbot on Azure DevOps In this guide, you will configure Machine & Workload Identity's agent, `tbot`, to run within a Azure DevOps pipeline run. The bot will be configured to use the `azure_devops` delegated joining method to eliminate the need for long-lived secrets. ## How it works The `azure_devops` join method is a secure way for Machine & Workload Identity bots to authenticate with the Teleport Auth Service without using any shared secrets. Instead, it makes use of an OpenID Connect token that Azure DevOps provides via an API to the pipeline job. This token is sent to the Teleport Auth Service, and assuming it has been configured to trust Azure DevOps's identity provider and all identity assertions match, the authentication attempt will succeed. This mitigates the risk of long-lived secrets such as passwords or SSH private keys being exfiltrated from your Azure DevOps organization and provides many of the other benefits of Teleport such as auditing and fine-grained access control. ## Prerequisites - A running Teleport (v17.5.1 or higher) 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 18.7.3 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. ## Step 1/5. Determine your Azure DevOps organization ID Before we can grant access to a `tbot` running within an Azure DevOps pipeline, we must determine the ID of the Azure DevOps organization that the pipeline runs within. This will be used later to configure the join token. To determine the organization ID, add a step to a new or existing pipeline that exists within the organization that echoes the `System.CollectionId` variable. For example: ``` trigger: - main pool: vmImage: ubuntu-latest steps: - script: | echo "Organization ID: $(System.CollectionId)" ``` Run this pipeline, and inspect the output of the step. You should see your organization ID printed in the logs, similar to the following: ``` ========================== Starting Command Output =========================== /usr/bin/bash --noprofile --norc /home/vsts/work/_temp/c4fdfbf7-6cd4-4737-a2a2-16702d201449.sh Organization ID: 0ca3ddd9-0000-1111-2222-example58665 ``` Record this organization ID as you will need it later: organization-id ## Step 2/5. Create a Bot 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 To allow the Azure DevOps pipeline to authenticate to your Teleport cluster, you'll first need to create a join token. An Azure DevOps join token contains allow rules that describe which pipelines can use that token in order to join the Teleport cluster. A rule can contain multiple fields, and any pipeline that matches all the fields within a single rule is granted access. In this example, you will create a token with a rule that grants access to any Azure DevOps pipeline within a specific project. Create a file named `bot-token.yaml`, assigning my-project to the name of your Azure DevOps project: ``` kind: token version: v2 metadata: name: example-bot spec: roles: [Bot] join_method: azure_devops bot_name: example azure_devops: organization_id: organization-id allow: - project_name: my-project ``` Replace: - `example-bot` with a meaningful name that describes the token. - `example` with the name of the bot you created in Step 2. - `my-project` with the name of the Azure DevOps project that you want to allow access to the bot. You can find a full list of the token configuration options for Azure DevOps joining on the [join methods reference page.](https://goteleport.com/docs/reference/deployment/join-methods.md#azure-devops-azure_devops) Apply this to your Teleport cluster using `tctl`: ``` $ tctl create -f bot-token.yaml ``` ## Step 4/5. Configure an Azure DevOps pipeline With the bot and join token created, you can now configure an Azure DevOps pipeline that sets up `tbot` to use these. To configure `tbot`, a YAML file will be used. In this example, we'll store the configuration within the repository itself but this could be generated by the CI pipeline itself. Create `tbot.yaml` within your repository: ``` version: v2 proxy_server: example.teleport.sh:443 onboarding: join_method: azure_devops token: example-bot oneshot: true storage: type: memory # services will be filled in during the completion of an access guide. services: [] ``` Replace: - example.teleport.sh with the address of your Teleport Proxy Service or Auth Service. Prefer using the address of the Teleport Proxy Service. - `example-bot` with the name of the token you created in the third step Now you'll modify your Azure DevOps pipeline to install `tbot` and run it with the configuration you just created. In production, rather than installing `tbot` in each pipeline run, you may wish to build a container image that contains `tbot` and other dependencies, and run your pipeline within a container based on that image. Create or modify an existing pipeline with the following YAML: ``` trigger: - main pool: vmImage: ubuntu-latest steps: - script: | curl "https://example.teleport.sh:443/scripts/install.sh" | sudo bash tbot start -c tbot.yaml displayName: 'Install Teleport and start tbot' env: SYSTEM_ACCESSTOKEN: $(System.AccessToken) TELEPORT_ANONYMOUS_TELEMETRY: 1 ``` Replace example.teleport.sh with the address of your Teleport Proxy Service. Note the inclusion of the `SYSTEM_ACCESSTOKEN` environment variable. This variable must be populated in any step where `tbot` is run. `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. Commit and push these two files to the repository. Check the status of your Azure DevOps pipeline run. If everything is configured correctly, you should see `tbot` successfully start, join the cluster, and then exit. ## 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. ## Further steps - For more information about the Azure DevOps join method, read the [join method reference page.](https://goteleport.com/docs/reference/deployment/join-methods.md#azure-devops-azure_devops) - 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)