feat(agents): authenticate Entra identities and delegated requests

[joshua-berri]

TLDR

Problem this solves:

• Managed Entra agents cannot authenticate for inference
• Agent calls need current permissions and correct target limits

How it solves it:

• Connect verified identities to existing authorization and accounting
• Resolve actual models and targets before enforcing permissions
• Preserve ordinary agents and trusted custom-auth callers

Adds managed Entra authentication, bounded inference access, verified human delegation, and caller/target attribution. Authorization uses the same model selection as inference handlers and reads current target policy even when a worker's registry is stale

Stack 3/9, targeting main. #43720 (identity contracts) and #43721 (permissions) are merged. This PR contains runtime integration only, with 2,383 additions and 265 deletions across 42 files. #43723 adds registration, #43724 budgets, and #43725–#43728 SCIM contracts, operations, activation, and dashboard support. Published descendants still target their immediate predecessors; this repair does not restack them

User Flow

Before: a registered agent's Entra token cannot authenticate for inference

1. Obtain an Entra token for an enabled agent allowed to use haiku-a
2. Send POST https://litellm-domain/v1/chat/completions with that bearer token and {"model":"haiku-a","messages":[{"role":"user","content":"hi"}]}
3. The request returns HTTP 401, User doesn't exist in db
4. Sending the same request with the disallowed haiku-b also returns HTTP 401

After: the same agent can use its allowed model and cannot use ungranted models

1. Obtain an Entra token for an enabled agent allowed to use haiku-a
2. Send POST https://litellm-domain/v1/chat/completions with that bearer token and {"model":"haiku-a","messages":[{"role":"user","content":"hi"}]}
3. The request returns HTTP 200 with the provider's response
4. Sending the same request with the disallowed haiku-b returns HTTP 403 without calling the provider

Relevant issues

Splits the approved scope from #43149 and #43459. The ordered stack #43720, #43721, #43722, #43723, #43724, #43725, #43726, #43727, #43728 collectively replaces #43149, #43229, #43230 and #43459; this PR covers runtime integration only

Affected release

Linear ticket

Resolves LIT-8958

Pre-Submission checklist

• I have added meaningful tests
• All affected tests pass locally, with inherited failures documented below
• My PR passes all required CI/CD checks
• This PR isolates the runtime portion of the approved stack
• Greptile confidence is at least 4/5 before maintainer review

Verification

Current head dd07ec807d1bf703633bb640fb10abfdd1b8d8ec, merge base 3930c5bab664dc506af05be6a1bc09575870bf0d

The protected manifest was derived from changed production paths and their mapped tests before editing. The final 39-file run produced 4,932 passed, 5 failed, and 3 skipped. All five failures also reproduce on main: four Google live OpenAPI schema assertions and one asynchronous spend-callback ordering failure. No unrelated fixes or budget changes are included

Whole-production Ruff, test-tree lint, changed-production formatting, strict-rule, type-discipline, test-quality, and canonical basedpyright gates pass locally. The OpenAPI snapshot and import checks also pass

Local changed executable-line coverage is 259/262 (98.85%). Touched-function branch coverage is 617/778 (79.31%), including unchanged branches in large legacy functions. The managed authorization module has 100% line and branch coverage. Three changed lines remain uncovered: a defensive missing-logger return, an empty pre-initialization registry adapter, and the unreachable exhaustive-match assertion. These measurements are separate from hosted repository-wide coverage

Current-tip Veria and Bugbot reviews are clean. Greptile is 5/5 and explicitly withdrew both database-access findings after confirming the authoritative revocation contract. No actionable concerns remain across those three reviewers

Hosted Codecov reports the same 259/262 changed executable lines (98.85%); the three gaps match local coverage. The final report is complete after the coverage-producing jobs finished; repository-wide coverage is 82.46%

All ten GitHub-required checks pass. The optional MCP OAuth workflow awaits approval for the protected e2e-changed environment. Other CI failures are the unchanged-lockfile OSV vulnerabilities, the four Google schema assertions reproduced on main, and two CodeQL hashing alerts. Both reported taint paths require a truthy key from a JWT principal that explicitly carries api_key=None and token=None; regression assertions confirm these values. Actual password hashing is unchanged. These alerts are explained, not suppressed or dismissed; security adjudication remains pending

Independent source-build verification is complete at this head. Real Entra inference, ordinary-agent compatibility, custom authentication, stale-registry controls, revocation, CLI enrollment and delegation pass. The extra A2A body-model case remains a documented rejection, not a passing invocation. This PR is not being declared fully ready while the CodeQL flags await adjudication

Screenshots / Proof of Fix

Independent verification compared source builds at the exact hashes below, with imports resolved from their respective worktrees. PostgreSQL databases were isolated (db_bE and db_hG), and port 4000 was untouched

Managed bindings were seeded directly with SQL because the registration API belongs to #43723. Agent A was enabled, autonomous, bound to a real Microsoft Entra application requiring Agent.Invoke, and granted only model haiku-a. JWT issuer, audience and Microsoft JWKS validation were configured. Both aliases haiku-a and haiku-b route to the real paid anthropic/claude-haiku-4-5 provider; the grant is what distinguishes access. Ordinary agent O was granted haiku-a

The same real Entra token was used for allowed and denied requests. The commands below preserve the captured request bodies and use descriptive names for private credential files. Outputs are sanitized response excerpts; the baseline service-principal identifier is redacted. The Responses output limit is intentionally small, so an HTTP 200 response can report status=incomplete

PROXY_BASE_URL=http://localhost:45780
PROXY_HEAD_URL=http://localhost:45790
ENTRA_TOKEN_FILE=~/verify/.replay/A.tok
BASE_KEY_FILE=~/verify/.replay/base-3930c5ba.okey
HEAD_KEY_FILE=~/verify/.replay/head-dd07ec80.okey

The final captured processes were baseline PID 40039 and head PID 40040, started at 2026-09-30 19:48:49 UTC. They were stopped after capture. Delayed spend inspection confirmed provider success rows for each allowed head request and ordinary-key control, with no provider success for the denied requests

Before (3930c5b)

Chat completions

1. Managed agent, allowed model

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/chat/completions" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 401, response excerpt:

   {"error":"Authentication Error, User doesn't exist in db. 'user_id'=<sp-id>. Create user via `/user/new` call."}

2. Same managed token, disallowed model

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/chat/completions" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-b","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 401, response excerpt:

   {"error":"Authentication Error, User doesn't exist in db. 'user_id'=<sp-id>. Create user via `/user/new` call."}

3. Ordinary agent control

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/chat/completions" -H "Authorization: Bearer $(cat "$BASE_KEY_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","content":"Hello! How can I"}

Responses

1. Managed agent, allowed model

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/responses" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","input":"hi","max_output_tokens":16}'

   Observed HTTP 401, response excerpt:

   {"error":"Authentication Error, User doesn't exist in db. 'user_id'=<sp-id>. ..."}

2. Same managed token, disallowed model

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/responses" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-b","input":"hi","max_output_tokens":16}'

   Observed HTTP 401, response excerpt:

   {"error":"Authentication Error, User doesn't exist in db. 'user_id'=<sp-id>. ..."}

3. Ordinary agent control

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/responses" -H "Authorization: Bearer $(cat "$BASE_KEY_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","input":"hi","max_output_tokens":16}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","status":"completed","text":"Hello! \ud83d\udc4b How can I help you today?"}

Messages

1. Managed agent, allowed model

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/messages" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 401, response excerpt:

   {"error":"Authentication Error, User doesn't exist in db. 'user_id'=<sp-id>. ..."}

2. Same managed token, disallowed model

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/messages" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-b","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 401, response excerpt:

   {"error":"Authentication Error, User doesn't exist in db. 'user_id'=<sp-id>. ..."}

3. Ordinary agent control

   curl -s -w '%{http_code}' "$PROXY_BASE_URL/v1/messages" -H "Authorization: Bearer $(cat "$BASE_KEY_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","text":"Hello! \ud83d\udc4b"}

After (dd07ec8)

Chat completions

1. Managed agent, allowed model

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/chat/completions" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","content":"Hello! \ud83d\udc4b"}

2. Same managed token, disallowed model

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/chat/completions" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-b","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 403, response excerpt:

   {"error":"The requested model 'haiku-b' is not available for this API key, or the model name is invalid. Check the models available to you and try again."}

3. Ordinary agent control

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/chat/completions" -H "Authorization: Bearer $(cat "$HEAD_KEY_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","content":"Hello! \ud83d\udc4b"}

Responses

1. Managed agent, allowed model

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/responses" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","input":"hi","max_output_tokens":16}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","status":"incomplete","text":"# Hi there! \ud83d\udc4b\n\nHow's it going? What can "}

2. Same managed token, disallowed model

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/responses" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-b","input":"hi","max_output_tokens":16}'

   Observed HTTP 403, response excerpt:

   {"error":"The requested model 'haiku-b' is not available for this API key, or the model name is invalid. Check the models available to you and try again."}

3. Ordinary agent control

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/responses" -H "Authorization: Bearer $(cat "$HEAD_KEY_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","input":"hi","max_output_tokens":16}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","status":"incomplete","text":"Hey! \ud83d\udc4b How's it going? What can I help y"}

Messages

1. Managed agent, allowed model

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/messages" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","text":"# Hey there! "}

2. Same managed token, disallowed model

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/messages" -H "Authorization: Bearer $(cat "$ENTRA_TOKEN_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-b","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 403, response excerpt:

   {"error":"The requested model 'haiku-b' is not available for this API key, or the model name is invalid. Check the models available to you and try again."}

3. Ordinary agent control

   curl -s -w '%{http_code}' "$PROXY_HEAD_URL/v1/messages" -H "Authorization: Bearer $(cat "$HEAD_KEY_FILE")" -H 'content-type: application/json' -d '{"model":"haiku-a","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

   Observed HTTP 200, response excerpt:

   {"model":"haiku-a","text":"# Hey there! "}

Additional live verification

These cases used the same source hashes, real HTTP requests, isolated databases and a real HTTP echo agent as the A2A upstream. Managed-only controls have no equivalent admitted managed principal on the baseline

Case	Baseline observation	Current-head observation
Ordinary A2A agent, master and own key	200 / 200	200 / 200
Agent-bound ordinary key: expensive URL, cheap body, repeated	200 / 200	200 / 429 naming expensive target
Managed A2A without body model, repeated	Managed JWT unavailable	200 / 429; expensive target charged 0.25
Managed A2A with either cheap or expensive body model	Managed JWT unavailable	403; model allowlist rejects extra field; zero upstream hits
Custom-auth grant to managed target, then denied credential	401 / 401	200 / 403; unknown credential 401
Stale ordinary registry entry after managed policy saved	Unrestricted, disabled and revoked cases reached upstream	Each denied 403; explicitly granted caller 200
Virtual key bound to managed agent, chat and A2A	403 / 403	403 / 403
Revoke binding, disable agent, change client; restore	Managed JWT unavailable	403 for each denial; restored 200
Policy lookup failure and recovery	Managed JWT unavailable	503 with no upstream call; recovered 200
Real Microsoft CLI sign-in	Login/whoami succeed; no verified-subject enrollment	Callback enrolls verified human before code entry; login/whoami succeed
Delegated model and target permissions	Managed JWT unavailable	Only agent/human intersection allowed; denied targets have zero hits
Delegated spoof, tampered signature, app-only token	Managed JWT unavailable	403 / 401 / 403
Delegated team grant revoked/restored; non-interactive enrollment	Managed JWT unavailable	403 / 200; non-interactive enrollment denied 403
Explicit team: none / permitted / ungranted / disallowed model	Existing team-header resolver	200 / 200 / 403 / 403 with fallback_to_db_teams: true

The team-header setting is required when the real token has no team claim; this resolver is unchanged from main. The fault hook intentionally makes the shared policy lookup fail, so ordinary callers also return 503 under that injected outage. This confirms the documented writer-availability dependency; normal ordinary-agent controls remain 200

Type

New Feature
Bug Fix

Caveats (if any)

Severe

• Managed targets require current database policy; lookup outages fail closed
• Managed JWT admission performs authoritative reads and conditional authentication writes

Medium

• Registration API ships in feat(agents): add identity registration and dashboard controls #43723; verification seeds bindings directly
• Dependency and schema-test failures also exist on main
• Managed A2A rejects an extraneous, ungranted body model
  • Native A2A without that field succeeds and respects target limits

Low

• Descendant stack branches need a separate restack after squash merge

Final Attestation

• Security-alert adjudication and remaining optional CI disposition complete

---

Note

High Risk
Changes core JWT authorization, team delegation, budget fail-closed behavior, and permission boundaries for managed agents—security-critical paths with broad proxy surface area.

Overview
Adds a managed-agent JWT admission path that recognizes Entra-bound agent identities, records authentication evidence, restricts them to inference/agent-discovery routes, and blocks virtual-key mapping and MCP token exchange for agent tokens.

Delegated execution picks a granting team from verified human SSO grants (resolve_delegated_agent_team), tightens permission checks for identity-managed agents (including admins), and centralizes invocation prep (prepare_agent_invocation) with per-target fees and invoked_agent_* fields on UserAPIKeyAuth. Custom-auth subjects are marked authenticated_by_custom_auth so they are not treated like DB-reloaded virtual keys.

Attribution and ops: request metadata distinguishes actor vs target vs billing agent; A2A and MCP tool calls stamp model / model_group and MCP tool metadata; spend logs prefer final agent outcomes in session grouping and can charge autonomous agents without a human key. Shared resolve_inference_model aligns managed and proxy model defaults; Microsoft interactive SSO enrolls verified human subjects for delegation.

^{Reviewed by Cursor Bugbot for commit dd07ec8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 1 · PR risk: 0/10

[codecov]

Codecov Report

❌ Patch coverage is 98.85496% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...m/proxy/_experimental/mcp_server/rest_endpoints.py	93.75%	1 Missing ⚠️
litellm/proxy/auth/handle_jwt.py	98.18%	1 Missing ⚠️
litellm/proxy/common_utils/http_parsing_utils.py	94.73%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Confidence Score: 5/5

[Critical risk] Adds authentication and authorization for managed agent identities.

The changes since the previous review appear safe to merge; no new actionable finding was identified.

Summary

The PR adds managed Entra agent authentication, delegated authorization, and request attribution. Since the previous review, the only code change is an explicit return in the inference-model resolver; it introduces no new finding.

_{Reviews (5) · Last reviewed commit: "fix(proxy): make exhaustive model resolu..."}

[joshua-berri]

@greptileai Please review the shared-cache wiring at 5b10f6b. Existing enrollment and target-selection findings remain outside this focused follow-up

[joshua-berri]

bugbot run. Please check the latest cache wiring and retained revocation behavior; broader existing findings remain tracked separately

[cursor]

Stale Bugbot comment from a previous run.

[joshua-berri]

@greptileai @cursor review Please review 0fd4e93c48, including the repaired A2A policy selection and the proxy-test import clarification. Independent live verification is pending

[joshua-berri]

@cursor review Please verify current commit 0fd4e93c48, especially A2A target precedence, custom-auth grants, and CLI subject enrollment

[joshua-berri]

@greptileai Please review current commit 0fd4e93c48 after restacking and fixes; the earlier FastAPI finding has been withdrawn in-thread

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_agent_split_entra_runtime (dd07ec8) with main (41df8cf)¹}

Footnotes

1. No successful run was found on main (50f5cc9) during the generation of this report, so 41df8cf was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[cursor]

Stale Bugbot comment from a previous run.

[joshua-berri]

@greptileai Fixed stale-registry admission in 7e60757407; regressions cover missing grants, disabled targets, outages, and unmanaged success. Please review the current commit

[joshua-berri]

@cursor review Please verify 7e60757407, including authoritative target-policy reads, custom-auth grants, and inference model resolution. Local checks pass; live verification is pending

[cursor]

Stale Bugbot comment from a previous run.

[joshua-berri]

@greptileai Please review dd07ec807d: explicit-return correction and stale-registry fix. See thread replies explaining authoritative policy reads and existing identity-store reuse

[joshua-berri]

@cursor review Please verify final commit dd07ec807d, including target-policy enforcement and explicit model resolution. Local checks pass; independent live verification is pending

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit dd07ec8. Configure here.}

[joshua-berri]

Both hashing alerts require a truthy JWT key, but JWT principals carry api_key=None and token=None. Regressions confirm this; password hashing remains unchanged