Getting Started with Workload Identity

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 15.3.0 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.

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.3.0
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl 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: svid-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

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.