Skip to main content

Getting Started with Workload Identity

Design Partnership

We're actively looking for design partners to help us shape the future of Teleport 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 15.4.22 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@example.com
    $ tctl status
    # Cluster  teleport.example.com
    # Version  15.4.22
    # 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: 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​