Skip to content

docs: add new tutorials on identity and static attributes. - #167

Merged
araujof merged 8 commits into
devfrom
feat/identity_tutorial
Aug 15, 2026
Merged

docs: add new tutorials on identity and static attributes.#167
araujof merged 8 commits into
devfrom
feat/identity_tutorial

Conversation

@terylt

@terylt terylt commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

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 --check mode,
wired into make tutorial-check (module 16 has its own make 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

# Module Teaches Cookbook
11 Organizing policy (Groups) factor shared setup into a reusable groups: bundle
12 Delegation subjects subject: user vs subject: this_workload Recipes 1, 3
13 Delegation as a client scope an agent's own client token — subject: client Recipe 5
14 Passthrough forward the caller's token, mint nothing (the zero-leg case) Recipe 4
15 Dual-principal subject: user, actor: client — who authorized vs. who acted Recipe 6
16 Workload identity (SVID) agent authenticates by SPIFFE SVID; two-leg subject: caller_workload Recipe 2
17 Multi-issuer one resolver trusting two IdPs, each validated on its own keys
18 Static attributes operator facts from a data file, read as data.*

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

  • Harness (examples/tutorial/src/):
    • mediate.rsCaller gains extra_credentials + with_credential(header, token)
      and mediate resolves 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.rsmint_client_token (client_credentials), mint_token_in_realm
      (a second issuer), and mint_svid (mints a JWT-SVID off SPIRE).
  • IdP realm (examples/tutorial/idp/):
    • realm-export.json — a cpex-agent confidential client (module 13).
    • partner-export.json — a second realm cpex-partner = a second issuer (module 17).
  • SPIRE overlay (opt-in, module 16 only):
    • docker-compose.spire.yml — SPIRE server + OIDC provider, and Keycloak bumped
      to 26.6.1 with spiffe:v1. Additive over the base compose; modules 0–15/17/18
      don't use it.
    • spire/{server,oidc}/*.conf + spire/setup-spiffe.sh — the SPIFFE authority and
      a one-time script that trusts SPIRE and binds the agent's SPIFFE ID to a
      federated-jwt client.

Testing

  • make tutorial-check green: all 19 modules plus the capstone, against the live
    tutorial Keycloak.
  • make tutorial-check-spire green: module 16 against the SPIRE overlay, from a
    cold start.
  • cargo fmt, clippy -D warnings and cargo test -p cpex-tutorial clean; hugo
    builds, and the six recipe anchors were checked against the generated ids.

Notes for reviewers

  • Module 16 needs the SPIRE overlay + setup, kept opt-in so the base tutorial
    stays a single Keycloak. See 16-workload.md for the two commands.
  • restrict is intentionally not covered. It shapes which backends a host
    router
    selects, and the tutorial harness has no router — a faithful module would
    mean building one. Module 18 teaches the data.* tree that restrict reads from,
    so the groundwork is there if we add it later.

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 araujof left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

araujof

This comment was marked as duplicate.

@araujof
araujof merged commit ebb1b5c into dev Aug 15, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants