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

Free lesson

Workload Identity Basics

The whole lesson is free and interactive. Read it here, or press Start lab to run it for real in a live lab, with no account needed.

Virtual machine lab10 min read8 commands

No password in the file

Two programs that talk to each other usually share a password, copied into a file on every server. Anybody who copies that file can pretend to be the program for years. Workload identity gives each running program its own short-lived identity instead, after checking what it really is.

By the end of this lesson

Note

I can register a workload and fetch its identity from the SPIRE agent.

Key words

  • Workload: a running program, such as a service.
  • SPIFFE ID: a workload's name, such as spiffe://lab.test/reader.
  • SVID: a short-lived certificate that carries a SPIFFE ID.
  • SPIRE agent: the program on each machine that checks workloads and hands out SVIDs.
  • Registration entry: a rule saying which workload gets which SPIFFE ID.

Starter: what you already know

Note

Answer in your head. 1. What is a certificate for on a website? 2. Why is a password copied to ten servers hard to change? 3. What is a Unix user? You need all three in a moment.

Before you start

Note

Press Start the lab on the bar at the top of this lesson. This lab is a whole Ubuntu machine of your own with SPIRE and a small Kubernetes cluster installed in it, so it takes a few minutes to come up the first time. Each Run button types its command into the machine's terminal, one after another in the same session. To watch them, or to type your own, press Open terminal on the bar.

SPIRE is running

This machine runs a SPIRE server, which signs identities, and an agent, which talks to the programs. spirelab status prints Server is healthy. and Agent is healthy., the trust domain lab.test, and whether k3s is ready. Each Unix user here stands for one workload.

Command
spirelab status

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

No entry, no identity

The user reader asks the agent for its identity. Nobody has registered it, so the agent checks it, finds no entry and gives it nothing: the Run prints no identity issued.

Command
sudo -u reader spire-agent api fetch x509

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

A common mistake

Warning

Many people think SPIRE gives every program an identity. It gives one only to a workload that matches a registration entry, after the agent has checked it. Everything else gets nothing.

Register reader, then ask again

The entry says: a process run by the Unix user reader, on this machine's agent, gets spiffe://lab.test/reader. It prints the new entry. The agent learns about it within a few seconds, so the next Run waits ten seconds. Then the fetch prints SPIFFE ID: spiffe://lab.test/reader and two times about an hour apart: the SVID is valid for an hour, and the agent renews it on its own.

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

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

Command
sleep 10

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

Command
sudo -u reader spire-agent api fetch x509

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

Check

Tip

Why did the same command fail the first time and work the second? Answer: the second time there was a registration entry for the user reader, so the agent gave it an SVID.

The identity is a certificate

An X.509 SVID is an ordinary certificate whose name is the SPIFFE ID. The first Run makes a folder reader owns, the second writes reader's SVID, its private key and the trust bundle into it, and the third reads the certificate with OpenSSL. It prints URI:spiffe://lab.test/reader under X509v3 Subject Alternative Name. The private key was made on this machine and never left it.

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

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

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

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

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

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

Now do the lab

Tip

You have registered one workload and read its SVID. Your lab asks for more: two services with an identity each, one allowed to call the other over mutual TLS, and a Kubernetes pod with an identity of its own. Open the README.md in your home folder with cat README.md in the terminal.

Exit check

Tip

Answer without looking back. 1. What does a registration entry do? 2. What did reader get before it was registered? 3. How long was its SVID valid? 4. Where in the certificate is the SPIFFE ID? Answers: it says which workload gets which SPIFFE ID; nothing; about an hour; in the subject alternative name, as a URI.

For teachers

Tip

This lesson is a small example of a lesson worked in a lab: the steps and the Run buttons are the lesson, and the lab is each student's own copy. This lesson is worked in a VM lab: each student has an Ubuntu machine with a SPIRE server and agent and a one-node k3s cluster, and a Run types into its terminal and shows what it printed. Key learning points: 1. A workload gets an identity only when an entry matches it. 2. The agent hands out short-lived SVIDs and renews them. 3. An SVID is a certificate whose subject alternative name holds the SPIFFE ID. Common mistake: believing every program gets an identity. Equipment: the lab and a browser; SPIRE alone runs in 1 GB, the lab's pod part needs a college account's 2 GB. Tip: before the second fetch, ask the class what will be different and why. The lab itself has a check that marks the work. Copy it into your own module and change it, or build one from scratch with the Lab menu in the lesson builder.

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 these lessons for your students with marking and a lab for every student.