![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
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. The term workload refers generally to pieces of software running within your system. These identities can be used to secure workload to workload communication (e.g mTLS) or to allow these workloads to access third party systems.
It is compatible with the industry-standard Secure Production Identity Framework For Everyone (SPIFFE) Specification meaning that it can be used in place of other SPIFFE compatible identity providers.
Teleport Workload Identity brings a number of Teleport features you are already familiar with, such as:
- Auditing of the issuance of SPIFFE SVIDs.
- RBAC for limiting access to SPIFFE IDs to specific machines and users.
- Rotation and management of the SPIFFE CA.
- Using Teleport SPIFFE CA with 3rd party services such as AWS Roles Anywhere.
Teleport Workload Identity is different from Teleport Machine Identity in that it is intended for workload to workload communication and is not intended to grant access to the Teleport cluster itself. Workload Identity does not leverage the Teleport Proxy.
What is SPIFFE?
SPIFFE (Secure Production Identity Framework For Everyone) is a set of standards for securely identifying workloads.
SPIFFE sets out:
- A format for uniquely specifying an identity, the SPIFFE ID.
- Standards for encoding the SPIFFE ID into verifiable documents, the SVID.
- Processes that workloads should use to validate a received SVID.
- A set of APIs that workloads can use to request SVIDS, the Workload API.
The open nature and popularity of SPIFFE make it a great choice as a foundation for a full workload identity implementation. It is supported as an identity provider by a number of popular tools (such as Linkerd and Istio) and off-the-shelf SDKs exist for implementing SPIFFE directly into your own services.
It's important to recognize that SPIFFE does not specify how to use SPIFFE IDs for authorization. This gives a high level of flexibility, allowing you to implement authorization in a way that suits you.
SPIFFE IDs and Trust Domains
The basis of identity in SPIFFE is the SPIFFE ID. This is a unique string that
identifies a workload. The SPIFFE ID is formatted as a URI with a scheme of
spiffe
and contains a trust domain and a workload identifier.
The trust domain is the "root of trust" for your workload identities. Workloads
within the trust domain are issued identities by authorities within the trust
domain, and using the root keys of the trust domain, it is possible to
validate these identities. The trust domain is encoded as the host within the
URI. For Teleport Workload Identity, the trust domain is your Teleport cluster,
and this is represented by the name configured for the cluster,
e.g example.teleport.sh
.
The workload identifier is encoded in the URI as the path. This should be a
string that identifies your workload within the trust domain. What you include
within this path is up to you and your application's requirements. Typically,
the hierarchical nature of the path is leveraged. For example, you had the
service foo
operating in the europe
region, you may wish to represent this
as: /region/europe/svc/foo
.
Together, this produces a SPIFFE ID that looks like:
spiffe://example.teleport.sh/region/europe/svc/foo
Secure Verifiable Identity Documents (SVIDs)
The SPIFFE ID may be a unique identifier for a workload, but provides no way for a workload to verifiably prove its identity. This is where the Secure Verifiable Identity Documents (SVIDs) come in.
The SVID is a document that encodes the SPIFFE ID and a cryptographic proof which allows the SVID to be verified as issued by a trusted authority.
SPIFFE sets out two formats for SVIDs:
- X.509-SVID: These are X.509 certificates that include the SPIFFE ID encoded in the URI SAN field. This certificate is then signed by a trusted authority within the trust domain.
- JWT-SVID: These are JWT tokens that include the SPIFFE ID as the
sub
claim. These are signed by a trusted authority within the trust domain.
The data needed by a workload to verify a SVID is known as the trust bundle. This is a set of certificates belonging to the trusted authorities within the trust domain.
Workload API
The Workload API is a standardized gRPC API that workloads should use to request SVIDs and trust bundles from a SPIFFE identity provider. The Workload API server also handles automatically renewing the credentials for subscribed workloads.
The Workload API is usually exposed by an agent that is installed on the same host as the workloads and is accessed using a unix socket rather than a TCP endpoint. It can perform basic authentication and authorization of the workload before issuing SVIDs. This is known as Workload Attestation.
Teleport's Workload Identity
Teleport's Workload Identity is an implementation of SPIFFE. Each Teleport cluster acts as a SPIFFE trust domain, with the Auth Service as a certificate authority for issuing SVIDs.
Teleport's RBAC system is used to control which Bots and Users are able to request a SVID for a given SPIFFE ID. Roles can specify which SPIFFE IDs can be issued and this role is then granted to the Bot or User. For example:
kind: role
version: v6
metadata:
name: europe-foo-svid-issuer
spec:
allow:
spiffe:
- path: "/region/europe/svc/foo"
The SPIFFE Workload API is implemented as a configurable service within the
tbot
agent. The tbot
agent should be installed close to the workloads that
need to request SVIDs, and they can then use the Workload API exposed by tbot
to fetch SVIDs and Trust Bundles.
Teleport's Workload Identity currently only supports issuing X.509-SVIDs.
Next steps
- Getting Started: How to configure Teleport for Workload Identity.
- Best Practices: Best practices for using Workload Identity in Production.
- Workload Attestation: Learn about using Workload Attestation to securely issue SVIDs to specific workloads.
- TSH Support: How to use
tsh
with Workload Identity to issue SVIDs to users. - AWS Roles Anywhere: Configuring AWS to accept Workload ID certificates as authentication using AWS Roles Anywhere.
Other resources
- SPIFFE Specification: The official SPIFFE specification. Useful for understanding the SPIFFE ID and SVID formats.
- Solving The Bottom Turtle: A book covering the fundamentals and details of SPIFFE.