Skip to main content
Version: 17.x

Workload Identity and tsh

Report an issue with this page

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 17.5.2 or above. If you do not have one, read Get Started with Teleport.

  • The tctl and tsh clients.

    Details

    Installing tctl and tsh clients

    Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

    curl -O https://cdn.teleport.dev/teleport-17.5.2.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.

    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/ping and use a JSON query tool to obtain your cluster version:

    curl https://example.teleport.sh/v1/webapi/ping | jq -r '.server_version'
    17.5.2

Step 1/2. Using tsh to issue a SPIFFE X509 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 which workload identity resource you'll use to issue the X509 SVID. In our example, we'll use a workload identity called my-workload-identity.

Issue the SVID specifying the output directory using --output and the name of the workload identity resource using --name-selector:

$ tsh workload-identity issue-x509 --output ./svid --name-selector my-workload-identity

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

flagDescription
--credential-ttlSets the Time To Live for the resulting X509 SVID. Specify duration using s, m and h, e.g 12h for 12 hours.

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 \
  workload-identity issue-x509 \
  --output . \
  --name-selector my-workload-identity

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:

fileDescription
svid_key.pemThe private key for the X509 SVID. This is PEM wrapped and marshalled in PKCS8 format.
svid.pemThe X509 SVID itself. This is PEM wrapped and DER encoded.
svid_bundle.pemThe SPIFFE trust bundle. A concatenated list of X509 certificates for the certificate authorities within the trust domain. These are individually PEM wrapped and DER encoded.

Next steps​