BerriAI/litellm · error · HTTPException

SAML authentication failed: {reason or ', '.join(errors)}

Error message

SAML authentication failed: {reason or ', '.join(errors)}

What it means

Post-processing check: the toolkit reports the response was not successfully processed — errors are non-empty, or a reason string was provided for an unauthenticated user. Raised as 401; at-fault cause is signature/timestamp/audience validation failure at the IdP response.

Source

Thrown at litellm/proxy/management_endpoints/sso/saml_sso.py:322

        return dict(parse_qsl(body.decode("utf-8", "replace")))

    @staticmethod
    async def handle_acs(request: Request, cache: DualCache, post_data: dict[str, str]) -> CustomOpenID:
        auth: Final = await SAMLAuthHandler._build_auth(request, cache, post_data=post_data)
        browser_request_id: Final = request.cookies.get(_SAML_AUTHN_STATE_COOKIE)
        try:
            auth.process_response(request_id=browser_request_id)
        except Exception as e:  # noqa: BLE001 - toolkit exposes no common exception base; fail closed
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail=f"Could not process SAML response: {e}",
            )

        errors: Final = cast(list[str], auth.get_errors())  # cast-ok: untyped python3-saml
        if errors or not auth.is_authenticated():
            reason: Final = auth.get_last_error_reason()
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail=f"SAML authentication failed: {reason or ', '.join(errors)}",
            )

        await SAMLAuthHandler._enforce_response_binding(auth, cache, browser_request_id)
        return SAMLAuthHandler._result_from_auth(auth)

    @staticmethod
    def _replay_guard_ttl(auth: "OneLogin_Saml2_Auth") -> int:
        not_on_or_after: Final = auth.get_last_assertion_not_on_or_after()
        if not isinstance(not_on_or_after, int):
            return _SAML_REPLAY_GUARD_DEFAULT_TTL_SECONDS
        remaining: Final = not_on_or_after - int(time.time())
        return min(
            max(remaining, _SAML_REPLAY_GUARD_DEFAULT_TTL_SECONDS),
            _SAML_REPLAY_GUARD_MAX_TTL_SECONDS,
        )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Review the failure reason in the message; verify certificates, timestamps, and audience restrictions.

When it happens

Trigger: Thrown at litellm/proxy/management_endpoints/sso/saml_sso.py:322 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

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