From befded95a1d2f4765bf8cf4f2eed4d5e002df314 Mon Sep 17 00:00:00 2001 From: libaojiang <2461443384@qq.com> Date: Thu, 22 Oct 2026 17:12:04 +0800 Subject: [PATCH 1/2] fix(otel): preserve Langfuse deployment metadata --- litellm/integrations/otel/mappers/langfuse.py | 6 ++ .../integrations/otel/model/trace_controls.py | 15 +++- litellm/proxy/_types.py | 11 ++- litellm/proxy/auth/auth_utils.py | 6 ++ .../otel/test_otel_v2_sources_of_truth.py | 74 +++++++++++++++++++ .../otel/test_otel_v2_vendor_mappers.py | 20 ++++- tests/unit/proxy/auth/test_auth_utils.py | 50 ++++++++++++- ui/litellm-dashboard/src/lib/http/schema.d.ts | 20 +++-- 8 files changed, 182 insertions(+), 20 deletions(-) diff --git a/litellm/integrations/otel/mappers/langfuse.py b/litellm/integrations/otel/mappers/langfuse.py index e60ea539188..cc8da9984fb 100644 --- a/litellm/integrations/otel/mappers/langfuse.py +++ b/litellm/integrations/otel/mappers/langfuse.py @@ -37,6 +37,9 @@ LANGFUSE_TRACE_NAME: Final = "langfuse.trace.name" LANGFUSE_TRACE_USER_ID: Final = "user.id" LANGFUSE_TRACE_SESSION_ID: Final = "session.id" LANGFUSE_TRACE_TAGS: Final = "langfuse.trace.tags" +LANGFUSE_ENVIRONMENT: Final = "langfuse.environment" +LANGFUSE_RELEASE: Final = "langfuse.release" +LANGFUSE_VERSION: Final = "langfuse.version" class LangfuseMapper: @@ -103,6 +106,9 @@ class LangfuseMapper: (LANGFUSE_TRACE_USER_ID, trace.user_id or None), (LANGFUSE_TRACE_SESSION_ID, trace.session_id or None), (LANGFUSE_TRACE_TAGS, trace.tags or None), + (LANGFUSE_ENVIRONMENT, trace.environment or None), + (LANGFUSE_RELEASE, trace.release or None), + (LANGFUSE_VERSION, trace.version or None), ) ) diff --git a/litellm/integrations/otel/model/trace_controls.py b/litellm/integrations/otel/model/trace_controls.py index eac7b5c897b..2451cdb2613 100644 --- a/litellm/integrations/otel/model/trace_controls.py +++ b/litellm/integrations/otel/model/trace_controls.py @@ -2,6 +2,7 @@ from __future__ import annotations +import os from collections.abc import Mapping from dataclasses import dataclass from typing import Final @@ -25,12 +26,15 @@ class TraceControls: user_id: str | None = None session_id: str | None = None tags: tuple[str, ...] = () + environment: str | None = None + release: str | None = None + version: str | None = None def caller_trace_controls(kwargs: Mapping[str, object]) -> TraceControls: request: Final = as_str_mapping(kwargs.get("litellm_params")) if request is None: - return TraceControls() + return TraceControls(environment=os.environ.get("LANGFUSE_TRACING_ENVIRONMENT") or None) proxy_request: Final = as_str_mapping(request.get("proxy_server_request")) headers: Final = as_str_mapping(proxy_request.get("headers")) if proxy_request is not None else None bodies: Final = tuple( @@ -39,17 +43,22 @@ def caller_trace_controls(kwargs: Mapping[str, object]) -> TraceControls: if (metadata := as_str_mapping(request.get(key))) is not None ) - def scalar(control: str) -> str | None: + def scalar(control: str, *, body_control: str | None = None) -> str | None: from_header: Final = as_str(headers.get(f"{LANGFUSE_HEADER_PREFIX}{control}")) if headers is not None else None if from_header: return from_header - return next((value for body in bodies if (value := as_str(body.get(control)))), None) + return next((value for body in bodies if (value := as_str(body.get(body_control or control)))), None) return TraceControls( name=scalar("trace_name"), user_id=scalar("trace_user_id"), session_id=scalar("session_id"), tags=next((tags for body in bodies if (tags := _str_items(body.get("tags")))), ()), + environment=scalar("environment", body_control="langfuse_environment") + or os.environ.get("LANGFUSE_TRACING_ENVIRONMENT") + or None, + release=scalar("release", body_control="trace_release"), + version=scalar("version", body_control="trace_version"), ) diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 54acf59ef80..dfc5ddd5a4a 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -88,7 +88,12 @@ from litellm.types.proxy.carried_budget_state import ( from litellm.types.proxy.control_plane_endpoints import WorkerRegistryEntry from litellm.types.proxy.request_tag_mappings import RequestTagMapping from litellm.types.proxy.spend_capture_rate import SpendCaptureRateCheckSettings -from litellm.types.router import AllowedModelRegion, RouterErrors, UpdateRouterConfig +from litellm.types.router import ( + AllowedModelRegion, + ConfigurableClientsideParamsCustomAuth, + RouterErrors, + UpdateRouterConfig, +) from litellm.types.router_weights import validate_router_settings_dict from litellm.types.secret_managers.main import KeyManagementSystem from litellm.types.utils import ( @@ -2493,6 +2498,10 @@ class ConfigGeneralSettings(LiteLLMPydanticObjectBase): use_google_kms: bool | None = Field(None, description="decrypt keys with google kms") use_azure_key_vault: bool | None = Field(None, description="load keys from azure key vault") master_key: str | None = Field(None, description="require a key for all calls to proxy") + configurable_clientside_auth_params: Sequence[str | ConfigurableClientsideParamsCustomAuth] | None = Field( + None, + description="Allow only these client-supplied credential or callback parameters for every model. Names allow any value. api_base mappings restrict values using the same matching rules as per-deployment configuration.", + ) dangerously_permit_weak_or_unset_master_key: bool | None = Field( None, description="local development only: start even when master_key is unset, empty, or a publicly known default", diff --git a/litellm/proxy/auth/auth_utils.py b/litellm/proxy/auth/auth_utils.py index 7a186d84aa5..4f9ddcab9e3 100644 --- a/litellm/proxy/auth/auth_utils.py +++ b/litellm/proxy/auth/auth_utils.py @@ -504,6 +504,12 @@ def _check_banned_params( # Proxy-wide opt-in: every banned param is permitted, exit # entirely so the rest of the loop doesn't waste work. return + if _is_param_allowed( + param=param, + request_body_value=body[param], + configurable_clientside_auth_params=general_settings.get("configurable_clientside_auth_params"), + ): + continue if ( _allow_model_level_clientside_configurable_parameters( model=model, diff --git a/tests/unit/integrations/otel/test_otel_v2_sources_of_truth.py b/tests/unit/integrations/otel/test_otel_v2_sources_of_truth.py index 318859cb3ed..5821f8eac46 100644 --- a/tests/unit/integrations/otel/test_otel_v2_sources_of_truth.py +++ b/tests/unit/integrations/otel/test_otel_v2_sources_of_truth.py @@ -1294,6 +1294,80 @@ def test_caller_trace_name_prefers_the_langfuse_header_over_body_metadata(reques assert LLMCallEvent.from_dict({"litellm_params": request_data}).trace.name == expected +@pytest.mark.parametrize( + "request_data,environment,release,version", + [ + ( + {"metadata": {"langfuse_environment": "body", "trace_release": "r1", "trace_version": "v1"}}, + "body", + "r1", + "v1", + ), + ( + {"litellm_metadata": {"langfuse_environment": "messages", "trace_release": "r2", "trace_version": "v2"}}, + "messages", + "r2", + "v2", + ), + ( + { + "proxy_server_request": { + "headers": { + "langfuse_environment": "header", + "langfuse_release": "r3", + "langfuse_version": "v3", + } + }, + "metadata": {"langfuse_environment": "body", "trace_release": "ignored", "trace_version": "ignored"}, + }, + "header", + "r3", + "v3", + ), + ( + { + "proxy_server_request": { + "headers": { + "langfuse_environment": "", + "langfuse_release": "", + "langfuse_version": None, + } + }, + "metadata": {"langfuse_environment": "body", "trace_release": "r4", "trace_version": "v4"}, + }, + "body", + "r4", + "v4", + ), + ({"metadata": {"langfuse_environment": None, "trace_release": "", "trace_version": ""}}, "deployment", None, None), + ({}, "deployment", None, None), + ], +) +def test_langfuse_deployment_controls_preserve_header_body_and_environment_precedence( + request_data: Mapping[str, object], + environment: str, + release: str | None, + version: str | None, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv("LANGFUSE_TRACING_ENVIRONMENT", "deployment") + expected: Final = TraceControls(environment=environment, release=release, version=version) + assert caller_trace_controls({"litellm_params": request_data}) == expected + assert LLMCallEvent.from_dict({"litellm_params": request_data}).trace == expected + + +@pytest.mark.parametrize("environment", [None, "", "deployment"]) +def test_langfuse_deployment_environment_applies_without_request_params( + environment: str | None, + monkeypatch: pytest.MonkeyPatch, +) -> None: + if environment is None: + monkeypatch.delenv("LANGFUSE_TRACING_ENVIRONMENT", raising=False) + else: + monkeypatch.setenv("LANGFUSE_TRACING_ENVIRONMENT", environment) + assert caller_trace_controls({}) == TraceControls(environment=environment or None) + + @pytest.mark.parametrize( ("request_data", "expected"), [ diff --git a/tests/unit/integrations/otel/test_otel_v2_vendor_mappers.py b/tests/unit/integrations/otel/test_otel_v2_vendor_mappers.py index 7e112fcf6a4..540728b9f87 100644 --- a/tests/unit/integrations/otel/test_otel_v2_vendor_mappers.py +++ b/tests/unit/integrations/otel/test_otel_v2_vendor_mappers.py @@ -631,11 +631,27 @@ def test_langfuse_mapper_omits_unset_trace_controls(): def test_langfuse_trace_attributes_match_between_root_and_generation(): - controls = TraceControls(name="n", user_id="u", session_id="s", tags=("t",)) + controls: Final = TraceControls( + name="n", + user_id="u", + session_id="s", + tags=("t",), + environment="test", + release="r1", + version="v1", + ) generation = LangfuseMapper().map(_llm_call(trace=controls)) root = LangfuseMapper.trace_attributes(controls) - assert root == {"langfuse.trace.name": "n", "user.id": "u", "session.id": "s", "langfuse.trace.tags": ("t",)} + assert root == { + "langfuse.trace.name": "n", + "user.id": "u", + "session.id": "s", + "langfuse.trace.tags": ("t",), + "langfuse.environment": "test", + "langfuse.release": "r1", + "langfuse.version": "v1", + } assert all(generation[key] == value for key, value in root.items()) diff --git a/tests/unit/proxy/auth/test_auth_utils.py b/tests/unit/proxy/auth/test_auth_utils.py index ee1ae43fd3a..9188311073f 100644 --- a/tests/unit/proxy/auth/test_auth_utils.py +++ b/tests/unit/proxy/auth/test_auth_utils.py @@ -368,7 +368,11 @@ _SERVICE_ACCOUNT_TOKEN_REFERENCE: Final = "oidc/file//var/run/secrets/kubernetes def _user_config_with(litellm_params: dict[str, str]) -> dict[str, object]: - return {"model_list": [{"model_name": "devstral", "litellm_params": {"model": "mistral/devstral-latest", **litellm_params}}]} + return { + "model_list": [ + {"model_name": "devstral", "litellm_params": {"model": "mistral/devstral-latest", **litellm_params}} + ] + } def _user_config_defaulting_to(litellm_params: dict[str, str]) -> dict[str, object]: @@ -388,7 +392,11 @@ def _user_config_search_tool_with(litellm_params: dict[str, str]) -> dict[str, o "search_tools": [ { "search_tool_name": "web", - "litellm_params": {"search_provider": "tavily", "api_base": "https://attacker.example", **litellm_params}, + "litellm_params": { + "search_provider": "tavily", + "api_base": "https://attacker.example", + **litellm_params, + }, } ] } @@ -509,7 +517,9 @@ def test_a_call_cannot_carry_an_oidc_api_key_in_litellm_params(route: str | None ) -@pytest.mark.parametrize("route", ["/model/new", "/model/update", "/model/deployment-1/update", "/health/test_connection"]) +@pytest.mark.parametrize( + "route", ["/model/new", "/model/update", "/model/deployment-1/update", "/health/test_connection"] +) def test_a_deployment_write_may_carry_an_oidc_api_key_in_litellm_params(route: str): """A proxy admin configures an oidc/ api_key on a deployment through these routes, and the model management role gate refuses anyone else with a 403.""" @@ -4395,6 +4405,40 @@ class TestObservabilityCallbackBans: ) +@pytest.mark.parametrize("container", [None, "metadata", "litellm_metadata", "extra_body"]) +@pytest.mark.parametrize("model", ["group-a", "group-b"]) +def test_proxy_wide_allowlist_admits_only_the_named_observability_param(container: str | None, model: str) -> None: + settings: Final = {"configurable_clientside_auth_params": ["langfuse_environment"]} + controls: Final = {"langfuse_environment": "test"} + request: Final = {"model": model, **({container: controls} if container else controls)} + assert is_request_body_safe(request_body=request, general_settings=settings, llm_router=None, model=model) is True + for field in ("api_base", "langfuse_host", "aws_web_identity_token"): + forbidden: Final = {**controls, field: "https://unlisted.example"} + mixed: Final = {"model": model, **({container: forbidden} if container else forbidden)} + with pytest.raises(ValueError, match=field): + is_request_body_safe(request_body=mixed, general_settings=settings, llm_router=None, model=model) + + +def test_proxy_wide_allowlist_keeps_api_base_value_restrictions() -> None: + settings: Final = {"configurable_clientside_auth_params": [{"api_base": r"^https://allowed\.example/v1$"}]} + assert ( + is_request_body_safe( + request_body={"api_base": "https://allowed.example/v1"}, + general_settings=settings, + llm_router=None, + model="group", + ) + is True + ) + with pytest.raises(ValueError, match="api_base"): + is_request_body_safe( + request_body={"api_base": "https://unlisted.example/v1"}, + general_settings=settings, + llm_router=None, + model="group", + ) + + def test_model_level_allow_does_not_skip_subsequent_banned_params(monkeypatch): """Greptile P1: ``_check_banned_params`` previously ``return``-ed when a deployment's ``configurable_clientside_auth_params`` permitted one diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts index bd08b743c7d..b0908267c29 100644 --- a/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -29857,6 +29857,11 @@ export interface components { * @description proxy level default model for all chat completion calls */ completion_model?: string | null; + /** + * Configurable Clientside Auth Params + * @description Allow only these client-supplied credential or callback parameters for every model. Names allow any value. api_base mappings restrict values using the same matching rules as per-deployment configuration. + */ + configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth"])[] | null; /** * Control Plane Url * @description Global Control Plane: URL of the control plane whose admin UI manages this instance. Enables /v3/login and /v3/login/exchange on this instance so that UI can authenticate against it cross-origin, and restricts the SSO return_to origin to that URL. No state is shared with the control plane @@ -30489,14 +30494,7 @@ export interface components { worker_registry?: components["schemas"]["WorkerRegistryEntry"][] | null; }; /** ConfigurableClientsideParamsCustomAuth */ - "ConfigurableClientsideParamsCustomAuth-Input": { - /** Api Base */ - api_base: string; - } & { - [key: string]: unknown; - }; - /** ConfigurableClientsideParamsCustomAuth */ - "ConfigurableClientsideParamsCustomAuth-Output": { + ConfigurableClientsideParamsCustomAuth: { /** Api Base */ api_base: string; }; @@ -35302,7 +35300,7 @@ export interface components { /** Complexity Router Default Model */ complexity_router_default_model?: string | null; /** Configurable Clientside Auth Params */ - configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth-Input"])[] | null; + configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth"])[] | null; /** Cost Per Second */ cost_per_second?: number | null; /** Custom Llm Provider */ @@ -38373,7 +38371,7 @@ export interface components { /** ModelGroupInfoProxy */ ModelGroupInfoProxy: { /** Configurable Clientside Auth Params */ - configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth-Output"])[] | null; + configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth"])[] | null; /** Custom Metadata */ custom_metadata?: { [key: string]: string | number | boolean; @@ -50600,7 +50598,7 @@ export interface components { /** Complexity Router Default Model */ complexity_router_default_model?: string | null; /** Configurable Clientside Auth Params */ - configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth-Input"])[] | null; + configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth"])[] | null; /** Cost Per Second */ cost_per_second?: number | null; /** Custom Llm Provider */ From 68c78b77ef2f9e2d453f15a7b2c4f4293c300816 Mon Sep 17 00:00:00 2001 From: libaojiang <2461443384@qq.com> Date: Thu, 22 Oct 2026 17:36:02 +0800 Subject: [PATCH 2/2] fix(auth): validate the global clientside parameter allowlist --- litellm/proxy/auth/auth_utils.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/litellm/proxy/auth/auth_utils.py b/litellm/proxy/auth/auth_utils.py index 4f9ddcab9e3..6e41b8aadb0 100644 --- a/litellm/proxy/auth/auth_utils.py +++ b/litellm/proxy/auth/auth_utils.py @@ -252,6 +252,9 @@ def _allow_model_level_clientside_configurable_parameters( reject_server_owned_wif_params = _reject_server_owned_wif_params _CREDENTIAL_VALUES: Final = TypeAdapter(dict[str, object]) +_CLIENTSIDE_AUTH_PARAMS: Final[TypeAdapter[CONFIGURABLE_CLIENTSIDE_AUTH_PARAMS]] = TypeAdapter( + CONFIGURABLE_CLIENTSIDE_AUTH_PARAMS +) _DECODED_JSON: Final = TypeAdapter(object) _LIST_ENTRIES: Final = TypeAdapter(tuple[object, ...]) @@ -507,7 +510,9 @@ def _check_banned_params( if _is_param_allowed( param=param, request_body_value=body[param], - configurable_clientside_auth_params=general_settings.get("configurable_clientside_auth_params"), + configurable_clientside_auth_params=_CLIENTSIDE_AUTH_PARAMS.validate_python( + _CREDENTIAL_VALUES.validate_python(general_settings).get("configurable_clientside_auth_params") + ), ): continue if (