feat: add Python OBO sample for Work IQ

[Shakir Fattani (shakir-fattani)]

Adds python/obo/ -- a FastAPI middle-tier service that accepts a frontend's access token, exchanges it for a Work IQ token via the On-Behalf-Of flow, and calls the Copilot Chat REST API through the Work IQ Gateway.

Every existing sample is a public client that signs a user in directly. This is the first middle-tier sample: the user signs in to your frontend, and the service brokers the Work IQ call on their behalf. A frontend token cannot be forwarded as-is -- its aud is your own API, so the Gateway rejects it with
401. Audience is signed into the JWT, so the token must be exchanged, not re-pointed at another resource.

Auth (python/obo/app/auth.py):

• Inbound tokens validated against Entra's JWKS (signature, aud, iss, scp).
• OBO exchange via azure-identity's OnBehalfOfCredential, which is MSAL-backed (it wraps msal.ConfidentialClientApplication underneath).
• Managed identity support, for enterprise security postures that disallow deployed secrets: with AZURE_CLIENT_SECRET unset, the service authenticates using a workload-identity federated credential -- DefaultAzureCredential fetches a token for api://AzureADTokenExchange and supplies it as the client assertion, so no secret ever ships. A client secret remains supported for local development.

Note that DefaultAzureCredential alone cannot perform the exchange: its chain (managed identity, environment service principal, Azure CLI) issues app-only or developer identities, and WorkIQAgent.Ask is delegated-only. It proves the app's identity; the user assertion supplies the user's. Both are required.

Contents:

• python/obo/app/config.py -- env config, fails fast on missing values
• python/obo/app/auth.py -- JWT validation + OBO exchange
• python/obo/app/workiq.py -- async Gateway client (sync + SSE streaming)
• python/obo/app/main.py -- FastAPI routes (/api/chat, /api/chat/stream)
• python/obo/smoke_test.py -- Gateway faked via httpx.MockTransport
• README.md: python/obo/ row added to the sample table; Python 3.10+ added to
  the toolchain list; callout that scripts/admin-setup.sh does not cover this
  sample -- it creates a public client, and OBO needs a confidential one that
  also exposes its own API.

Validation:

• smoke_test.py passes with no credentials and no network: conversation creation, citation parsing, cumulative-to-delta stream conversion, the 403 path surfacing request-id, and the auth gate (missing and malformed tokens both 401 before body validation).
• azure-identity 1.25.3 confirmed to expose client_assertion_func on the async OnBehalfOfCredential.
• NOT yet validated end-to-end against a live tenant. That requires a confidential app registration with admin-consented WorkIQAgent.Ask and a Copilot-licensed user; the wire contract was matched against dotnet/rest/ rather than observed from the Gateway.

[Shakir Fattani (shakir-fattani)]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

Adds a new python/obo/ sample that demonstrates a FastAPI middle-tier service using the Entra On-Behalf-Of (OBO) flow to exchange a frontend access token for a Work IQ token, then calling the Work IQ Gateway Copilot Chat REST endpoints (sync + SSE streaming). This complements the existing “public client” samples by showing the brokered backend pattern required when the frontend token audience is your own API.

Changes:

• Introduces a FastAPI service with inbound JWT validation (JWKS) and OBO exchange via azure-identity OnBehalfOfCredential.
• Implements an async Work IQ Gateway REST client with synchronous chat and SSE streaming (cumulative-to-delta conversion).
• Adds documentation, environment templates, and a no-network smoke test using httpx.MockTransport.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Adds the python/obo/ entry and clarifies that it needs a confidential app registration; adds Python toolchain note.
python/obo/README.md	Full sample documentation: OBO rationale, app registration steps, endpoints, and operational notes.
python/obo/requirements.txt	Declares Python dependencies for FastAPI + auth + HTTP client.
python/obo/smoke_test.py	Adds a self-contained smoke test with a mocked Gateway and basic auth gating checks.
python/obo/app/config.py	Adds environment-backed configuration and derived settings (issuer, JWKS URI, Work IQ base URL).
python/obo/app/auth.py	Implements JWT validation and OBO token exchange (client secret or federated assertion).
python/obo/app/main.py	Defines /api/chat and /api/chat/stream routes and wires auth/token exchange into request handling.
python/obo/app/workiq.py	Implements async REST calls to the Gateway and SSE parsing/delta emission.
python/obo/app/init.py	Marks the app package.
python/obo/.gitignore	Ignores local virtual environments.
python/obo/.env.example	Provides example environment variables and guidance for secretless vs local dev auth.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

python/obo/requirements.txt:8

• httpx2 is only referenced here and isn’t imported anywhere in the sample. The smoke test uses fastapi.testclient (which rides on httpx), and httpx is already a dependency above, so httpx2 looks unnecessary and may break installs if it’s not available.

# Test dependency: starlette.testclient requires httpx2 at runtime.
httpx2>=2.7

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (2)

python/obo/app/main.py:79

• In the chunked/unknown Content-Length path, exceeding the body limit currently returns http.disconnect without sending a 413 response. This makes oversized requests look like a dropped connection (often surfacing as 500) even when the app has not started a response yet.

                        rejected = True
                        # Do NOT send a response here — the inner app may have
                        # already started its response. Returning http.disconnect
                        # causes the inner app to abort cleanly.
                        return {"type": "http.disconnect"}

python/obo/app/config.py:103

• WORKIQ_HOST is validated via exact string match, but the value is not normalized. A common value like https://workiq.svc.cloud.microsoft/ (trailing slash) will fail the allowlist check even though it should be equivalent, causing an avoidable startup ConfigError.

def _validated_workiq_host(host: str) -> str:
    allowed = _allowed_hosts()
    if host not in allowed:
        raise ConfigError(
            f"WORKIQ_HOST {host!r} is not in the allowed list: {allowed}"

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (3)

python/obo/app/main.py:172

• Middleware order means 413 responses generated by _BodySizeLimitMiddleware bypass _SecurityHeadersMiddleware, so oversized-body rejections won’t include the security headers you add to other responses. Swap the add_middleware calls so security headers wrap all responses, including early 413s.

app = FastAPI(title="Work IQ OBO Backend", lifespan=lifespan)
app.add_middleware(_SecurityHeadersMiddleware)
app.add_middleware(_BodySizeLimitMiddleware)

python/obo/smoke_test.py:169

• Allowing a 500 here bakes in non-deterministic behavior for oversized chunked bodies. Once the body-limit middleware consistently returns 413, this assertion should require 413 so regressions are caught.

        assert r.status_code in (413, 500), r.status_code  # 413 or 500 from disconnect

python/obo/app/main.py:88

• In the chunked/slow-path body limiter, returning http.disconnect after sending a 413 can still trigger downstream request-parsing errors that surface as a 500 (your smoke test currently allows this). Instead, after rejecting, stop feeding the body to FastAPI with a clean end-of-body message and suppress any downstream response writes so the client deterministically sees 413.

This issue also appears on line 170 of the same file.

            async def limited_receive() -> dict:  # type: ignore[type-arg]
                nonlocal seen, rejected
                if rejected:
                    return {"type": "http.disconnect"}
                message = await receive()

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (2)

python/obo/app/main.py:180

• The middleware-order comment is inaccurate/confusing: with Starlette/FastAPI add_middleware, the last added middleware is outermost, so _SecurityHeadersMiddleware wraps _BodySizeLimitMiddleware (which is good because 413 responses from the body-size limiter still get the security headers). Update the comment to match the actual order/intent so future edits don’t accidentally break the header guarantee.

# Body-size runs outermost (added last = LIFO), security headers wraps the
# inner app so 413 rejections also carry the security headers.
app.add_middleware(_BodySizeLimitMiddleware)
app.add_middleware(_SecurityHeadersMiddleware)

python/obo/app/main.py:310

• The done SSE frame currently sends a single-space payload (data: ␠). Some SSE clients treat this as non-empty data, which can complicate “done with no payload” handling. Emit an actually-empty data line (data:) instead.

            yield "event: done\ndata: \n\n"

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (1)

python/obo/app/config.py:93

• _validated_workiq_host() normalizes WORKIQ_HOST by stripping a trailing slash, but _allowed_hosts() does not normalize entries from EXTRA_WORKIQ_HOSTS. As a result, an extra host like https://workiq.test/ will never match (it is stored with the slash, but compared against the normalized form), causing a confusing startup ConfigError.

    for raw in extra.split(","):
        host = raw.strip()
        if not host:
            continue
        if not host.startswith("https://"):
            raise ConfigError(
                f"EXTRA_WORKIQ_HOSTS entry {host!r} must use the https:// scheme"
            )
        additions.add(host)
    return _ALLOWED_WORKIQ_HOSTS | frozenset(additions)

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (2)

python/obo/app/config.py:101

• _validated_workiq_host only strips trailing slashes before checking membership in the allowlist. If WORKIQ_HOST includes a path/query/fragment, it can bypass the intended 'host-only' shape checks and also result in an incorrect workiq_base when WORKIQ_PATH is appended. Normalizing WORKIQ_HOST to an origin (scheme + netloc) makes the allowlist unambiguous.

def _validated_workiq_host(host: str) -> str:
    # Normalize trailing slashes so "https://host/" matches "https://host".
    normalized = host.rstrip("/")
    allowed = _allowed_hosts()
    if normalized not in allowed:

python/obo/app/config.py:94

• EXTRA_WORKIQ_HOSTS is documented as a list of gateway hosts, but the current check only enforces the https:// scheme and then stores the full string (minus trailing slash). This allows entries with paths/query/fragment (e.g. https://example.com/evil), which weakens the allowlist intent and can produce unexpected base URLs when WORKIQ_PATH is appended.

This issue also appears on line 97 of the same file.

        if not host.startswith("https://"):
            raise ConfigError(
                f"EXTRA_WORKIQ_HOSTS entry {host!r} must use the https:// scheme"
            )
        additions.add(host.rstrip("/"))