How identitypython/pysaml2 works
Project type and purpose
• This is PySAML2: a pure‐Python library implementing the SAML2 standard.
• It provides all building blocks to assemble a SAML2 Service Provider (SP) or Identity Provider (IdP).
• It’s framework‐agnostic but originally intended for WSGI (with s2repoze extensions).
File structure
• Top-level:
• src/saml2 – core library code, organized by functionality: protocol, binding, crypto, metadata, tools
• example – ready-to-run SP/IdP demos (WSGI scripts, Mako templates, PKI)
• script – CLI/test utilities driving sample IdP/SP interactions
• docs – Sphinx docs, how-tos, examples
• tests – exhaustive unit and integration tests, sample metadata, certificates
• Key configuration files: pyproject.toml, .travis.yml, docs/conf.py
• Extensions: src/saml2/s2repoze (plugins for repoze.who), attribute-map converters
Insights from README
• Pure Python SAML2 stack
• Uses external xmlsec CLI for XML signature/encryption
• Supports metadata schema, multiple authentication contexts, caching, pluggable back-ends (in-memory, Mongo)
• Examples illustrate SP and IdP deployments under WSGI
a. Main components
• Application Layer (your IdP or SP application)
• PySAML2 Core Library
– Protocol handlers (samlp.py, saml.py)
– Assertion manager (assertion.py, response.py)
– Metadata subsystem (md.py, mdstore.py, mdbcache.py)
– Cryptography (cryptography/, sigver.py, xmlenc/xmlsec wrappers)
– Bindings and transports (httputil.py, httpbase.py, ecp, paos)
– Utility tools (tools/, attribute maps)
– Extensions (profile/, extension/, s2repoze/)
• External Dependencies
– xmlsec1 binary for signing/encryption
– Optional LDAP for userinfo
– Optional MongoDB (mongo_store.py)
• Web Container / Transport
– WSGI server or alternative framework
• Data stores
– Metadata files or database
– Cache (in-memory or persistent)
b. Relationships and interactions
1. Client browser → HTTP request to your SP/IdP (WSGI)
2. Web container hands request to application, which calls PySAML2 API
3. Core Library:
– Loads and validates metadata
– Processes incoming SAMLRequest via samlp.py
– Builds / signs Assertions via assertion.py + xmlsec
– Optionally encrypts data (xmlenc)
– Resolves attributes via attribute_resolver or LDAP
– Caches sessions & metadata
4. Library returns HTTPResponse (Redirect, POST binding)
5. External xmlsec invoked for crypto operations
c. Architectural patterns and design principles
• Modular layering: transport → protocol → assertion → crypto
• Pluggable back-ends (cache, metadata, attribute mapping)
• Clear separation of concerns: core protocol vs extensions (s2repoze, tools)
• Test-driven: extensive tests mirror each component
d. Key technologies/frameworks
• Python 3
• WSGI / s2repoze plugins
• xmlsec1 CLI
• Mako templates for example UIs
• MongoDB (optional)