Azure AI Gateway & Cost Attribution

ADR-0009: Individual cost attribution from On-Behalf-Of tokens

Context

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:

  1. The identity must be unforgeable. A header such as x-user-id set by the application is whatever the application says it is. It cannot be the basis of a bill.
  2. The application identity must not be lost. Per-user cost is a refinement of per-application cost, not a replacement for it. Application owners still need their own number.
  3. Streaming is the common case for user-facing applications, and the ledger records streamed requests with no tokens, because the policy deliberately never buffers a stream (see §10 of the policy reference). A user dimension that silently omits every streamed request would be worse than none: it would look complete.

Decision

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.

Consequences

Positive

Negative and accepted

Alternatives considered

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.