Skip to main content
Teleport Machine & Workload Identity Getting Started Guide
Teleport Machine & Workload Identity Getting Started Guide

Length: 07:10

Version: 19.x (unreleased)

Machine and Workload Identity Getting Started Guide

Report an issue with this page

Teleport Machine and Workload Identity (MWI) provides secure access for Non-Human Identities across multiple platforms and resource types, supporting everything from Infrastructure-as-Code workflows to AI agent operations. This guide focuses on a popular implementation: executing commands on deployment targets through CI/CD pipelines. Even if your specific use case differs, this guide covers the fundamental MWI setup process, after which you can reference the dedicated use case pages for tool-specific guidance.

Here's an overview of what you will do:

  • Choose a Linux server or Kubernetes cluster as your target resource.
  • Create a Role for your Bot, or choose an existing one.
  • Create a Bot in Teleport with a role allowing it to access your target resource.
  • Create a GitHub join token for the Bot.
  • Set up a GitHub Actions workflow that authenticates and issues a command using the tbot binary.

This guide covers configuring MWI for development and learning purposes. For a production-ready configuration of MWI, visit the Deploying Machine ID guides.

Prerequisites​

In this getting started guide, you will configure MWI to issue commands to a Linux server or Kubernetes cluster from a GitHub Actions workflow. This guide assumes you've already enrolled a Linux server or Kubernetes cluster to Teleport. If you haven't done so, refer to the guides on enrolling resources.

  • A GitHub repository where you have permissions to create GitHub Actions workflows.

    Using GitHub Enterprise?

    There is extra configuration needed when using GitHub Enterprise repositories, either cloud or self-hosted. We recommend using a personal repository for this guide if possible.

    If you need to use GitHub Enterprise, check the following:

    • Cloud
      • In the join token, under github set the enterprise_slug field to the name of your enterprise's slug, likely the name of the organization.
    • Self-hosted
      • Your Teleport Auth Service must be able to reach your GitHub Enterprise instance.
      • In the join token, under github, set the enterprise_server_host field to the hostname of your GitHub Enterprise instance.

    The join token fields are available and commented out in the example join token file.

  • A target resource enrolled in Teleport, either:

    • A Linux server
    • A Kubernetes cluster
    • If you don't have a target resource that you can use, follow one of the guides for enrolling a new resource.

  • A running Teleport cluster. If you do not have one, read Getting Started.

  • 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:

      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.

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 protected] to your Teleport username:

tsh login --proxy=teleport.example.com --user=[email protected]
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.

Step 1/5. Choose a target resource​

First, choose a target resource that you want your GitHub Actions workflow to access using Machine and Workload Identity.

To grant the GitHub Actions workflow access to the resource, you'll create a role and specify within this role the labels of the resources it should grant access to. Labels are key-value pairs that help identify and categorize resources in Teleport.

You can find your nodes and labels in the GUI or with the following command:

tctl nodes ls --format=text

Host    UUID                                 Public Address Labels                              Version------- ------------------------------------ -------------- ----------------------------------- -------target1 8a50c8aa-c45f-403c-95ff-83f50561d64c                env=mwi-demo,hostname=ip-10-0-0-200 18.1.5

In our examples, we'll use the env label with the value mwi-demo to control what our GitHub Actions workflow can access.

Step 2/5. Choose or create a role​

Now, we'll create a role which will grant access to our target resource. If you have a pre-existing role which grants access to your target resources, you can skip this step and use that instead.

On your local machine, create a file called role.yaml and add the following contents:

kind: role
version: v7
metadata:
  name: github-bot
spec:
  allow:
    node_labels:
      env: mwi-demo
    logins:
      - ubuntu

Replace:

  • env: mwi-demo with the label selector that matches your target resource.
  • ubuntu with the name of the Linux user that the workflow should have access to.

Use tctl create to create the role from the file:

tctl create -f ./role.yaml

Step 3/5. Create a bot​

In Teleport, a Bot represents an identity for a machine. This is similar to how a user represents the identity of a human. Like users, bots are assigned roles to manage their access to resources.

You'll now create a bot to represent the GitHub Actions workflow.

On your local machine, create a file called bot.yaml with the following contents:

kind: bot
version: v1
metadata:
  name: github-bot
spec:
  roles:
    - github-bot

Ensure that the value within the spec.roles field matches the name of the role you have just created.

Use tctl create to create the bot from the file:

tctl create -f ./bot.yaml

Step 4/5 Create a join token​

Unlike users, bots do not authenticate using a username and password or SSO. Instead, they authenticate in a process called joining. Teleport uses metadata about the platform the bot is running on, such as OIDC endpoints for CI pipelines, or the Assumed Role of an AWS EC2 Instance, to attest to the identity of the process, ensuring only authorized bots can join the cluster. This means the bot has a verified identity, rather than just a shared secret.

Teleport supports a number of secure join methods specific to the platform the bot is running on. Since we are using GitHub Actions, we will use the github join method.

For the join token definition, edit the repository field to match the GitHub repository where you will run the GitHub Actions workflow. When a bot attempts to join from that GitHub organization and repository, Teleport will identify it as your github-bot and assign it the correct role. If a bot attempts to join from any other repository, it will be rejected.

On your local machine, create a file called join_token.yaml with the following contents:

kind: token
version: v2
metadata:
  name: github-bot
spec:
  join_method: github
  roles:
  - Bot
  bot_name: github-bot
  github:
    allow:
    - repository: "your-github-username/my-repo"
    # enterprise_server_host: github.my-company.com # use for self-hosted GitHub Enterprise
    # enterprise_slug: my-company # use for GitHub Enterprise Cloud organization

Ensure that:

  • You replace your-github-username/my-repo with the name of the GitHub repository where your GitHub Actions workflow will run.
  • The spec.bot_name field matches the name of the bot you created in the previous step.
  • That you have set enterprise_server_host or enterprise_slug if appropriate.

Use tctl create to create the join token from the file:

tctl create -f join_token.yaml

Step 5/5 Access a resource from GitHub Actions​

We have several published Actions for convenience, but for this guide we will look at things explicitly to aid understanding.

Within your GitHub repository, you'll create two different files:

  • .github/workflows/teleport.yaml: the configuration for the GitHub Actions workflow, specifying which actions should be taken on what triggers.
  • tbot.yaml: the configuration file for the Machine & Workload Identity agent, tbot, which specifies how the bot should authenticate and what kind of identity it should request.

At the root of your GitHub repository, create a file called tbot.yaml with the following contents:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: github-bot
certificate_ttl: 5m
storage:
  type: memory
outputs:
  - type: identity
    destination:
      type: directory
      path: ./ssh_out

Replace:

  • example.teleport.sh:443 with the address of your Teleport Proxy.
  • github-bot with the name of the token you created in Step 4/5.

This configuration will write credentials for SSH access to the ./ssh_out directory, which will last up to 5 minutes. You can adjust this TTL to match the expected runtime of your job, so the identity expires when its purpose is complete.

Commit and push this file to your repository.

You'll now add the GitHub Actions workflow file. Within the GitHub repository, create a file at .github/workflows/teleport.yaml with the following contents:

on:
  workflow_dispatch:

jobs:
  check_resource_usage:
    permissions:
      # The "id-token: write" permission is required, or MWI will not be
      # able to authenticate with the cluster.
      id-token: write
      contents: read
    name: Check resource usage on server
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Fetch Teleport binaries
      uses: teleport-actions/setup@v1
      with:
        proxy: example.teleport.sh:443
        version: auto
    - name: Export ssh config
      run: tbot start --oneshot -c ./tbot.yaml
    - name: Run mpstat
      run: |
        ssh -F ./ssh_out/ssh_config [email protected] mpstat

Replace:

  • example.teleport.sh:443 with the address of your Teleport proxy
  • myinstance.example.teleport.sh with the address of your target server.
  • ubuntu with the Linux user you want to log in as.

In the second step of this workflow, we use one one of the published actions which installs the tbot binary into the workflow run environment.

In the third step, we use this binary with the configuration you created earlier to authenticate as the bot and produce the SSH configuration and credentials in the ./ssh_out directory.

Finally, we run an SSH command using the short-lived identity. Instead, this configuration file could be used with Ansible or other kinds of SSH-based automations.

Commit and push this file to your repository.

Run the workflow​

In your GitHub repository

  • Go to the Actions tab
  • Select the Teleport workflow on the left
  • Click Run workflow on the right
  • Make sure the branch is main and click the Run workflow confirmation button

After the workflow completes, you should see the job complete successfully, and the output of the command in the logs.

Summary​

You've successfully set up a workflow in GitHub Actions that can access your resources securely through the Teleport proxy, without distributing long-lived credentials, making the process more secure and efficient for development teams.

Next Steps​

  • Check out the deployment guides to learn about configuring tbot in a production-ready way for your platform.
  • Check out the access guides to learn about configuring tbot for other use cases than SSH and Kubernetes.
  • Read the configuration reference to explore all the available configuration options.
  • Learn how Workload Identities enable the same capabilities for resources like cloud APIs that can't be protected with the Teleport proxy.