Skip to main content
Version: 17.x

Deploying Machine ID on Azure DevOps

Report an issue with this page

In this guide, you will configure Machine ID'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 ID 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 finely-grained access control.

Prerequisites​

  • A running Teleport cluster version 17.5.2 or above. If you do not have one, read Get Started with Teleport.

  • The tctl and tsh clients.

    Details

    Installing tctl and tsh clients

    Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

    curl -O https://cdn.teleport.dev/teleport-17.5.2.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.

    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/ping and use a JSON query tool to obtain your cluster version:

    curl https://example.teleport.sh/v1/webapi/ping | jq -r '.server_version'
    17.5.2
  • 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  17.5.2
    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.shOrganization 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.

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
# 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 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 second 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: |
    wget https://cdn.teleport.dev/teleport-v17.5.2-linux-amd64-bin.tar.gz
    tar -xvf teleport-v17.5.2-linux-amd64-bin.tar.gz
  displayName: 'Download and extract Teleport'
- script: TELEPORT_ANONYMOUS_TELEMETRY=1 ./teleport/tbot start -c 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.

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

Further steps​