Table of Contents

Protocol flows

Each page here shows one protocol flow as this server actually runs it: every request and every response, in order, with a sequence diagram drawn from the same exchanges. None of it is written by hand. An integration test drives the demo host (src/Fdyay.IdentityServer.Host, with its demo clients and APIs) through the flow, asserting on what comes back, and records the HTTP traffic as it goes; the page is rendered from that recording.

CI runs those tests on every build and compares each rendered page with the one committed here. A page that no longer matches what the server does fails the build, so these pages cannot drift from the code. When a change to the server is meant to change a flow, regenerate the pages and review the diff with the rest of the change:

UPDATE_DOCS=1 dotnet test --filter "Category=DocumentedFlow"

(In PowerShell: $env:UPDATE_DOCS=1; dotnet test --filter "Category=DocumentedFlow".)

Reading a page

  • Placeholders. A value the server makes up — a code, a token, a session id, a nonce, a key — differs on every run, so it is shown as a placeholder named for what it is and numbered by first appearance: {authorization_code_1}, {access_token_2}. The same placeholder is the same value wherever it appears, so a value can be followed from the response that issued it into the requests that present it. Times are shown relative to the token's own iat, as {iat + 3600}. Values the test chose — client ids, secrets, redirect URIs, state, the PKCE verifier — are shown as they are, and match the demo host's configuration.
  • JWTs are shown as a placeholder in the HTTP message and decoded beneath it, header then payload. The signature is never shown.
  • SAML messages are shown the same way, decoded beneath the message that carries them as indented XML.
  • Headers are limited to the ones the protocol is about (Authorization, Content-Type, DPoP, Cookie, Location, Cache-Control, WWW-Authenticate, DPoP-Nonce, Set-Cookie and a few more); HTML pages are not shown.
  • Notes mark what happens off the record: a person using a page, or tokens obtained in an earlier flow.

The host runs as configured in its Program.cs, except that its signing key is kept in memory, so that every recording starts from a single fresh key; where a flow changes anything else, its description says so.

Two pages record a federation, and so two servers: federated sign-in and SAML identity provider to OpenID Connect client. The upstream identity provider is a second instance of the demo host, in the same process at http://idp.partner.example; the browser reaches each server by its host name, and the requests this server sends the provider itself — discovery, keys, a pushed request, the token request — are recorded as they leave it. Both hops are real: the upstream's own endpoints answer, and this server's OpenID Connect and SAML handlers check what comes back. The federation gateway guide is the setup they illustrate.