docs: add new tutorials on identity and static attributes. - #167
Merged
Conversation
Signed-off-by: Teryl Taylor <terylt@ibm.com>
Recipe headings on dev use colons (#156), so the double-hyphen anchors this branch was written against no longer resolve. Update the six anchors and the link text to match. Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>
Modules 11-15, 17 and 18 join TUTORIAL_IDP_MODULES. Module 16 needs the SPIRE overlay and a one-time Keycloak setup, so it gets its own opt-in target instead. Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>
The three minters differed only in endpoint and form fields, so fold the client build, status check and access_token extraction into one helper. mint_token_in_realm now carries the same 'is the IdP running?' hint as the others, and mint_svid trims its output instead of collapsing all whitespace, which could splice extra stdout into the token. Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>
Correct the m15 header: an actor with subject: this_workload is denied when the step runs, not at load. Retarget m13 to github-api so the tool and its audience agree. Drop the send_email entry from controls.yaml, which no route reads. Trim the m14 header, cut comments that restate the scenario line, and drop em dashes to match the rest of the tutorial. Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>
Open each module on its own problem instead of a recap of the previous ones, cut the editorial asides, reserve bold for labels, and drop the em dashes the rest of the tutorial does not use. Fold module 14's trade-off and module 15's guardrail into the sections they belong to, shorten module 18's per-caller example and mark it as illustration rather than something the module runs, and note that module 18 must run from the repo root. Module 12 now points at modules 13, 15 and 16 for the subjects it used to call unsupported. Scale the time budget for eight extra modules, and link the recipe anchors and configuration sections that exist. Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>
The IdP README is the reference for the stack, so give it the cpex-agent client, the cpex-partner realm and its user, and the opt-in SPIFFE overlay. Switch setup-spiffe.sh to jq, which the rest of the tutorial already uses, and say plainly what re-running it does. Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>
araujof
approved these changes
Aug 15, 2026
araujof
left a comment
Contributor
There was a problem hiding this comment.
Reviewed, and pushed follow-ups to the branch: merged dev, repointed the cookbook anchors after #156 changed the recipe headings, wired modules 11 to 15, 17 and 18 into make tutorial-check (16 gets its own tutorial-check-spire), corrected the m15 header on where the actor: guardrail fires, deduped the three IdP token minters behind one helper, and did a prose pass on the new pages.
Verified end to end on the live stack: full gate green across all 19 modules, and module 16 green against a cold SPIRE overlay. LGTM.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds eight runnable tutorial modules that complete the identity and delegation
story, so every delegation recipe in the Identity & Delegation cookbook
has a hands-on module, plus two supporting identity topics (multi-issuer
federation, static attributes). Each module is a small program you run against
the live IdP and can edit, break, and re-run; each also runs in
--checkmode,wired into
make tutorial-check(module 16 has its ownmake tutorial-check-spire,since it needs the overlay).
The tutorial harness, IdP realm, and (for the SVID module) an opt-in SPIRE
overlay grow just enough to support these — modules 0–10 are unchanged in
behavior.
New modules
groups:bundlesubject: uservssubject: this_workloadsubject: clientsubject: user, actor: client— who authorized vs. who actedsubject: caller_workloaddata.*Every delegation module links to its cookbook recipe, and module 6 gained a
link to Recipe 1. The cookbook page itself is unchanged.
Supporting changes
examples/tutorial/src/):mediate.rs—Callergainsextra_credentials+with_credential(header, token)and
mediateresolves multiple credentials by header, so a dual-principal call(module 15) carries a user and an agent token. Single-token modules keep the
exact prior path.
idp.rs—mint_client_token(client_credentials),mint_token_in_realm(a second issuer), and
mint_svid(mints a JWT-SVID off SPIRE).examples/tutorial/idp/):realm-export.json— acpex-agentconfidential client (module 13).partner-export.json— a second realmcpex-partner= a second issuer (module 17).docker-compose.spire.yml— SPIRE server + OIDC provider, and Keycloak bumpedto 26.6.1 with
spiffe:v1. Additive over the base compose; modules 0–15/17/18don't use it.
spire/{server,oidc}/*.conf+spire/setup-spiffe.sh— the SPIFFE authority anda one-time script that trusts SPIRE and binds the agent's SPIFFE ID to a
federated-jwtclient.Testing
make tutorial-checkgreen: all 19 modules plus the capstone, against the livetutorial Keycloak.
make tutorial-check-spiregreen: module 16 against the SPIRE overlay, from acold start.
cargo fmt,clippy -D warningsandcargo test -p cpex-tutorialclean;hugobuilds, and the six recipe anchors were checked against the generated ids.
Notes for reviewers
stays a single Keycloak. See
16-workload.mdfor the two commands.restrictis intentionally not covered. It shapes which backends a hostrouter selects, and the tutorial harness has no router — a faithful module would
mean building one. Module 18 teaches the
data.*tree thatrestrictreads from,so the groundwork is there if we add it later.