Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

SPIFFE IDs, trust domains and SVIDs

After this lesson: I can read a SPIFFE ID and find it inside an X.509 or JWT SVID.

70 min lesson7 commandsWorkload identity lab: SPIFFE and SPIRE on k3s, with mTLS between services, on a private Ubuntu VM

A name every service can check

A SPIFFE ID is a workload's name, written as a URI such as spiffe://lab.test/basket. Every service in a company can read it and check it the same way.

Without a shared format, each team invents its own: a host name here, an account name there. Nobody can then write one rule about who may call what.

By the end of this lesson

Note

I can read a SPIFFE ID and find it inside an X.509 or JWT SVID.

Key words

WordWhat it meansExample
SPIFFE IDa workload's name as a URIspiffe://lab.test/basket
Trust domainthe part after spiffe://, one signing authoritylab.test
X.509-SVIDa certificate carrying the ID in its URI SAN
JWT-SVIDa signed token carrying the ID in its sub claim
Trust bundlethe CA certificates that check a trust domain's SVIDs
Registration entrya rule that gives an ID to matching workloads

The cells students fill in are left blank in this preview.

A SPIFFE ID has two parts

After spiffe:// comes the trust domain, such as lab.test. Everything in a trust domain is signed by one authority. Then comes the path, such as /ns/demo/sa/printer, which names the workload inside it.

The rules are strict. Lower-case letters, digits, dots, dashes and underscores in the trust domain. No port, no user, no query, no empty segment, no . or .., and no slash at the end.

Worked example: valid or not

TextValid?Why
spiffe://lab.test/basketYesTrust domain lab.test, path /basket
spiffe://lab.testYesA trust domain with no path
spiffe://Lab.test/basketNoCapital letter in the trust domain
spiffe://lab.test/basket/NoA slash at the end
spiffe://lab.test:8443/basketNoA port is not allowed
https://lab.test/basketNoThe scheme must be spiffe

The cells students fill in are left blank in this preview.

A registration entry gives out an ID

An ID is given by a registration entry. It names the SPIFFE ID, the agent allowed to hand it out (the parent ID) and the selectors a workload must match. Lesson 4 looks at entries closely.

The next two Runs register the lessons' workloads. The user catalogue gets spiffe://lab.test/catalogue, and basket gets spiffe://lab.test/basket. Each prints the new entry; its Entry ID differs in every copy.

Register the catalogue workload

Command
sudo spire-server entry create -parentID spiffe://lab.test/spire/agent/x509pop/spire-lab -spiffeID spiffe://lab.test/catalogue -selector unix:user:catalogue

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Register the basket workload

Command
sudo spire-server entry create -parentID spiffe://lab.test/spire/agent/x509pop/spire-lab -spiffeID spiffe://lab.test/basket -selector unix:user:basket

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

An X.509-SVID is a short certificate

An X.509-SVID is an ordinary certificate with one difference: its name is a URI SAN holding the SPIFFE ID. TLS libraries already know how to use it.

Wait a few seconds after registering, then fetch as basket. The Run prints SPIFFE ID: spiffe://lab.test/basket, then SVID Valid After and SVID Valid Until about an hour and ten seconds apart. SPIRE starts the certificate ten seconds early to allow for clocks that differ.

Fetch the X.509-SVID as basket

Command
sudo -u basket spire-agent api fetch x509

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Make a folder basket owns

Command
sudo -u basket mkdir -p /tmp/basket

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Write the SVID to files

Command
sudo -u basket spire-agent api fetch x509 -write /tmp/basket

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Read the SPIFFE ID inside it

Command
openssl x509 -in /tmp/basket/svid.0.pem -noout -ext subjectAltName

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Three files, and one stays private

The write Run makes svid.0.pem (the certificate), svid.0.key (its private key, readable by basket alone) and bundle.0.pem (the trust bundle). OpenSSL prints URI:spiffe://lab.test/basket under X509v3 Subject Alternative Name.

The private key was made on this machine and never left it.

A JWT-SVID is a signed token

Some calls cannot use mutual TLS, for example through a proxy that ends TLS. A JWT-SVID is a signed token instead. Its sub claim is the SPIFFE ID and its aud claim names who may accept it.

The Run prints token(spiffe://lab.test/basket):, a long token in three parts joined by dots, then the trust domain's JWT keys. The token lasts five minutes here.

Fetch a JWT-SVID for the catalogue

Command
sudo -u basket spire-agent api fetch jwt -audience catalogue

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think a JWT-SVID is safer because it is newer. A JWT can be replayed by anybody who copies it until it expires. Use X.509-SVIDs with mutual TLS where you can, and short JWTs with a narrow audience where you cannot.

About this lab and its source: Workload identity lab: SPIFFE and SPIRE on k3s, with mTLS between services, on a private Ubuntu VM

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.