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
| Word | What it means | Example |
|---|---|---|
| SPIFFE ID | a workload's name as a URI | spiffe://lab.test/basket |
| Trust domain | the part after spiffe://, one signing authority | lab.test |
| X.509-SVID | a certificate carrying the ID in its URI SAN | |
| JWT-SVID | a signed token carrying the ID in its sub claim | |
| Trust bundle | the CA certificates that check a trust domain's SVIDs | |
| Registration entry | a 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
| Text | Valid? | Why |
|---|---|---|
| spiffe://lab.test/basket | Yes | Trust domain lab.test, path /basket |
| spiffe://lab.test | Yes | A trust domain with no path |
| spiffe://Lab.test/basket | No | Capital letter in the trust domain |
| spiffe://lab.test/basket/ | No | A slash at the end |
| spiffe://lab.test:8443/basket | No | A port is not allowed |
| https://lab.test/basket | No | The 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
sudo spire-server entry create -parentID spiffe://lab.test/spire/agent/x509pop/spire-lab -spiffeID spiffe://lab.test/catalogue -selector unix:user:catalogueShown here, not run. Press Start lab to type it into your own lab’s terminal.
Register the basket workload
sudo spire-server entry create -parentID spiffe://lab.test/spire/agent/x509pop/spire-lab -spiffeID spiffe://lab.test/basket -selector unix:user:basketShown 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
sudo -u basket spire-agent api fetch x509Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Make a folder basket owns
sudo -u basket mkdir -p /tmp/basketShown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the SVID to files
sudo -u basket spire-agent api fetch x509 -write /tmp/basketShown here, not run. Press Start lab to type it into your own lab’s terminal.
Read the SPIFFE ID inside it
openssl x509 -in /tmp/basket/svid.0.pem -noout -ext subjectAltNameShown 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
sudo -u basket spire-agent api fetch jwt -audience catalogueShown 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.