# Deploying tbot with Workload Identity on AWS Teleport Workload Identity issues short-lived cryptographic identities to workloads, enabling them to securely authenticate and communicate with other workloads or cloud provider APIs. This guide walks you through deploying the Machine & Workload Identity agent `tbot` on an Amazon EC2 instance and setting up Machine and Workload Identity (MWI). By the end, you'll have a working `tbot` service that issues SPIFFE-compatible credentials to workloads running on your EC2 instance. ## Prerequisites - 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. * An AWS IAM role that you wish to grant access to your Teleport cluster. This role must be granted `sts:GetCallerIdentity`. In this guide, this role will be named `teleport-bot-role`. * An AWS EC2 instance with the IAM role attached that you'll install the MWI agent, `tbot`, onto. ## Step 1/7. Install `tbot` **This step is completed on the AWS EC2 instance.** Install `tbot` on the EC2 instance that will use Machine & Workload Identity. Download and install the appropriate Teleport package for your platform: To install a Teleport Agent on your Linux server: The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster. 1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://). 2. Run your cluster's install script: ``` $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash ``` ## Step 2/7. Create a Bot **This step is completed on your local machine.** 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/7. Create a join token **This step is completed on your local machine.** Create `bot-token.yaml`: ``` kind: token version: v2 metadata: # name will be specified in the `tbot` to use this token name: example-bot spec: roles: [Bot] # bot_name should match the name of the bot created earlier in this guide. bot_name: example join_method: iam # Restrict the AWS account and (optionally) ARN that can use this token. # This information can be obtained from running the # "aws sts get-caller-identity" command from the CLI. allow: - aws_account: "111111111111" aws_arn: "arn:aws:sts::111111111111:assumed-role/teleport-bot-role/i-*" ``` Replace: - `111111111111` with the ID of your AWS account. - `teleport-bot-role` with the name of the AWS IAM role you created and assigned to the EC2 instance. - `example` with the name of the bot you created in the second step. - `i-*` indicates that any instance with the specified role can use the join method. If you wish to restrict this to an individual instance, replace `i-*` with the full instance ID. Use `tctl` to apply this file: ``` $ tctl create bot-token.yaml ``` ## Step 4/7. Configure `tbot` **This step is completed on the AWS EC2 instance.** Configure `workload-identity-api` service in `tbot`. To issue SPIFFE credentials to workloads, `tbot` must expose a Workload API endpoint. You'll configure this by adding the `workload-identity-api` service to your `tbot` configuration. First, determine where you wish this socket to be created. In our example, we'll use `/opt/machine-id/workload.sock`. You may wish to choose a directory that is only accessible by the processes that will need to connect to the Workload API. Create `/etc/tbot.yaml`: ``` version: v2 # Teleport proxy server address proxy_server: example.teleport.sh:443 # Onboarding configuration onboarding: join_method: iam token: example-bot # Storage configuration for tbot state storage: type: directory path: /var/lib/teleport/bot # Services section - configures the workload-identity-api service services: - type: workload-identity-api listen: unix:///opt/machine-id/workload.sock selector: name: example-workload-identity attestors: systemd: enabled: true ``` Replace: - `example.teleport.sh:443` with the address of your Teleport Proxy Service or Auth Service. Prefer using the address of a Teleport Proxy Service instance. - `example-bot` with the name of the token you created in the third step. By default, `tbot` will run in daemon mode. However, this must then be configured as a service within the service manager on the Linux host. The service manager will start `tbot` on boot and ensure it is restarted if it fails. **If tbot was installed using the Teleport install script or `teleport-update` command, the `tbot` systemd service is automatically created for you.** After `tbot.yaml` is created, enable and start the service: ``` $ sudo systemctl enable tbot --now ``` Check the service has started successfully: ``` $ sudo systemctl status tbot ``` Service properties like `User` and `Group` may be configured using `systemctl edit tbot`. **If tbot was installed manually, service configuration will need to be performed manually as well.** For this guide, systemd will be demonstrated but `tbot` should be compatible with all common alternatives. Use `tbot install systemd` to generate a systemd service file: ``` $ sudo tbot install systemd \ --write \ --config /etc/tbot.yaml \ --user teleport \ --group teleport \ --pid-file /run/tbot.pid \ --anonymous-telemetry ``` Ensure that you replace: - `teleport` with the name of Linux user you wish to run `tbot` as. - `/etc/tbot.yaml` with the path to the configuration file you have created. - `/run/tbot.pid` with a path that the user configured for `tbot` has write access to. By default, `tbot` writes its PID file to `/run/tbot.pid`. You can omit `--write` to print the systemd service file to the console instead of writing it to disk. `--anonymous-telemetry` enables the submission of anonymous usage telemetry. This helps us shape the future development of `tbot`. You can disable this by omitting this. Next, enable the service so that it will start on boot and then start the service: ``` $ sudo systemctl daemon-reload $ sudo systemctl enable tbot --now ``` Check the service has started successfully: ``` $ sudo systemctl status tbot ``` Restart your `tbot` instance to apply the new configuration. ## Step 5/7. Configure Workload Identity Next, we'll configure Workload Identity on the target resource you just created. With your bot configured and connected to Teleport, you can now use it to issue SPIFFE-compatible credentials to workloads through Teleport's Workload Identity system. You'll: - Create a Workload Identity resource that defines your workload's SPIFFE ID. - Configure RBAC so your Bot can issue credentials for that identity. - Update your `tbot` instance to expose a SPIFFE Workload API endpoint that workloads can connect to receive SPIFFE SVID-compatible credentials. Before proceeding, you'll want to determine the SPIFFE ID path that your workload will use. In our example, we'll use `/svc/foo`. We provide more guidance on choosing a SPIFFE ID structure in the [Best Practices](https://goteleport.com/docs/machine-workload-identity/workload-identity/best-practices.md) guide. Create a new file called `workload-identity.yaml`: ``` kind: workload_identity version: v1 metadata: name: example-workload-identity labels: example: getting-started spec: spiffe: id: /svc/foo ``` Replace: - `example-workload-identity` with a name that describes your use-case. - `/svc/foo` with the SPIFFE ID path you have decided on issuing. Use `tctl create ./workload-identity.yaml` to create the Workload Identity. ### Using workload attestation Instead of hard-coding values in the SPIFFE ID, you can also use [workload attestation](https://goteleport.com/docs/reference/machine-workload-identity/workload-identity/workload-identity-api-and-workload-attestation.md) to dynamically populate it based on workload attributes. For example, you can include the name of the `systemd` service requesting the identity. Add the following to your `tbot.yaml` configuration to enable the `systemd` attestor: ``` services: - type: workload-identity-api listen: unix:///opt/machine-id/workload.sock selector: name: example-workload-identity attestors: systemd: enabled: true ``` Then define a workload identity that references the attested service name: ``` kind: workload_identity version: v1 metadata: name: example-workload-identity labels: example: getting-started spec: spiffe: id: "/svc/{{workload.systemd.service}}" ``` With this configuration, the SPIFFE ID automatically includes the systemd service name, such as `/svc/my-app` for a service named `my-app`. ## Step 6/7. Testing the Workload API with `tbot spiffe-inspect` Use `tbot spiffe-inspect` to verify that the Workload API endpoint is issuing SPIFFE credentials correctly. This command connects to the endpoint, requests SVIDs, and prints detailed debug information. Before configuring your workload to use the Workload API, we recommend using this command to ensure that the Workload API is behaving as expected. Use the `spiffe-inspect` command with `--path` to specify the path to the Workload API socket, replacing `/opt/machine-id/workload.sock` with the path you configured in the previous step: ``` $ tbot spiffe-inspect --path unix:///opt/machine-id/workload.sock INFO [TBOT] Inspecting SPIFFE Workload API Endpoint unix:///opt/machine-id/workload.sock tbot/spiffe.go:31 INFO [TBOT] Received X.509 SVID context from Workload API bundles_count:1 svids_count:1 tbot/spiffe.go:46 SVIDS - spiffe://teleport.example.com/svc/foo - Expiry: 2025-03-20 10:55:52 +0000 UTC Trust Bundles - teleport.example.com ``` This confirms that workloads can successfully connect to the Workload API and receive SPIFFE-compatible credentials issued by Teleport. ## Step 7/7. Configuring your workload to use the Workload API Now that you know that the Workload API is behaving as expected, you can configure your workload to use it. The exact steps will depend on the workload. In cases where you have used the SPIFFE SDKs, you can configure the `SPIFFE_ENDPOINT_SOCKET` environment variable to point to the socket created by `tbot`. ## Next steps - Read the [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all available configuration options. - Restrict which SVIDs are issued based on characteristics of the workload using [Workload Attestation](https://goteleport.com/docs/reference/machine-workload-identity/workload-identity/workload-identity-api-and-workload-attestation.md#workload-attestation). - Configure [WorkloadIdentity Rules](https://goteleport.com/docs/reference/machine-workload-identity/workload-identity/sigstore-attestation.md) based on the attributes determined via workload attestation. - [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](https://goteleport.com/docs/reference/machine-workload-identity/telemetry.md).