fix(scim): answer every SCIM route error as a SCIM Error and keep the span's error type
Some checks failed
Cost map pins recheck / rerun-cost-map-guard (push) Has been cancelled
LiteLLM Rust DB / db-queries (push) Has been cancelled
LiteLLM Rust / rust-lint (push) Has been cancelled
LiteLLM Rust / rust-test (push) Has been cancelled
LiteLLM Rust / rust-wheel (push) Has been cancelled
Terraform Modules / fmt, validate, test (aws) (push) Has been cancelled
Terraform Modules / fmt, validate, test (gcp) (push) Has been cancelled
Terraform Provider / gofmt, vet, build, test (push) Has been cancelled
Terraform Provider / Provider endpoints vs proxy OpenAPI schema (push) Has been cancelled

Every 409 on a SCIM route now answers scimType uniqueness, so a duplicate email
that only differs in case gets it too. An unexpected error answers a SCIM Error
with the status phrase and is logged like the handlers' own errors. The OTel
server span reports the ProxyException or a public RequestValidationError the
route raised instead of ScimError
This commit is contained in:
mateo-berri 2026-11-14 10:53:47 -08:00
parent 5e7e687ebe
commit 99d2406a4e
6 changed files with 154 additions and 40 deletions

View file

@ -1,7 +1,7 @@
from collections.abc import Callable, Coroutine, Mapping
from http import HTTPStatus
from types import MappingProxyType
from typing import Final, NamedTuple, TypeAlias
from typing import Final, TypeAlias
from fastapi import Request, Response
from fastapi.exceptions import RequestValidationError
@ -12,7 +12,8 @@ from starlette.exceptions import HTTPException
from typing_extensions import assert_never
from litellm.proxy._types import ProxyException
from litellm.proxy.common_utils.validation_error_body import public_validation_errors
from litellm.proxy.common_utils.validation_error_body import ValidationErrorDetail, public_validation_errors
from litellm.proxy.utils import handle_exception_on_proxy
from litellm.types.proxy.management_endpoints.scim_v2 import SCIMError, ScimErrorDetail, ScimType
SCIM_CONTENT_TYPE: Final = "application/scim+json"
@ -23,33 +24,31 @@ _STATUS_PHRASES: Final = MappingProxyType({status.value: status.phrase for statu
_ScimRouteFailure: TypeAlias = HTTPException | ProxyException | RequestValidationError
def _scim_type(status_code: int) -> ScimType | None:
return "uniqueness" if status_code == HTTPStatus.CONFLICT else None
class ScimError(Exception):
def __init__(
self,
status_code: int,
detail: str,
scim_type: ScimType | None = None,
headers: Mapping[str, str] | None = None,
traced_as: Exception | None = None,
) -> None:
self.status_code: Final = status_code
self.headers: Final = MappingProxyType(dict(headers or {}))
self.error: Final = SCIMError(status=str(status_code), detail=detail, scimType=scim_type)
self.traced_as: Final = traced_as
self.error: Final = SCIMError(status=str(status_code), detail=detail, scimType=_scim_type(status_code))
super().__init__(detail)
class _Reason(NamedTuple):
detail: str
scim_type: ScimType | None
def _reason(detail: object) -> _Reason:
def _readable_detail(detail: object) -> str:
try:
parsed: Final = _DETAIL_ADAPTER.validate_python(detail)
except ValidationError:
return _Reason(str(detail), None)
if isinstance(parsed, str):
return _Reason(parsed, None)
return _Reason(parsed["error"], parsed.get("scimType"))
return str(detail)
return parsed if isinstance(parsed, str) else parsed["error"]
def _detail_before_proxy_exception_stringified_it(exc: ProxyException) -> object:
@ -63,37 +62,49 @@ def _proxy_exception_status_code(exc: ProxyException) -> int:
return int(exc.code) if exc.code.isdecimal() else HTTPStatus.INTERNAL_SERVER_ERROR.value
def _validation_detail(exc: RequestValidationError) -> str:
return "; ".join(
f"{'.'.join(str(part) for part in error['loc'])}: {error['msg']}"
for error in public_validation_errors(exc.errors())
def _validation_detail(errors: tuple[ValidationErrorDetail, ...]) -> str:
return "; ".join(f"{'.'.join(str(part) for part in error['loc'])}: {error['msg']}" for error in errors)
def _scim_error(
status_code: int, detail: object, headers: Mapping[str, str] | None, traced_as: Exception | None
) -> ScimError:
return ScimError(
status_code,
_readable_detail(detail) or _STATUS_PHRASES.get(status_code, str(status_code)),
headers,
traced_as,
)
def _scim_error(status_code: int, detail: object, headers: Mapping[str, str] | None) -> ScimError:
reason: Final = _reason(detail)
def _scim_validation_error(exc: RequestValidationError) -> ScimError:
public_errors: Final = public_validation_errors(exc.errors())
return ScimError(
status_code,
reason.detail or _STATUS_PHRASES.get(status_code, str(status_code)),
reason.scim_type,
headers,
HTTPStatus.UNPROCESSABLE_ENTITY.value,
_validation_detail(public_errors),
traced_as=RequestValidationError(public_errors),
)
def scim_error_from(exc: _ScimRouteFailure) -> ScimError:
match exc:
case HTTPException():
return _scim_error(exc.status_code, exc.detail, exc.headers)
return _scim_error(exc.status_code, exc.detail, exc.headers, None)
case ProxyException():
return _scim_error(
_proxy_exception_status_code(exc), _detail_before_proxy_exception_stringified_it(exc), exc.headers
_proxy_exception_status_code(exc), _detail_before_proxy_exception_stringified_it(exc), exc.headers, exc
)
case RequestValidationError():
return ScimError(HTTPStatus.UNPROCESSABLE_ENTITY.value, _validation_detail(exc))
return _scim_validation_error(exc)
case _:
assert_never(exc)
def _unexpected_scim_error(exc: Exception) -> ScimError:
status_code: Final = _proxy_exception_status_code(handle_exception_on_proxy(exc))
return ScimError(status_code, _STATUS_PHRASES.get(status_code, str(status_code)), traced_as=exc)
def scim_error_response(exc: ScimError) -> JSONResponse:
return JSONResponse(
status_code=exc.status_code,
@ -112,5 +123,7 @@ class ScimRoute(APIRoute):
return await handler(request)
except (HTTPException, ProxyException, RequestValidationError) as exc:
raise scim_error_from(exc) from exc
except Exception as exc:
raise _unexpected_scim_error(exc) from exc
return answer_errors_as_scim

View file

@ -1888,11 +1888,10 @@ async def create_user(
if user.userName:
existing_user = await _table(UserRepository(prisma_client)).find_unique(where={"user_id": user.userName})
if existing_user:
duplicate: Final[ScimErrorDetail] = {
"error": f"User already exists with username: {user.userName}",
"scimType": "uniqueness",
}
raise HTTPException(status_code=409, detail=duplicate)
raise HTTPException(
status_code=409,
detail={"error": f"User already exists with username: {user.userName}"},
)
# Create user in database
user_id: Final = user.userName or str(uuid.uuid4())
@ -3037,11 +3036,10 @@ async def create_group(
existing_team: Final = await _table(TeamRepository(prisma_client)).find_unique(where={"team_id": team_id})
if existing_team:
duplicate: Final[ScimErrorDetail] = {
"error": f"Group already exists with ID: {team_id}",
"scimType": "uniqueness",
}
raise HTTPException(status_code=409, detail=duplicate)
raise HTTPException(
status_code=409,
detail={"error": f"Group already exists with ID: {team_id}"},
)
# Extract and validate group members (all users must exist)
member_result: Final = await _extract_group_member_ids(group)

View file

@ -2503,7 +2503,7 @@ async def management_problem_exception_handler(request: Request, exc: Management
@app.exception_handler(ScimError)
async def scim_error_exception_handler(request: Request, exc: ScimError) -> JSONResponse:
_close_dangling_otel_server_span(request, exc.status_code, exc=exc)
_close_dangling_otel_server_span(request, exc.status_code, exc=exc.traced_as or exc)
return scim_error_response(exc)

View file

@ -11,7 +11,7 @@ from pydantic import (
model_validator,
)
from pydantic_core.core_schema import SerializerFunctionWrapHandler
from typing_extensions import NotRequired, ReadOnly, TypedDict
from typing_extensions import ReadOnly, TypedDict
from litellm.types.llms.base import LiteLLMBaseModel
from litellm.types.proxy.management_endpoints.user_requests import NewUserRequest
@ -172,7 +172,6 @@ ScimType: TypeAlias = Literal["uniqueness"]
class ScimErrorDetail(TypedDict):
error: ReadOnly[str]
scimType: ReadOnly[NotRequired[ScimType]]
class SCIMError(LiteLLMBaseModel):

View file

@ -13,11 +13,13 @@ from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanE
import litellm.proxy.proxy_server as proxy_server_module
from litellm.proxy._types import ProxyException
from litellm.proxy.management_endpoints.scim.scim_errors import scim_error_from
from litellm.proxy.proxy_server import (
_close_dangling_otel_server_span,
openai_exception_handler,
otel_request_validation_exception_handler,
otel_unhandled_exception_handler,
scim_error_exception_handler,
)
from litellm.integrations._types.open_inference import ErrorAttributes
@ -162,6 +164,48 @@ def test_validation_handler_puts_the_error_message_on_the_span_status(
assert description == server_span.attributes.get(ErrorAttributes.ERROR_MESSAGE)
@pytest.mark.parametrize(
("failure", "error_type"),
[
(
ProxyException(
message="Authentication Error, Invalid API key provided.", type="auth_error", param="key", code=401
),
"ProxyException",
),
(
RequestValidationError(
errors=[
{
"type": "bool_parsing",
"loc": ("body", "active"),
"msg": "Input should be a valid boolean",
"input": "s3cret-input",
}
]
),
"RequestValidationError",
),
],
ids=["auth", "validation"],
)
def test_a_scim_error_keeps_the_error_type_the_route_raised_on_the_span(
wired_otel: InMemorySpanExporter,
server_span_factory: Callable[[str], object],
failure: ProxyException | RequestValidationError,
error_type: str,
) -> None:
path: Final = "/scim/v2/Users"
request: Final = _fake_request(parent_otel_span=server_span_factory(path), path=path)
answered: Final = scim_error_from(failure)
response: Final = asyncio.run(scim_error_exception_handler(request, answered))
attributes: Final = get_server_span(wired_otel).attributes
assert (response.status_code, attributes.get(ErrorAttributes.ERROR_TYPE)) == (answered.status_code, error_type)
assert "s3cret-input" not in str(attributes.get(ErrorAttributes.ERROR_MESSAGE))
def test_unhandled_handler_reraises_known_exceptions(wired_otel, server_span_factory):
"""ProxyException / HTTPException / RequestValidationError have dedicated handlers."""
request = _fake_request(parent_otel_span=server_span_factory("/key/generate"), path="/key/generate")

View file

@ -4,6 +4,7 @@ import json
import logging
import time
from collections.abc import Awaitable, Callable, Mapping, Sequence
from http import HTTPStatus
from itertools import chain
from types import MappingProxyType
from typing import Final, assert_never
@ -7331,6 +7332,65 @@ async def test_creating_a_resource_that_already_exists_answers_409_with_scim_typ
)
@pytest.mark.asyncio
async def test_a_user_whose_email_matches_another_only_ignoring_case_answers_409_with_scim_type_uniqueness(
proxy_scim_client: AsyncClient, proxy_admin_caller: None, monkeypatch: pytest.MonkeyPatch
):
existing: Final = LiteLLM_UserTable(user_id="erin-from-okta", user_email="erin@example.com")
async def find_first(where: dict[str, object]) -> LiteLLM_UserTable | None:
match where:
case {"user_email": {"equals": str() as email, "mode": "insensitive"}} if email.casefold() == "erin@example.com":
return existing
case _:
return None
users: Final = MagicMock()
users.find_unique = AsyncMock(return_value=None)
users.find_first = AsyncMock(side_effect=find_first)
_proxy_database(monkeypatch, users=users, teams=MagicMock())
async with proxy_scim_client as client:
response = await client.post("/scim/v2/Users", json=_okta_user("Erin@Example.com"))
assert (response.status_code, response.headers["content-type"], response.json()) == (
409,
"application/scim+json",
{
"schemas": [_SCIM_ERROR_URN],
"status": "409",
"detail": "User with email erin@example.com already exists",
"scimType": "uniqueness",
},
)
@pytest.mark.asyncio
async def test_an_unexpected_failure_before_the_handler_answers_a_scim_error_and_logs_what_broke(
proxy_scim_client: AsyncClient, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
):
from litellm.proxy import proxy_server
internals: Final = "row decode failed for column metadata"
def fail_while_authenticating() -> UserAPIKeyAuth:
raise RuntimeError(internals)
monkeypatch.setitem(proxy_server.app.dependency_overrides, user_api_key_auth, fail_while_authenticating)
with caplog.at_level(logging.ERROR, logger="LiteLLM Proxy"):
async with proxy_scim_client as client:
response = await client.post("/scim/v2/Users", json=_okta_user("user-d@okta-test.com"))
assert (response.status_code, response.headers["content-type"], response.json()) == (
500,
"application/scim+json",
{"schemas": [_SCIM_ERROR_URN], "status": "500", "detail": HTTPStatus.INTERNAL_SERVER_ERROR.phrase},
)
assert internals not in response.text
assert any(internals in record.getMessage() for record in caplog.records)
@pytest.mark.asyncio
async def test_a_key_the_proxy_does_not_know_answers_401_as_a_scim_error_with_the_auth_reason(
proxy_scim_client: AsyncClient, monkeypatch: pytest.MonkeyPatch