Attribution stopped at the application. A consuming application — a claims assistant, an internal copilot — was charged for its tokens, and that was the finest grain the ledger could express. For a shared application with hundreds of users that is not enough: the application owner cannot tell whether spend is broad adoption or three people running batch jobs through a chat window, and finance cannot charge a department that uses a central application.
Three facts constrain any solution:
x-user-id set by the application is
whatever the application says it is. It cannot be the basis of a bill.Consuming applications call the gateway with an On-Behalf-Of (OBO) token — a delegated token the
application obtains for its signed-in user, with the gateway’s API as audience. The gateway already
validates Entra tokens (ADR-0007). In a delegated token appid/azp is still the calling
application, so the existing consumer resolution is unchanged; the user is the token’s oid and the
tenant its tid. One validated credential yields both levels, and neither can be spoofed.
scp or declares
idtyp = user. An app-only token’s oid is a service principal; it is recorded as
userType = "app" with no user rather than being charged as if it were a human.users map.requestId, userId, userTenantId and userType.
The fields are always present (none when the feature is off) so reports never special-case a
missing column, and schema 2 rows simply land in an (unattributed) bucket.(app-only) or
(unattributed) row instead of vanishing.GatewayLlmLogs and API-level LLM logging (token counts only, never message content). API
Management meters the stream natively and writes ApiManagementGatewayLlmLog rows keyed by the
same request id the ledger now records. The shared ledger query joins the two, fills in tokens for
rows the policy could not measure, reprices them from the same rate card, and marks each row with
usageSource = policy, llmlog or none. The hot path is untouched: no stream is buffered.require_delegated. Off, app-only traffic is accepted and visible as
(app-only). Once every application sends OBO tokens, turning it on refuses app-only tokens with
403 delegated_token_required, so nothing can escape user attribution.unmeasured_usage falls
for every consumer, not only the ones that adopt OBO, because the backfill applies to the whole
ledger.acquire_token_on_behalf_of (or equivalent)
per user. See the integration guide.GatewayLlmLogs are only written to the resource-specific
table, so enabling them switches the diagnostic setting to Dedicated mode. GatewayLogs move
from AzureDiagnostics to ApiManagementGatewayLogs. Nothing in this repository queries the
legacy table, but an operator’s own queries might. enable_llm_logs = false keeps the old
behaviour and forgoes the backfill.A trusted header set by the application (x-user-id). Rejected: unverifiable. It reduces a
chargeback to the application’s say-so, and a single misconfigured client charges the wrong person.
Signed user assertions in a custom header. Rejected: re-implements OBO with weaker tooling and a second key to manage.
Replacing the application identity with the user. Rejected: loses the application dimension that existing chargeback depends on, and makes app-only traffic unattributable.
Parsing streamed responses in policy to capture usage. Rejected: reading the body buffers the stream, destroying time-to-first-token — the reason a client streams in the first place.
Requiring stream_options.include_usage and parsing only the final chunk. Rejected for the same
reason: the policy still has to read the body to find the chunk.