Skip to main content

Deploying Machine ID on Bitbucket Pipelines

In this guide, you will configure Machine ID's agent, tbot, to run within a Bitbucket Pipelines workflow. The bot will be configured to use the bitbucket delegated joining method to eliminate the need for long-lived secrets.

How it works

The bitbucket 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 Bitbucket Pipelines injects into the job environment.

This token is sent to the Teleport Auth Service, and assuming it has been configured to trust Bitbucket's identity provider and all identity assertions match, the authentication attempt will succeed.

Prerequisites

  • A running Teleport cluster version 16.4.12 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. For example:
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 16.4.12

    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.
  • A Bitbucket repository you can push to.

Step 1/5. Determine Bitbucket configuration

Bitbucket joining requires a number of configuration parameters that can be found in your repository settings. From the Bitbucket repository, navigate to "Repository settings", then in the sidebar under "Pipelines" select "OpenID Connect".

From this page, note the following values:

  • Identity provider URL (identity-provider-url)
  • Audience (audience)
  • Workspace UUID, including the braces (workspace-uuid)
  • Repository UUID, including the braces (repository-uuid)

Step 2/5. Create the Machine ID 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 the join token for Bitbucket Pipelines

In order to allow your Pipelines workflow to authenticate with your Teleport cluster, you'll first need to create a join token. These tokens set out criteria by which the Auth Service decides whether or not to allow a bot or node to join.

Create a file named bot-token.yaml, ensuring that you replace the identity_provider_url, audience, workspace_uuid, and repository_uuid with the values from Step 1.

kind: token
version: v2
metadata:
  name: example-bot
spec:
  roles: [Bot]
  join_method: bitbucket
  bot_name: example
  bitbucket:
    identity_provider_url: identity-provider-url
    audience: audience
    # allow specifies the rules by which the Auth Service determines if `tbot`
    # should be allowed to join.
    allow:
    - workspace_uuid: workspace-uuid
      repository_uuid: repository-uuid

Let's go over the token resource's fields in more detail:

  • metadata.name defines the name of the token. Note that this value will need to be used in other parts of the configuration later.
  • spec.bot_name is the name of the Machine ID bot that this token will grant access to. Note that this value will need to be used in other parts of the configuration later.
  • spec.roles defines which roles that this token will grant access to. The value of [Bot] states that this token grants access to a Machine ID bot.
  • spec.join_method defines the join method the token is applicable for. Since this guide only focuses on Bitbucket Pipelines, you will set this to to bitbucket.
  • spec.bitbucket.identity_provider_url is the identity provider URL shown in the Bitbucket repository settings, under Pipelines and OpenID Connect.
  • spec.bitbucket.audience is the audience value shown in the Bitbucket repository settings, under Pipelines and OpenID connect.
  • spec.bitbucket.allow is used to set rules for what Bitbucket Pipelines runs will be able to authenticate by using the token.

Refer to the token reference for a full list of valid fields.

Apply this to your Teleport cluster using tctl:

tctl create -f bot-token.yaml

Step 4/5. Configure a Bitbucket Pipelines workflow

With the bot and join token created, you can now configure a workflow that can authenticate to Teleport.

To configure tbot, a YAML file will be used. In this example we'll store this within the repository itself, but this could be generated or created by the CI pipeline itself.

Create tbot.yaml within your repository:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: bitbucket
  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. If connecting directly to an Auth Service, replace proxy_server: with auth_server:.
  • example-bot with the name of the token you created in the second step

Next, define a Pipelines workflow that downloads the tbot binary and starts it using the tbot.yaml configured above. This example workflow defines a "custom" pipeline that can be triggered manually from "Pipelines" or "Branches" views, but any type of workflow may be used:

image: atlassian/default-image:3

pipelines:
  custom:
    run-tbot:
      - step:
          oidc: true
          script:
            # Download and extract Teleport
            - wget https://cdn.teleport.dev/teleport-v16.4.12-linux-amd64-bin.tar.gz
            - tar -xvf teleport-v16.4.12-linux-amd64-bin.tar.gz

            # Run `tbot` in identity mode for SSH access
            - ./teleport/tbot start -c tbot.yaml

Once run, tbot will start and authenticate to Teleport. Note that at this point, no outputs will have been configured so it will not yet have credentials to connect to any resources.

If you're adapting an existing workflow, note these steps:

  1. Set oidc: true on the step properties so that step will be issued a token
  2. Download and extract a .tar.gz Teleport build
  3. Run tbot start -c tbot.yaml with the configuration file defined above
Sharing credentials between steps

Note that in Bitbucket Pipelines, outputs cannot be securely shared between steps as anything stored using artifacts will remain downloadable once the CI run has completed.

Due to this limitation, all operations making use of Teleport credentials should be performed as part of the same step. If necessary, you can duplicate the script shown here to download and run tbot multiple times in a given run if credentials are needed in multiple steps.

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