# Machine and Workload Identity Getting Started Guide
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](https://goteleport.com/docs/machine-workload-identity/use-cases/iac-mwi.md) workflows to [AI agent](https://goteleport.com/docs/machine-workload-identity/use-cases/ai-agents-mwi.md) 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](https://goteleport.com/docs/machine-workload-identity/deployment.md) 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](https://goteleport.com/docs/enroll-resources.md).
- 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](https://goteleport.com/docs/enroll-resources.md) for enrolling a new resource.
* A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).
* 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:
**Mac**
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.
---
**Windows - Powershell**
```
$ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead.
```
**Linux**
All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).
```
$ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
$ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
$ cd teleport
$ sudo ./install
Teleport binaries have been copied to /usr/local/bin
```
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 18.7.3
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.
**Server**
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
```
**Kubernetes**
You can find your clusters and labels in the GUI or with the following command:
```
$ tctl kube ls --format=text
Cluster Labels Version
-------- ----------------------------- -------
staging env=mwi-demo,region=us-west-2 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.
**Server**
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
```
**Kubernetes**
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:
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:
```
$ tctl create -f role.yaml
```
## 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:
```
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](https://goteleport.com/docs/reference/deployment/join-methods.md#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:
```
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](https://goteleport.com/docs/reference/deployment/join-methods.md#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.
**Server**
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
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:
```
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.
**Kubernetes**
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
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:
```
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.
### 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](https://goteleport.com/docs/machine-workload-identity/deployment.md) to learn about configuring `tbot` in a production-ready way for your platform.
- Check out the [access guides](https://goteleport.com/docs/machine-workload-identity/access-guides.md) to learn about configuring `tbot` for other use cases than SSH and Kubernetes.
- Read the [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available configuration options.
- Learn how [Workload Identities](https://goteleport.com/docs/machine-workload-identity/workload-identity/introduction.md) enable the same capabilities for resources like cloud APIs that can't be protected with the Teleport proxy.