BerriAI/litellm · error · HTTPException

SAML assertion has already been used (replay detected).

Error message

SAML assertion has already been used (replay detected).

What it means

The replay guard increments a consumption counter for the assertion id in the shared cache; if the count is already above 1, the same assertion was submitted before and the login is refused with 401 as a replay attempt.

Source

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

                status_code=status.HTTP_401_UNAUTHORIZED,
                detail=(
                    "Unsolicited (IdP-initiated) SAML responses require a shared Redis cache "
                    "so the replay guard is enforced across every worker."
                ),
            )

        assertion_id: Final = cast(str | None, auth.get_last_assertion_id())  # cast-ok: untyped python3-saml
        if assertion_id is None:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="SAML assertion is missing the required ID attribute.",
            )
        consumed_key: Final = f"{_SAML_CONSUMED_ASSERTION_CACHE_PREFIX}:{assertion_id}"
        consumed_count: Final = await cache.async_increment_cache(
            key=consumed_key, value=1, ttl=SAMLAuthHandler._replay_guard_ttl(auth)
        )
        if consumed_count is not None and consumed_count > 1:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="SAML assertion has already been used (replay detected).",
            )

    @staticmethod
    def _result_from_auth(auth: "OneLogin_Saml2_Auth") -> CustomOpenID:
        attributes: Final = cast(dict[str, list[str]], auth.get_attributes())  # cast-ok: untyped python3-saml
        name_id: Final = cast(str | None, auth.get_nameid())  # cast-ok: untyped python3-saml

        email = SAMLAuthHandler._attribute_value(attributes, "SAML_ATTRIBUTE_EMAIL", _EMAIL_ATTRIBUTE_CANDIDATES)
        if email is None and name_id is not None and "@" in name_id:
            email = name_id

        if email is None and SAMLAuthHandler._env("ALLOWED_EMAIL_DOMAINS") is not None:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail=(
                    "SAML assertion did not contain an email address, but ALLOWED_EMAIL_DOMAINS "

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Restart the login flow; the assertion was replayed. Investigate potential replay attacks if persistent.

When it happens

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

Common situations: See trigger scenarios.

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