Skip to content

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

Open
terylt wants to merge 1 commit into
devfrom
feat/identity_tutorial
Open

docs: add new tutorials on identity and static attributes.#167
terylt wants to merge 1 commit 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
for CI.

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 cross-links its cookbook recipe (both directions), and
modules 6/12 were back-linked to Recipes 1/3.

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

  • Each module runs end-to-end against the live tutorial Keycloak (module 16 also
    against SPIRE), and passes in --check mode (exit 0) for CI.
  • Modules 0–15 re-verified on the bumped 26.6.1 Keycloak — no regressions.
  • cargo fmt + clippy clean; hugo builds with no broken refs (all recipe/reference
    cross-links resolve).

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>
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.

1 participant