![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Getting Started with Workload Identity
- 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.
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.
In this guide, you'll configure the RBAC necessary to allow a Bot to issue
SPIFFE SVIDs and then configure tbot
to expose a SPIFFE Workload API endpoint.
You can then connect your workloads to this endpoint to receive SPIFFE SVIDs.
Prerequisites
-
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
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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.
Step 1/4. Configure RBAC
First, Teleport must be configured to allow the Bot to issue SPIFFE SVIDs. This is done by configuring a role to allow the issuance of SPIFFE SVIDs and then granting this role to the Bot.
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 guide.
Create a new file named spiffe-issuer-role.yaml
:
kind: role
version: v6
metadata:
name: spiffe-issuer
spec:
allow:
spiffe:
- path: "/svc/foo"
Replace:
spiffe-issuer
with a name that describes your use-case./svc/foo
with the SPIFFE ID path you have decided on issuing.
Use tctl create -f ./spiffe-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 spiffe-issuer
with the name of the role you just created:
$ tctl bots update example-bot --add-roles spiffe-issuer
Step 2/4. Configure spiffe-workload-api
service in tbot
To set up a SPIFFE Workload API endpoint with tbot
, we configure an instance
of the spiffe-workload-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 spiffe-workload-api
service:
services:
- type: spiffe-workload-api
listen: unix:///opt/machine-id/workload.sock
svids:
- path: /svc/foo
hint: my-hint
Replace:
/opt/machine-id/workload.sock
with the path to the socket you wish to create./svc/foo
with the SPIFFE ID path you have decided on issuing.my-hint
with a hint that will be included with the SVID. This can help workloads identify which SVID they should select if multiple are presented. This field can be omitted if not required.
Start or restart your tbot
instance to apply the new configuration
Configuring DNS and IP SANs
In some cases, you may wish to configure DNS and IP SANs which should be included in the SVIDs 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.
These can be configured in the spiffe-workload-api
service using the sans
configuration block:
services:
- type: spiffe-workload-api
listen: unix:///opt/machine-id/workload.sock
svids:
- path: /svc/foo
hint: my-hint
sans:
dns:
- example.com
ip:
- 10.0.0.1
You will also need to modify the role to explicitly grant the Bot permission to request an SVID including a DNS or IP SAN. For example:
kind: role
version: v6
metadata:
name: spiffe-issuer
spec:
allow:
spiffe:
- path: "/svc/foo"
# Replace with the DNS SANs that you wish your Bot to be able to include
# in SVIDs.
dns_sans: ["example.com"]
# Replace with the IP SANs that you wish your Bot to be able to include
# in SVIDs. You can remove this if you do not wish to include IP SANs.
# IPs must be specified using CIDR notation, which allows you to specify
# a single IP or a range of IPs.
ip_sans: ["10.0.0.1/32"]
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.
To configure Workload Attestation, you configure a set of rules for each SVID. Each rule is a list of characteristics, and all characteristics within the rule must match for that rule to pass. If you have multiple rules, any one rule can pass for the SVID to be issued.
For example, to configure an SVID 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:
services:
- type: spiffe-workload-api
listen: unix:///opt/machine-id/workload.sock
svids:
- path: /svc/foo
hint: my-hint
rules:
- uid: 1000
- gid: 50
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
- Hint: my-hint
- 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 guide for more information on integrating SPIFFE with your workloads.
Next steps
- Workload Identity Overview: Overview of Teleport Workload Identity.
- Best Practices: Best practices for using Workload Identity in Production.
- Read the configuration reference to explore all the available configuration options.