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 17.0.0-dev 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@example.com
  tctl status
  Cluster  teleport.example.com
  Version  17.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.
• A Bitbucket repository you can push to.

Step 1/4. 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/4. 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/4. 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/4. Configure a Bitbucket Pipelines workflow

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

This example workflow defines a "custom" pipeline that can be triggered manually from "Pipelines" or "Branches" views:

image: atlassian/default-image:3

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

            # Run `tbot` in identity mode for SSH access
            - ./teleport/tbot start identity --destination=./tbot-user --join-method=bitbucket --proxy-server=example.teleport.sh:443 --token=bot-bitbucket --oneshot

            # Make use of the generated SSH credentials
            - ssh -F ./tbot-user/ssh_config user@node.example.teleport.sh echo "hello world"

This example will start tbot in identity mode to generate SSH credentials. Refer to the tbot start documentation for details on using other modes such as database, application, and Kubernetes access.

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 with --join-method=bitbucket, --token=example-bot (or whichever name was configured in Step 3), and --oneshot

Further steps

• Follow the access guides to finish configuring tbot for your environment.
• Read the configuration reference to explore all the available configuration options.
• For more information about Bitbucket Pipelines itself, read their documentation.