# Workload Identity and tsh

In some scenarios, you may wish to issue a SPIFFE SVID manually, without using `tbot`. 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 access to services that 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](https://goteleport.com/docs/machine-workload-identity/workload-identity/getting-started.md) for more information.

* 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\<username>) 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
     ```

## 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:

| `flag`             | Description                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `--credential-ttl` | Sets 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:

| `file`            | Description                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `svid_key.pem`    | The private key for the X509 SVID. This is PEM wrapped and marshalled in PKCS8 format.                                                                                         |
| `svid.pem`        | The X509 SVID itself. This is PEM wrapped and DER encoded.                                                                                                                     |
| `svid_bundle.pem` | The 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

- [Workload Identity Overview](https://goteleport.com/docs/machine-workload-identity/workload-identity/introduction.md): Overview of Teleport Workload Identity.
- [Getting Started](https://goteleport.com/docs/machine-workload-identity/workload-identity/getting-started.md): How to configure Teleport for 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 [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available configuration options.