proposed core.backchannel-logout

Tell each app a browser session signed in to that the session ended

A browser session ends: the person signs out at an app (RP-initiated logout) or at POST /auth/logout, an admin revokes it, a key is retired in an emergency, or it lapses. Every caller ends sessions through the session service, and in the transaction that marks a session revoked and takes the clients it served, QAuth writes one user.client_session_ended event per client with a backchannel_logout_uri to the event store: the notices cannot be lost once the end commits, and the end never waits for them. The delivery role fans each event out to its client when the client registered a backchannel_logout_uri, and delivers it at least once: it reads the client again, has the signer role sign a logout token (typ logout+jwt, with iss, aud, iat, a two-minute exp, a jti every retry keeps, the back-channel logout event, sub and sid, and no nonce), and POSTs it as the logout_token form field through the egress client, which checks the destination's addresses again. A 2xx delivers it; a failure that may pass is retried on the delivery role's schedule; any other answer ends the delivery as failed. A failed delivery is recorded and counted, and changes nothing about the sign-out.

What this view shows

the end of browser sessions through the session service, the notices it queues, and the delivery of one logout token to one app, from the fan-out through every attempt to its last.

Open world: what is not drawn here is not ruled out. Only the guarantees below are binding.

Left out of this view:

who ends a session and what the caller answers: RP-initiated logout (core.logout), POST /auth/logout (core.logout-token), the expiry sweep (idle and expired sessions), and the account's sign out everywhere, an admin's revocation and the emergency retirement of a key once their routes land; each ends sessions through the session service, and each pairs it with the token revocation it owes
the delivery role's own mechanics (#460): the poll, the lease of a claimed row, a node that stops mid-attempt (the row comes due again, so a token may arrive twice and the app drops the repeat by sid), the backoff and the attempt limit (EVENT_DELIVERY_MAX_ATTEMPTS, EVENT_DELIVERY_RETRY_*), and the delivery history and metrics
registering the URI: dynamic registration and CIMD documents check it through the egress client and refuse a URI that is not https, carries credentials or a fragment, or resolves to a private, loopback or other non-public address, even for a development client; only the seed manifest, an operator's, sets a URI as an admin, which the deployment allowlist may then let reach a private address
the signer's own refusals: the delivery role may sign a logout+jwt with the realm's ID token key and a secevent+jwt with its event_signing key, and nothing else, and its handle holds no key
front-channel logout: QAuth has none (ADR-019 Decision 4)

The main story

When: The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client is enabled, not suspended, of the event's realm, and still has its URI, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left.

End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit
The notices wait in the event store: the delivery role's next poll reaches the event
Match the event to its client: one delivery row for this client and this session
Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt
Read the client as it is now: the client still takes the notice
Have the signer role sign the logout token: the signer answers a compact JWS
Check the destination again through the egress client: the destination passes
POST the logout token to the app: the app answers 2xx

Result: The app logged the session out.

The flow

Show failure paths and “the user closes the page”

blue line: the main storyred dashed line: a failure path (shown with “Show failure paths”)dotted line: decided by a rule, nobody actsdashed grey box: the server decides, nothing is shown

What each step answers

Step	The outside world sees
The app logged the session out delivered	body: {"delivery":"delivered"}
The app refused the logout token refusedByApp	body: {"delivery":"failed","errorClass":"http_status"}
Every attempt failed failedForGood	body: {"delivery":"failed","errorClass":"the last attempt's"}
Nothing is sent to a client that no longer exists droppedClientGone	body: {"delivery":"failed","errorClass":"client_deleted"}
Nothing is sent to a disabled or suspended client droppedClientInactive	body: {"delivery":"failed","errorClass":"client_inactive"}
Nothing is sent to a client that dropped its URI droppedNoLogoutUri	body: {"delivery":"failed","errorClass":"logout_uri_removed"}
Nothing is sent when the client requires a sid the notice lacks droppedSidUnavailable	body: {"delivery":"failed","errorClass":"sid_unavailable"}

How it decides what happens next

Match the event to its client

#	If	Then
1	no destination matches: the client registered no URI, so it gets nothing	A client without a back-channel logout URI gets nothing
2	one delivery row for this client and this session	Wait for the delivery role to claim the delivery

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`noUriAtFanOut`	`notSentNoLogoutUri`	768 of 1536
2	otherwise	`awaitingAttempt`	768 of 1536

noUriAtFanOut: uriAtFanOut == 'none'

Check the destination again through the egress client

#	If	Then
1	the egress client refuses the address: nothing is sent, and a later attempt checks again	Record the failed attempt
2	the destination passes	POST the logout token to the app

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`destinationBlocked`	`attemptFailed`	54 of 144
2	otherwise	`posting`	90 of 144

destinationBlocked: address == 'private' and not (uriSetBy == 'admin' and allowlisted == true)

Record the failed attempt

#	If	Then
1	that was the last attempt	Every attempt failed
2	attempts are left	Wait for the next attempt

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`attemptsSpent`	`failedForGood`	456 of 912
2	otherwise	`waitingToRetry`	456 of 912

attemptsSpent: attempts == 'spent'

Every way it can end

It ends with	When	What happens
The app logged the session out ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client is enabled, not suspended, of the event's realm, and still has its URI, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: one delivery row for this client and this session Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt Read the client as it is now: the client still takes the notice Have the signer role sign the logout token: the signer answers a compact JWS Check the destination again through the egress client: the destination passes POST the logout token to the app: the app answers 2xx
The app refused the logout token ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client is enabled, not suspended, of the event's realm, and still has its URI, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 400, or another status no retry changes: a redirect, 401, 403, 404, the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: one delivery row for this client and this session Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt Read the client as it is now: the client still takes the notice Have the signer role sign the logout token: the signer answers a compact JWS Check the destination again through the egress client: the destination passes POST the logout token to the app: the app answers 400 or another status no retry changes
Every attempt failed ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client is enabled, not suspended, of the event's realm, and still has its URI, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), this was its last attempt	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: one delivery row for this client and this session Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt Read the client as it is now: it fails, because the client cannot be read now Record the failed attempt: that was the last attempt
Nothing is sent to a client that no longer exists ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client was deleted since, or the row is of another realm, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: one delivery row for this client and this session Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt Read the client as it is now: the client is gone, or of another realm
Nothing is sent to a disabled or suspended client ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client was disabled or suspended since, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: one delivery row for this client and this session Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt Read the client as it is now: the client is disabled or suspended
Nothing is sent to a client that dropped its URI ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client dropped its backchannel_logout_uri since, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: one delivery row for this client and this session Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt Read the client as it is now: the client no longer has a backchannel_logout_uri
Nothing is sent when the client requires a sid the notice lacks ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client is enabled, not suspended, of the event's realm, and still has its URI, the client set backchannel_logout_session_required, the event names no sid, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: one delivery row for this client and this session Wait for the delivery role to claim the delivery: the delivery role claims the row, counting one attempt Read the client as it is now: the client requires a sid and the event names none: nothing is sent
A client without a back-channel logout URI gets nothing ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client registered none, or was deleted, disabled or suspended, before the fan-out, the client is enabled, not suspended, of the event's realm, and still has its URI, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends and its notices are queued, in the same commit The notices wait in the event store: the delivery role's next poll reaches the event Match the event to its client: no destination matches: the client registered no URI, so it gets nothing
The session ended, and served no app ends here	The session never got as far as an app, or none of its apps registered a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client is enabled, not suspended, of the event's realm, and still has its URI, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: the session ends; it served no app with a backchannel_logout_uri, so nothing is queued
Nothing ended ends here	The session had signed the person in to at least one app with a backchannel_logout_uri, the client has a backchannel_logout_uri when the delivery role lists its destinations, the client is enabled, not suspended, of the event's realm, and still has its URI, the client did not set backchannel_logout_session_required, the event names the session by its sid, as every session QAuth creates has one, the client's own registration set the URI (dynamic registration, a CIMD document), every address the host resolves to now is public, the deployment allowlist names neither the host nor its range for the client's realm, the app answers 200, or 204 as some frameworks do (§2.8), the delivery has attempts left	End the sessions, and queue a notice for each client they served: it fails, because Postgres cannot store the change: the transaction rolls back

Each row is also a generated test: set the starting situation, send the events, expect the ending.

What is guaranteed

These hold in all 15942 situations the model can reach, from 3072 different starting situations.

A notice is queued only in the transaction that ends its session, so it is never sent for a session that did not end
A session that served an app never ends without its notices queued, whatever happens to the node next
Every delivery outcome, a failed one included, comes after the session ended; none of them ends or keeps a session
Only a client the session served gets a delivery
A logout token goes only to an active client that has a back-channel logout URI at the fan-out and at the attempt
A logout token never reaches a private or loopback address, unless an admin set the URI and the deployment allowlist names it for the client's realm
A client that requires a sid never gets a logout token without one
What is posted is a token the signer role signed
A delivery counts as delivered only when the app answered the POST

Exact rules

Id	Never
`a-notice-commits-with-the-end`	`queued and not sessionEnded`
`an-end-is-never-lost`	`sessionEnded and not servedNone and not queued`
`delivery-never-undoes-the-sign-out`	`state in ['delivered', 'refusedByApp', 'failedForGood', 'droppedClientGone', 'droppedClientInactive', 'droppedNoLogoutUri', 'droppedSidUnavailable', 'notSentNoLogoutUri'] and not sessionEnded`
`nothing-for-an-app-the-session-never-served`	`deliveryRow and servedNone`
`no-token-without-a-uri`	`posted and (noUriAtFanOut or clientAtAttempt != 'active')`
`no-private-address-for-a-client-registration`	`posted and destinationBlocked`
`sid-when-the-client-requires-it`	`posted and sidUnavailable`
`signed-before-sent`	`posted and not signed`
`delivered-means-posted`	`state == 'delivered' and not posted`

Reference

All transitions (24)

From	Event	Guard	To	Effects	Taken
`endingSessions`	`DONE`	`servedNone`	`nothingToNotify`	`endSessions`	yes
`endingSessions`	`DONE`		`queued`	`endSessions` `queueNotices`	yes
`endingSessions`	`FAIL.server`		`endFailed`		yes
`queued`	`FAN_OUT`		`fanningOut`		yes
`fanningOut`	`rule 1`	`noUriAtFanOut`	`notSentNoLogoutUri`		yes
`fanningOut`	`rule 2`		`awaitingAttempt`	`writeDelivery`	yes
`awaitingAttempt`	`ATTEMPT`		`readingClient`		yes
`readingClient`	`DONE`	`clientGone`	`droppedClientGone`		yes
`readingClient`	`DONE`	`clientInactive`	`droppedClientInactive`		yes
`readingClient`	`DONE`	`uriDropped`	`droppedNoLogoutUri`		yes
`readingClient`	`DONE`	`sidUnavailable`	`droppedSidUnavailable`		yes
`readingClient`	`DONE`		`signing`		yes
`readingClient`	`FAIL.server`		`attemptFailed`		yes
`signing`	`DONE`		`checkingDestination`	`signToken`	yes
`signing`	`FAIL.server`		`attemptFailed`		yes
`checkingDestination`	`rule 1`	`destinationBlocked`	`attemptFailed`		yes
`checkingDestination`	`rule 2`		`posting`		yes
`posting`	`DONE`	`answeredOk`	`delivered`	`postToken`	yes
`posting`	`DONE`	`answeredRefused`	`refusedByApp`	`postToken`	yes
`posting`	`DONE`		`attemptFailed`	`postToken`	yes
`posting`	`FAIL.network`		`attemptFailed`	`postToken`	yes
`attemptFailed`	`rule 1`	`attemptsSpent`	`failedForGood`		yes
`attemptFailed`	`rule 2`		`waitingToRetry`		yes
`waitingToRetry`	`RETRY`		`readingClient`	`waitForRetry`	yes