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

Free lesson

Mutual TLS between services with SVIDs

After this lesson: I can decide whether a caller is authorised from the SPIFFE ID in its certificate.

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

Both sides show a certificate

Mutual TLS, or mTLS, is TLS where the client shows a certificate too, so each side proves who it is. With SVIDs, each certificate names a workload by its SPIFFE ID.

A service can then refuse a caller with no identity at the handshake. It can also refuse a known caller that is not allowed, with no password anywhere.

By the end of this lesson

Note

I can decide whether a caller is authorised from the SPIFFE ID in its certificate.

Key words

WordWhat it means
mTLSTLS where both sides show a certificate
Authenticationproving who you are
Authorisationdeciding what you may do
Allow-listthe SPIFFE IDs a service accepts
Handshakethe start of TLS, where certificates are checked

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

Two checks: who, then what is allowed

The handshake does authentication. The server checks that the client's certificate was signed by its trust bundle. The client checks the server's the same way.

Then each side reads the other's SPIFFE ID and does authorisation. The client checks it reached the service it meant. The server checks the caller against its allow-list.

The catalogue service fetches its own SVID

The service catalogue runs on port 9443 as the user catalogue. Every 15 seconds it asks the agent for a fresh SVID, so it never reads a key from a file somebody copied.

Its allow-list starts empty. These Runs need lesson 2's two entries: if you skipped it, run its two register Runs first.

Read the catalogue's allow-list

Command
cat /etc/spirelab/catalogue.allow

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

Call the catalogue as basket

Command
spirelab call basket catalogue

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

Authenticated, but not authorised

The allow-list holds only a comment line. The call prints call: the server proved it is spiffe://lab.test/catalogue, then call: reply: refused: spiffe://lab.test/basket is not on the allow list.

The handshake worked: both sides proved who they are. The catalogue then said no. Add basket to the list and call again.

Allow basket to call the catalogue

Command
echo spiffe://lab.test/basket >> /etc/spirelab/catalogue.allow

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

Call the catalogue again

Command
spirelab call basket catalogue

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

No identity, no connection

Now the reply is hello spiffe://lab.test/basket, you are on the allow list. No restart was needed: the service reads the list for each call.

The user stranger has no entry, so it has no SVID and calls with no certificate. The Run prints call: the TLS handshake failed: TLSV13_ALERT_CERTIFICATE_REQUIRED. It never got as far as the allow-list.

Call the catalogue as stranger

Command
spirelab call stranger 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 valid certificate from the trust domain is enough to let a caller in. It only proves who the caller is. Without an allow-list, every workload in the trust domain could call every service.

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.