BerriAI/litellm · error · HTTPException

SAML assertion did not contain a usable subject (NameID) or

Error message

SAML assertion did not contain a usable subject (NameID) or email.

What it means

Neither the configured email attribute candidates nor a NameID containing '@' yielded an email, and no role/subject info could produce a usable identity: the assertion lacks a usable subject, so the login cannot proceed and a 401 is raised.

Source

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

        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 "
                    "restricts sign-in by email domain."
                ),
            )

        user_id: Final = SAMLAuthHandler._attribute_value(attributes, "SAML_ATTRIBUTE_USER_ID", ()) or name_id or email
        if user_id is None:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="SAML assertion did not contain a usable subject (NameID) or email.",
            )

        first_name: Final = SAMLAuthHandler._attribute_value(
            attributes, "SAML_ATTRIBUTE_FIRST_NAME", _FIRST_NAME_ATTRIBUTE_CANDIDATES
        )
        last_name: Final = SAMLAuthHandler._attribute_value(
            attributes, "SAML_ATTRIBUTE_LAST_NAME", _LAST_NAME_ATTRIBUTE_CANDIDATES
        )
        role_value = SAMLAuthHandler._attribute_value(attributes, "SAML_ATTRIBUTE_ROLE", _ROLE_ATTRIBUTE_CANDIDATES)
        team_ids: Final = SAMLAuthHandler._attribute_values(
            attributes, "SAML_ATTRIBUTE_TEAM_IDS", _TEAM_IDS_ATTRIBUTE_CANDIDATES
        )

        display_name: Final = " ".join(part for part in (first_name, last_name) if part) or email

        verbose_proxy_logger.info(

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Configure the IdP to send a NameID or email attribute in the assertion.

When it happens

Trigger: Thrown at litellm/proxy/management_endpoints/sso/saml_sso.py:434 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/a6982cfc1eeed994. Report an issue: GitHub.