PySAML2

PySAML2 is a pure Python implementation of the SAML Version 2.0 standard, providing all the building blocks needed to build a SAML2 service provider (SP) or identity provider (IdP). Maintained under the IdentityPython umbrella, it has been a foundational piece of Python SSO infrastructure for over a decade, powering enterprise and academic federation deployments.

The library implements the full range of SAML2 bindings and profiles (HTTP-Redirect, HTTP-POST, SOAP, ECP), handles metadata parsing/generation, assertion validation, and XML signing/encryption via the external xmlsec binary. Originally built for WSGI environments, extensions and examples exist for integrating it with other Python web frameworks.

What You Get

• Full SAML2 Core, Bindings, Profiles, and Metadata specification support
• Service provider (SP) and identity provider (IdP) building blocks, with example WSGI apps for both
• Command-line tools for metadata generation, export, and merging (make_metadata, mdexport, merge_metadata)
• XML signing and encryption via the xmlsec1 binary, with certificate management helpers
• Enhanced Client or Proxy (ECP) profile support for non-browser SAML flows
• Attribute mapping and conversion utilities for common attribute profiles (eduPerson, etc.)

Common Use Cases

• Adding SAML-based single sign-on to a Python web application acting as a service provider
• Building a custom identity provider for institutional or enterprise federations
• Integrating with academic/research federations (e.g. eduGAIN, InCommon) that require SAML2 metadata exchange
• Bridging SAML2 identity federation into non-SAML auth systems as part of a broader IAM stack

Under The Hood

Architecture: PySAML2 is organized around a central saml2 package (src/saml2, ~25k lines) that separates protocol concerns into dedicated modules — entity.py and config.py model SP/IdP entities and their configuration, request.py/response.py build and parse SAML protocol messages, mdstore.py/metadata.py handle metadata discovery and caching (with pluggable backends like mongo_store.py and mcache.py), and client.py/client_base.py/ecp_client.py implement the consuming side of the various bindings. Example WSGI-based SP and IdP reference apps live under example/, demonstrating end-to-end wiring. Tech Stack: Pure Python (99.8% of the codebase) targeting Python 3.9+, built with Poetry/pyproject.toml, depending on cryptography, defusedxml, pyopenssl, python-dateutil, requests, and xmlschema, plus the external xmlsec1 system binary for XML-DSig/XML-Enc operations — a notable non-Python runtime dependency that complicates deployment. Code Quality: The project has an extensive tests/ directory (180+ files) covering protocol edge cases, but activity has slowed considerably (low recent commit velocity per GitHub metrics) even though the codebase is mature and heavily battle-tested in production federations. Module naming follows SAML spec terminology closely, which aids spec-to-code traceability but raises the learning curve for newcomers unfamiliar with SAML jargon. API Design: The public API requires understanding SAML/XML concepts (entity IDs, bindings, NameID formats, metadata) before it becomes ergonomic; configuration is dict/class-based rather than fluent, and the CLI tools (make_metadata, mdexport) offer a lower-friction entry point for metadata-only tasks than the full client API.