Workload Identity and tsh

In some scenarios, you may wish to issue a SPIFFE SVID manually, without using Machine ID. This can be useful in scenarios where you need to impersonate a service for the purposes of debugging or could provide a mechanism for providing human access to services which use SPIFFE SVIDs for authentication.

In this guide, you will use the tsh tool to issue a SPIFFE SVID.

Prerequisites

• A role configured to allow issuing SPIFFE SVIDs and this role assigned to your user. See Getting Started for more information.

• A running Teleport cluster version 15.4.22 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

Step 1/2. Using tsh to issue a SPIFFE SVID

First, determine where you wish to write the SPIFFE SVID. If you wish to write these into a directory, you must first create it. In our example, we will write the SVID to a directory called svid.

Next, determine what SPIFFE ID you wish to issue the SVID for. In our example, this will be a SPIFFE ID with a path of /my-svc.

Issue the SVID specifying the output directory using --out and the SPIFFE ID path as the first argument:

$ tsh svid issue --out ./svid /my-svc

Additionally, flags can be used to further customize the SVID:

Using headless authentication to issue a SVID on a remote host

In some scenarios, you may wish to use tsh to issue a SVID on a host you have SSHed into, without logging into Teleport on that host. This can be particularly useful in scenarios where authentication may not be possible, for example, when you authenticate using a hardware token.

In this case, you can use the headless authentication feature of tsh. This provides a prompt for you to authenticate the command on the remote machine, using your local tsh client.

To use headless authentication, we provide the --headless flag, and must also specify the --proxy and --user flags:

$ tsh --proxy=example.teleport.sh --user=example --headless svid issue \
  --output . \
  /foo

Step 2/2. Using the output SVID

Once the SVID has been issued, you can configure your workload to use it. This will differ depending on the workload.

When written to disk, the SVID will be written as three files:

Next steps

• Workload Identity Overview: Overview of Teleport Workload Identity.
• Getting Started: How to configure Teleport for Workload Identity.
• Best Practices: Best practices for using Workload Identity in Production.
• Read the configuration reference to explore all the available configuration options.