![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Workload Identity and tsh
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
Teleport Workload Identity is currently in Preview. This means that some features may be missing. We're actively looking for design partners to help us shape the future of Workload Identity and would love to hear your feedback.
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 16.2.1 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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
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:
flag | Description |
---|---|
--dns-san | Adds a DNS SAN to the resulting X509 SVID. |
--ip-san | Adds an IP SAN to the resulting X509 SVID. |
--svid-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 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:
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: 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.