# Getting Started with Workload Identity Teleport's Workload Identity issues flexible short-lived identities intended for workloads. It is compatible with the industry-standard SPIFFE specification meaning that it can be used in place of other SPIFFE compatible identity providers. ## How it works In this guide, you'll configure the RBAC necessary to allow a Bot to issue workload identity credentials and then configure `tbot` to expose a SPIFFE Workload API endpoint. You can then connect your workloads to this endpoint to receive SPIFFE SVID-compatible workload identity credentials. ## 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 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. * `tbot` must already be installed and configured on the host where the workloads which need to access Teleport Workload Identity will run. For more information, see the [deployment guides](https://goteleport.com/docs/machine-workload-identity/deployment.md). ## Step 1/4. Configure Workload Identity First, you will need to create a Workload Identity resource. This resource is the primary way that Teleport Workload Identity is configured. Each Workload Identity resource represents the configuration of an identity for a specific workload or a template to be used when representing the identity of a group of workloads. The Workload Identity resource specifies a number of key things, including: - The name of the Workload Identity, which will be needed when issuing it. - The SPIFFE ID that will be included in credentials issued for this WorkloadIdentity. - Any rules around when this Workload Identity can be used to issue 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 -f ./workload-identity.yaml` to create the Workload Identity. Now, you'll need to create a role that will grant access to the Workload Identity that you have just created. As with other Teleport resources, access is granted by specifying label matchers on the role that will match the labels on the resource itself. In addition to granting access to the resource, we will also need to grant the ability to read and list the Workload Identity resource type. Create `workload-identity-issuer-role.yaml`: ``` kind: role version: v6 metadata: name: example-workload-identity-issuer spec: allow: workload_identity_labels: example: ["getting-started"] rules: - resources: - workload_identity verbs: - list - read ``` Use `tctl create -f ./workload-identity-issuer-role.yaml` to create the role. Now, use `tctl bots update` to add the role to the Bot. Replace `example-bot` with the name of the Bot you created in the deployment guide and `example-workload-identity-issuer` with the name of the role you just created: ``` $ tctl bots update example-bot --add-roles example-workload-identity-issuer ``` ### Configuring DNS SANs In some cases, you may wish to configure DNS SANs which should be included in the X509 certificates issued by the Workload API. This is useful in cases where the client may not be SPIFFE aware and will check the DNS SAN rather than the SPIFFE URI during the TLS handshake. Modify your `workload-identity.yaml` resource definition to include the `spec.spiffe.x509.dns_sans` field, replacing `example.com` with the DNS name you require: ``` kind: workload_identity version: v1 metadata: name: example-workload-identity labels: example: getting-started spec: spiffe: id: /svc/foo x509: dns_sans: - example.com ``` Use `tctl create -f ./workload-identity.yaml` to update the WorkloadIdentity resource with your changes. ## Step 2/4. Configure `workload-identity-api` service in `tbot` To set up a SPIFFE Workload API endpoint with `tbot`, we configure an instance of the `workload-identity-api` service. 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. Modify your `tbot` configuration file to include the `workload-identity-api` service: ``` services: - type: workload-identity-api listen: unix:///opt/machine-id/workload.sock selector: name: example-workload-identity ``` Replace: - `/opt/machine-id/workload.sock` with the path to the socket you wish to create. - `example-workload-identity` with the name of the Workload Identity resource you created earlier. Start or restart your `tbot` instance to apply the new configuration. ### Configuring Unix Workload Attestation By default, an SVID listed under the Workload API service will be issued to any workload that connects to the Workload API. You may wish to restrict which SVIDs are issued based on certain characteristics of the workload. This is known as Workload Attestation. When using the Unix listener, `tbot` supports workload attestation based on three characteristics of the workload process: - `uid`: The UID of the user that the workload process is running as. - `gid`: The primary GID of the user that the workload process is running as. - `pid`: The PID of the workload process. Within a Workload Identity, you can configure rules based on the attributes determined via workload attestation. Each rule contains a number of tests and all tests must pass for the rule to pass. At least one rule must pass for the Workload Identity to be allowed to issue a credential. For example, to configure a Workload Identity to be issued only to workloads that are running as the user with ID 1000 or running as a user with a primary group ID of 50: ``` kind: workload_identity version: v1 metadata: name: example-workload-identity labels: example: getting-started spec: rules: allow: - conditions: - attribute: workload.unix.uid eq: value: 1000 - conditions: - attribute: workload.unix.gid eq: value: 50 spiffe: id: /svc/foo ``` ## Step 3/4. Testing the Workload API with `tbot spiffe-inspect` The `tbot` binary includes a `spiffe-inspect` command that can be used to test the configuration of the Workload API. This command will connect to the Workload API and request SVIDs, whilst providing 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://example.teleport.sh/svc/foo - Expiry: 2024-03-20 10:55:52 +0000 UTC Trust Bundles - example.teleport.sh ``` ## Step 4/4. 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`. See the [Best Practices](https://goteleport.com/docs/machine-workload-identity/workload-identity/best-practices.md) guide for more information on integrating SPIFFE with your workloads. ## Next steps - [Workload Identity Overview](https://goteleport.com/docs/machine-workload-identity/workload-identity/introduction.md): Overview of Teleport Workload Identity. - [Best Practices](https://goteleport.com/docs/machine-workload-identity/workload-identity/best-practices.md): Best practices for using Workload Identity in Production. - Read the [Workload Identity reference](https://goteleport.com/docs/reference/machine-workload-identity/workload-identity/workload-identity-resource.md) to explore the configuration of the Workload Identity resource. - Read the [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available configuration options for `tbot`.