python3-saml

python3-saml turns a Python application into a SAML Service Provider (SP) that can federate authentication with an Identity Provider (IdP), implementing the SAML 2.0 Web Browser SSO Profile including SP-initiated and IdP-initiated SSO and SLO (Single Logout). It handles assertion/nameID encryption, message and assertion signature validation, and SP metadata publishing.

The library is session-less by design — it validates and parses SAML messages but delegates actual session management to the host application, and it ships as onelogin/saml2 (the module namespace retained from its predecessor python-saml), with reference demo integrations for Django, Flask, Pyramid, and Tornado. It depends on xmlsec and lxml for XML signature verification and encryption, and defusedxml/careful XML parsing to defend against XXE and XML-signature-wrapping attacks, several of which were the subject of past published CVEs the project has since patched.

What You Get

• An Auth class (onelogin.saml2.auth) providing high- and low-level APIs for processing SSO/SLO requests and responses
• Assertion and NameID encryption/decryption plus signature validation for AuthNRequest, LogoutRequest, and LogoutResponse messages
• SP metadata generation, including signed metadata support
• Reference demo integrations for Django, Flask, Pyramid, and Tornado showing end-to-end wiring
• Security utilities (get_last_request_id, get_last_message_id, get_last_assertion_id) for replay-attack prevention

Common Use Cases

• Adding enterprise SSO login to a Django, Flask, or Pyramid app so employees authenticate via their company’s IdP (Okta, Azure AD, ADFS)
• Implementing centralized single logout (SLO) across multiple SP applications sharing one IdP session
• Publishing signed SP metadata for automated IdP-side SAML configuration in enterprise B2B integrations
• Building a custom identity broker or SSO gateway that needs to validate and reissue SAML assertions

Under The Hood

Architecture - The core lives in src/onelogin/saml2/: auth.py is the main entry point coordinating request/response flow, settings.py loads SP/IdP configuration (certs, endpoints, security options), authn_request.py/logout_request.py/logout_response.py build outgoing SAML XML messages, response.py parses and validates incoming assertions, metadata.py generates SP metadata XML, and xml_utils.py/xmlparser.py/utils.py centralize XML signing, canonicalization, and signature-wrapping defenses shared across all message types. idp_metadata_parser.py additionally lets an SP bootstrap its IdP configuration directly from a published IdP metadata XML document.

Tech Stack - Python 3.7+, built on xmlsec (Python bindings to the XML Security Library) for XML-DSig/XML-Enc operations, lxml for XML parsing, and isodate for SAML’s ISO-8601 timestamps. The README explicitly warns against installing lxml from binary wheels to avoid libxml2 version mismatches with xmlsec, reflecting the security-sensitive nature of correct XML-crypto library pairing.

Code Quality - Six top-level test modules exercise SSO/SLO flows, signature validation, and metadata generation, with Coveralls-tracked coverage and a GitHub Actions CI workflow. The project’s README maintains an unusually detailed changelog of security fixes by version (CVE-2017-11427, CVE-2017-9672, CVE-2016-1000251), documenting exactly which historical versions were vulnerable to XXE, signature-wrapping, and validation-bypass attacks — a strong signal of security-conscious maintenance for a protocol library where correctness is a security property.

API Design - Auth exposes both a high-level API (call process_response()/process_slo() and check is_authenticated()) for common flows and lower-level building blocks for custom SAML handling, but the library is explicit that strict mode MUST be enabled in production and that IdP certificates should be registered directly rather than relying on the more collision-prone fingerprint method — meaning safe usage requires reading the security-guidelines section, not just the quickstart.