teleport/docs/pages/machine-workload-identity/getting-started.mdx

---
title: Machine and Workload Identity Getting Started Guide
description: Getting started with Teleport Machine and Workload Identity
sidebar_label: Getting Started
sidebar_position: 2
videoBanner: YzVK2tr6u-U
tags:
 - get-started
 - mwi
 - infrastructure-identity
page_type: how-to
---

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](./use-cases/iac-mwi.mdx)
workflows to [AI agent](./use-cases/ai-agents-mwi.mdx) 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.

In this guide, you will:
- 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](../machine-workload-identity/deployment/deployment.mdx) guides.

{/* lint ignore page-structure remark-lint */}

## 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](../enroll-resources/enroll-resources.mdx).

- A GitHub repository where you have permissions to create GitHub Actions workflows.
  <details>
  <summary>Using GitHub Enterprise?</summary>

  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.

  <br/>
  The join token fields are available and commented out in the example join token file.
  </details>
- 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](../enroll-resources/enroll-resources.mdx)
    for enrolling a new resource.

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

(!/docs/pages/includes/tctl.mdx!)

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

<Tabs>
<TabItem label="Server">

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

```code
$ 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
```

</TabItem>

<TabItem label="Kubernetes">

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

```code
$ tctl kube ls --format=text

Cluster  Labels                        Version
-------- ----------------------------- -------
staging  env=mwi-demo,region=us-west-2  18.1.5
```

</TabItem>
</Tabs>

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.

<Tabs>
<TabItem label="Server">

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

```yaml
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:

```code
$ tctl create -f ./role.yaml
```

</TabItem>

<TabItem label="Kubernetes">

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

```yaml
kind: role
version: v7
metadata:
  name: github-bot
spec:
  allow:
    kubernetes_labels:
      env: mwi-demo
    kubernetes_groups:
      - system:masters
    kubernetes_resources:
      - kind: '*'
        name: '*'
        namespace: default
        verbs:
          - '*'
```

Replace:

- `env: mwi-demo` with the label selector that matches your target resource.
- `system:masters` with the Kubernetes group that the workflow should have access to.

Use `tctl create` to create the role from the file:

```code
$ tctl create -f role.yaml
```

</TabItem>
</Tabs>

## Step 3/5. Create a bot

In Teleport, a **Bot user** represents an identity for a machine or AI agent.
Like SSO users and local 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:

```yaml
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:

```code
$ 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 <i>identity</i>,
rather than just a shared secret.

Teleport supports a number of secure [join methods](../reference/deployment/join-methods.mdx#delegated-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:

```yaml
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:

```code
$ tctl create -f join_token.yaml
```

## Step 5/5 Access a resource from GitHub Actions

We have several published [Actions](../reference/deployment/join-methods.mdx#github-actions-helpers)
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.

<Tabs>
<TabItem label="Server">

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

```yaml
version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: github-bot
certificate_ttl: 5m
storage:
  type: memory
services:
  - 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:

```yaml
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 ubuntu@myinstance.example.teleport.sh 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 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.

</TabItem>

<TabItem label="Kubernetes">

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

```yaml
version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: github
  token: github-bot
certificate_ttl: 5m
storage:
  type: memory
services:
  - type: kubernetes/v2
    selectors:
      - name: my-kubernetes-cluster
    destination:
      type: directory
      path: ./k8s_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.
- `my-kubernetes-cluster` with the name of your Kubernetes cluster as enrolled in Teleport.

This configuration will write credentials for Kubernetes access to the
`./k8s_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:

```yaml
on:
  workflow_dispatch:

jobs:
  list_pods:
    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: List pods in default namespace
    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 kubectl config
      run: tbot start --oneshot -c ./tbot.yaml
    - name: Run kubectl get pods
      run: |
        kubectl --kubeconfig=./k8s_out/kubeconfig.yaml get pods -n default
```

Replace:

- `example.teleport.sh:443` with the address of your Teleport proxy

In the second step of this workflow, we use 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 Kubernetes configuration and
credentials in the `./k8s_out` directory.

Finally, we run a `kubectl` command using the short-lived identity. This could
instead be Helm or another Kubernetes configuration management tool.

Commit and push this file to your repository.

</TabItem>
</Tabs>

### Run the workflow

Execute the workflow you created:

<Tabs>
<TabItem label="Web UI">

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

</TabItem>
<TabItem label="CLI">

Execute the following command:

```code
$ gh workflow run teleport.yaml --ref main
```

</TabItem>
</Tabs>

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](./deployment/deployment.mdx) to learn about
  configuring `tbot` in a production-ready way for your platform.
- Check out the [access guides](./access-guides/access-guides.mdx) to learn about configuring
  `tbot` for other use cases than SSH and Kubernetes.
- Read the [configuration reference](../reference/machine-workload-identity/configuration.mdx) to explore
  all the available configuration options.
- Learn how [Workload Identities](../machine-workload-identity/workload-identity/introduction.mdx) enable the same capabilities
  for resources like cloud APIs that can't be protected with the Teleport proxy.