docs: add three-party flow examples with mermaid diagrams#25
Merged
Conversation
- README: Add mermaid sequence diagram showing PS-Asserted flow with user consent, self-hosted agent setup, resource-side verification example, agent-calls-resource example, and step-by-step walk-through - Getting Started: Add protocol participants section (AP role explained), key types & cryptography, supported flows table, three-party deep dive with detailed HTTP headers and consent model, resource-side example with TrustedAuthTokenIssuers, and enrollment comparison table - Both files: Show PS trust relationship explicitly via TrustedAuthTokenIssuers in resource verification options
There was a problem hiding this comment.
Pull request overview
Adds end-to-end documentation for the three-party (PS-Asserted) flow, including mermaid sequence diagrams and server/client examples, and introduces a lightweight plan folder documenting the research and execution plan for these doc updates.
Changes:
- Expanded README three-party flow section with a mermaid diagram plus agent/resource/client examples and a step-by-step walkthrough.
- Extended
docs/getting-started.mdwith protocol participant explanations (AP/PS/AS), cryptography/key concepts, supported flows, and a detailed three-party deep dive. - Added
.agent/plans/...research + phased implementation plan files for the documentation initiative.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds PS-Asserted flow overview, diagram, and illustrative code snippets for agent/resource/client. |
| docs/getting-started.md | Adds deep-dive protocol documentation, diagrams, examples, and updated “Next Steps” links. |
| .agent/plans/2026-05-28-readme-getting-started-update/research.md | Captures spec terminology and supporting research for the doc changes. |
| .agent/plans/2026-05-28-readme-getting-started-update/implementation-plan.md | Phased plan with DoD checkboxes for the doc updates and cross-references. |
Copilot's findings
- Files reviewed: 4/4 changed files
- Comments generated: 9
Comment on lines
73
to
+88
| ```csharp | ||
| using AAuth.Crypto; | ||
| using AAuth.HttpSig; | ||
| using AAuth.Server; | ||
| using AAuth.Tokens; | ||
|
|
||
| // Hosted service: generate key at startup, self-issue tokens | ||
| var key = AAuthKey.Generate(); | ||
| const string Kid = "svc-key-1"; | ||
| var issuer = "https://my-service.example"; | ||
|
|
||
| // Publish agent metadata so resources can discover the JWKS | ||
| app.MapAAuthAgentWellKnown(new AAuthAgentMetadataOptions | ||
| { | ||
| Issuer = issuer, | ||
| SigningKeys = new Dictionary<string, AAuthKey> { [Kid] = key }, | ||
| }); |
| // Trust specific PSes — the resource verifies auth tokens against their JWKS. | ||
| // Omit to accept any PS (claims are namespaced by issuer per spec). | ||
| TrustedAuthTokenIssuers = new HashSet<string> { "https://ps.example" }, | ||
| }); |
Comment on lines
+173
to
+176
| ``` | ||
| HTTP/1.1 401 Unauthorized | ||
| AAuth-Requirement: requirement=auth-token;resource_token="<resource-token>" | ||
| ``` |
| AAuth-Requirement: requirement=auth-token;resource_token="<resource-token>" | ||
| ``` | ||
|
|
||
| The resource token contains: issuer (resource URL), audience (PS URL), agent identifier, agent key thumbprint (`jkt`), and requested scope. |
| **5. Consent: immediate vs deferred** | ||
|
|
||
| - **Immediate**: User is online and grants consent in real time. PS returns the auth token directly. | ||
| - **Deferred**: User is not available. PS returns `202 Accepted` with `requirement=interaction` and a `pending` URL. The agent polls until the user consents (SDK handles this via `InteractionWaitMode`). |
| - `iss`: PS URL | ||
| - `aud`: Resource URL | ||
| - `sub`: User identifier (stable, PS-scoped) | ||
| - `cnf.jkt`: Agent's key thumbprint (proof-of-possession binding) |
| The resource verifies the auth token: | ||
| - Fetches the PS's JWKS (from `{iss}/.well-known/aauth-person.json`) and verifies the JWT signature | ||
| - Checks `aud` matches its own identifier | ||
| - Confirms `cnf.jkt` matches the signing key on the HTTP request (proof-of-possession) |
| TrustedAuthTokenIssuers = new HashSet<string> { "https://ps.example" }, | ||
| }); | ||
|
|
||
| // Protected endpoint — if agent lacks auth, middleware issues 401 + resource_token |
| | Key lifecycle | Generated at startup, published via JWKS | Generated in keystore at enrollment, loaded by handle | | ||
| | Token acquisition | Self-signed at startup | AP refresh endpoint (automatic via SDK) | | ||
| | Metadata | Publishes `/.well-known/aauth-agent.json` | AP publishes it | | ||
| | Code entry point | `MapAAuthAgentWellKnown()` + `AgentTokenBuilder` | `AAuthClientBuilder.Bootstrap().EnrolAsync()` | |
- Add WebApplication setup to README agent example (missing app context) - Add UseAAuthChallenge middleware to resource examples (issues 401 + resource_token when agent lacks auth token) - Fix AAuth-Requirement header format: resource-token (hyphen) per spec - Fix resource token claim name: agent_jkt (not jkt) - Fix auth token PoP claim: cnf.jwk (not cnf.jkt) per spec - Fix SDK type reference: InteractionHandlingOptions (not InteractionWaitMode) - Fix Bootstrap call shape: Bootstrap(url, agentId) takes arguments - Add AAuth.Crypto using to README resource example
Add Resource-Managed and Federated access modes to the table. Clarify the distinction between signing modes (how the agent proves identity) and access modes (how authorization is decided). Add note explaining why Identity-Based access supports hwk despite hwk being pseudonymous.
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 end-to-end three-party (PS-Asserted) flow examples to the README and Getting Started guide, including mermaid diagrams, code examples for all three parties, and a detailed protocol walk-through.
Changes
README.md
TrustedAuthTokenIssuersdocs/getting-started.md
TrustedAuthTokenIssuersTerminology
All terminology verified against draft-hardt-oauth-aauth-protocol (draft-01):
resource_token/auth_token(not "access token")