BerriAI/litellm · error · ValueError

Oauth2 proxy auth refuses to map non-identity UserAPIKeyAuth

Error message

Oauth2 proxy auth refuses to map non-identity UserAPIKeyAuth fields from request headers: {disallowed}. Only identity fields are accepted ({sorted(ALLOWED_OAUTH2_PROXY_FIELDS)}); anything else (privileges, budgets, rate limits, metadata) would let a caller forge enforcement parameters by spoofing the matching header. If you need a trusted upstream to assert anything beyond identity, use JWT auth (signature-validated) instead of header-trust.

What it means

Error "Oauth2 proxy auth refuses to map non-identity UserAPIKeyAuth fields from request headers: {disallowed}. Only identity fields are accepted ({sorted(ALLOWED_OAUTH2_PROXY_FIELDS)}); anything else (privileges, budgets, rate limits, metadata) would let a caller forge enforcement parameters by spoofing the matching header. If you need a trusted upstream to assert anything beyond identity, use JWT auth (signature-validated) instead of header-trust." thrown in BerriAI/litellm.

Source

Thrown at litellm/proxy/auth/oauth2_proxy_hook.py:76

    """
    from litellm.proxy.proxy_server import general_settings

    verbose_proxy_logger.debug("Handling oauth2 proxy request")
    require_trusted_proxy_request(
        request=request,
        general_settings=general_settings,
        feature_name="OAuth2 proxy auth",
    )

    oauth2_config_mappings: Final[dict[str, str]] = general_settings.get("oauth2_config_mappings") or {}
    verbose_proxy_logger.debug("Oauth2 config mappings: %s", oauth2_config_mappings)

    if not oauth2_config_mappings:
        raise ValueError("Oauth2 config mappings not found in general_settings")

    disallowed: Final = sorted(set(oauth2_config_mappings.keys()) - ALLOWED_OAUTH2_PROXY_FIELDS)
    if disallowed:
        raise ValueError(
            "Oauth2 proxy auth refuses to map non-identity UserAPIKeyAuth "
            f"fields from request headers: {disallowed}. Only identity "
            f"fields are accepted ({sorted(ALLOWED_OAUTH2_PROXY_FIELDS)}); "
            "anything else (privileges, budgets, rate limits, metadata) "
            "would let a caller forge enforcement parameters by spoofing "
            "the matching header. If you need a trusted upstream to "
            "assert anything beyond identity, use JWT auth "
            "(signature-validated) instead of header-trust."
        )

    auth_data: Final[Mapping[str, str | list[str]]] = {
        key: [model.strip() for model in value.split(",")] if key == "models" else value
        for key, header in oauth2_config_mappings.items()
        if (value := request.headers.get(header))
    }

    verbose_proxy_logger.debug(
        "Auth data before creating UserAPIKeyAuth object: keys=%s",

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Restrict your upstream proxy to only assert identity headers (the ALLOWED_OAUTH2_PROXY_FIELDS).
2. If you need trusted assertions beyond identity, switch to JWT auth so claims are signature-validated.

Example fix

Remove non-identity header mappings (roles, budgets, rate limits, metadata) from the oauth2 proxy config.

When it happens

Trigger: Thrown at litellm/proxy/auth/oauth2_proxy_hook.py:76 when the library encounters an invalid state.

Common situations: The oauth2 proxy config tried to map enforcement fields (privileges, budgets, metadata) from spoofable request headers.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/9ab02eb57b6e03e1. Report an issue: GitHub.