fix(ui_sso): resolve highest privilege Entra app role, not first in claim - #36728

TLDR

Problem this solves:

• Users with multiple Entra app roles get an arbitrary one
• Entra does not guarantee roles claim ordering
• proxy_admin can silently lose to internal_user
• Only Microsoft SSO is affected; generic/Okta already ranks correctly

How it solves it:

• Reuse the existing privilege hierarchy for app roles
• Highest privilege wins, independent of claim order
• Extract the selection into a testable function
• Single-role, unknown-role, and empty-claim behaviour unchanged

User Flow

Before: a platform admin who is also a member of a regular team group signs in and lands with read-only access, unable to administer the proxy

1. The Entra admin creates two app roles on the LiteLLM enterprise application, proxy_admin and internal_user, and assigns one group to each
2. A user is a member of both groups, the admin group and their own team's group
3. The user opens https://litellm-domain/ui and completes the Microsoft sign-in
4. They land on the UI with internal-user access: no Teams or Models administration, and key creation is refused
5. Whether this happens is luck. Another user with the same two groups, or the same user in a different tenant, may land as proxy_admin instead, because the role that wins depends on the order Entra listed the roles in
6. The admin removes the user from their team group to work around it, which also removes them from that team

After: the same user signs in and lands with the higher privilege role, keeping their team membership

1. The Entra admin creates the same two app roles and assigns the same two groups
2. A user is a member of both groups, the admin group and their own team's group
3. The user opens https://litellm-domain/ui and completes the Microsoft sign-in
4. They land on the UI as a proxy admin, with the full administration surface, and remain a member of their team
5. The result is the same on every sign-in and for every user with that pair of groups, regardless of how Entra ordered the roles

Relevant issues

Linear ticket

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Screenshots / Proof of Fix

Before, against a live proxy on v1.95.0

This reproduces on a real tenant, not a constructed claim. The user below is a member of two Entra groups assigned to this app, one mapped to the internal_user app role and one mapped to proxy_admin_viewer. Hostname, tenant, app id and email are redacted; the role values are verbatim.

Minting a real Entra access token for the app and decoding its roles claim shows Entra listing internal_user first:

$ TOKEN=$(<mint an Entra token for the LiteLLM app>)
$ python3 -c '
import base64, json, sys
payload = sys.stdin.read().strip().split(".")[1]
payload += "=" * (-len(payload) % 4)
c = json.loads(base64.urlsafe_b64decode(payload))
print("roles claim :", json.dumps(c.get("roles")))
print("aud         :", c.get("aud"))
' <<< "$TOKEN"
roles claim : ["internal_user", "proxy_admin_viewer"]
aud         : api://<app-id>

The running proxy resolved that user to the lower privilege role, dropping proxy_admin_viewer:

$ curl -sS https://<proxy-host>/user/info -H "Authorization: Bearer $TOKEN"
user_role   : internal_user
user_email  : <redacted>
teams       : 3 team(s)

That is the bug end to end: the user holds proxy_admin_viewer in Entra, the token carries it, and the proxy stored internal_user purely because Entra happened to list it first.

After, same claim through the patched resolver

At f7d1524, the real claim above resolves the other way:

$ uv run python -c '
from litellm.proxy.management_endpoints.ui_sso import MicrosoftSSOHandler
claim = ["internal_user", "proxy_admin_viewer"]
print("claim   :", claim)
print("resolved:", MicrosoftSSOHandler.get_user_role_from_app_roles(claim).value)
'
claim   : ['internal_user', 'proxy_admin_viewer']
resolved: proxy_admin_viewer

Remaining half, the interactive sign-in

The sign-in itself needs a browser, so I cannot capture it headlessly. Steps to reproduce both halves against a local proxy, if you want the UI screenshots:

1. Add http://localhost:4000/sso/callback to the app registration's redirect URIs
2. Assign one user two app roles whose values are internal_user and proxy_admin_viewer, via two groups or directly
3. Export MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT and PROXY_BASE_URL=http://localhost:4000
4. On d86336a (this PR's merge base), run python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml --detailed_debug --reload 2>&1 | tee litellm.log
5. Open http://localhost:4000/ui, sign in as that user, and expect to land without the admin surface. curl -sS localhost:4000/user/info -H "Authorization: Bearer $TOKEN" reports internal_user
6. Check out f7d1524, restart the proxy, and sign in again as the same user. Expect the admin viewer surface, and /user/info reporting proxy_admin_viewer

Type

🐛 Bug Fix

Caveats (if any)

• org_admin, team, customer are unranked by the existing hierarchy
• Those now resolve deterministically, not by claim order
• Worth confirming whether org_admin should be ranked

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR