# identitypython/pysaml2 architecture

> Architecture diagram of the GitHub repository identitypython/pysaml2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/identitypython/pysaml2
- Repository: https://github.com/identitypython/pysaml2

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Network
    Client["Client Browser"]:::network

    %% Application Layer
    subgraph "Your Application / WSGI Container"
        direction TB
        AppWSGI["WSGI App Entrypoint"]:::app

        subgraph "PySAML2 Core Library"
            direction TB

            subgraph "Protocol Handlers"
                SAMLP["samlp.py"]:::core
                SAML["saml.py"]:::core
            end

            subgraph "Assertion Manager"
                ASSERT["assertion.py"]:::core
                RESPONSE["response.py"]:::core
            end

            subgraph "Metadata Subsystem"
                MD["md.py / metadata.py"]:::core
                MDSTORE["mdstore.py"]:::core
                MDBCACHE["mdbcache.py"]:::core
            end

            subgraph "Cryptography"
                CRYPTO["cryptography/"]:::core
                SIGVER["sigver.py"]:::core
                XMLENC["xmlenc/"]:::core
            end

            subgraph "Bindings & Transports"
                HTTPUTIL["httputil.py"]:::core
                HTTPBASE["httpbase.py"]:::core
                ECP["ecp.py"]:::core
                PAOS["profile/paos.py"]:::core
                SOAPH["soap.py / schema/soap.py"]:::core
            end

            subgraph "Attribute Resolution & Mapping"
                ATTRRES["attribute_resolver.py"]:::core
                ATTRCONV["attribute_converter.py"]:::core
                MAPS["attributemaps/"]:::core
                LDAPINFO["userinfo/ldapinfo.py"]:::core
            end

            subgraph "Pluggable Back-ends"
                CACHE["cache.py"]:::core
                MONGO["mongo_store.py"]:::core
            end

            CFG["config.py"]:::core

            subgraph "Client/Server API"
                CLIENT["client.py / client_base.py"]:::core
                SERVER["server.py"]:::core
            end

            subgraph "Extensions"
                EXT["extension/"]:::core
                PROFILE["profile/"]:::core
                S2REPOZE["s2repoze/plugins/"]:::core
            end

            TOOLS["tools/"]:::core
        end
    end

    %% External Dependencies
    XMLSEC["xmlsec1 CLI"]:::ext
    LDAP["LDAP"]:::ext
    MONDB["MongoDB"]:::ext

    %% Data Stores
    MetadataFiles["Metadata Files"]:::data
    CacheStore["Cache (In-memory/persistent)"]:::data

    %% Examples, Docs, Tests
    Examples["example/"]:::misc
    Docs["docs/"]:::misc
    Tests["tests/"]:::misc

    %% Flows
    Client -->|HTTP Request| AppWSGI
    AppWSGI -->|"calls API"| CLIENT
    CLIENT -->|"invoke Protocol"| SAMLP
    SAMLP -->|processes| ASSERT
    ASSERT -->|sign/verify| SIGVER
    SIGVER -->|executes| XMLSEC
    ASSERT -->|encrypt| XMLENC
    SAMLP -->|loads metadata| MD
    MDSTORE -->|reads/writes| MetadataFiles
    MDBCACHE -->|caches| CacheStore
    ATTRRES -->|fetch attributes| LDAPINFO
    ATTRRES -->|connects| LDAP
    CACHE -->|in-memory cache| CacheStore
    MONGO -->|persists| MONDB

    %% Click Events
    click SAMLP "https://github.com/identitypython/pysaml2/blob/master/src/saml2/samlp.py"
    click SAML "https://github.com/identitypython/pysaml2/blob/master/src/saml2/saml.py"
    click ASSERT "https://github.com/identitypython/pysaml2/blob/master/src/saml2/assertion.py"
    click RESPONSE "https://github.com/identitypython/pysaml2/blob/master/src/saml2/response.py"
    click MD "https://github.com/identitypython/pysaml2/blob/master/src/saml2/md.py"
    click MDSTORE "https://github.com/identitypython/pysaml2/blob/master/src/saml2/mdstore.py"
    click MDBCACHE "https://github.com/identitypython/pysaml2/blob/master/src/saml2/mdbcache.py"
    click CRYPTO "https://github.com/identitypython/pysaml2/tree/master/src/saml2/cryptography/"
    click SIGVER "https://github.com/identitypython/pysaml2/blob/master/src/saml2/sigver.py"
    click XMLENC "https://github.com/identitypython/pysaml2/tree/master/src/saml2/xmlenc/"
    click HTTPUTIL "https://github.com/identitypython/pysaml2/blob/master/src/saml2/httputil.py"
    click HTTPBASE "https://github.com/identitypython/pysaml2/blob/master/src/saml2/httpbase.py"
    click ECP "https://github.com/identitypython/pysaml2/blob/master/src/saml2/ecp.py"
    click PAOS "https://github.com/identitypython/pysaml2/blob/master/src/saml2/profile/paos.py"
    click SOAPH "https://github.com/identitypython/pysaml2/blob/master/src/saml2/soap.py"
    click ATTRRES "https://github.com/identitypython/pysaml2/blob/master/src/saml2/attribute_resolver.py"
    click ATTRCONV "https://github.com/identitypython/pysaml2/blob/master/src/saml2/attribute_converter.py"
    click MAPS "https://github.com/identitypython/pysaml2/tree/master/src/saml2/attributemaps/"
    click LDAPINFO "https://github.com/identitypython/pysaml2/blob/master/src/saml2/userinfo/ldapinfo.py"
    click CACHE "https://github.com/identitypython/pysaml2/blob/master/src/saml2/cache.py"
    click MONGO "https://github.com/identitypython/pysaml2/blob/master/src/saml2/mongo_store.py"
    click CFG "https://github.com/identitypython/pysaml2/blob/master/src/saml2/config.py"
    click CLIENT "https://github.com/identitypython/pysaml2/blob/master/src/saml2/client.py"
    click SERVER "https://github.com/identitypython/pysaml2/blob/master/src/saml2/server.py"
    click EXT "https://github.com/identitypython/pysaml2/tree/master/src/saml2/extension/"
    click PROFILE "https://github.com/identitypython/pysaml2/tree/master/src/saml2/profile/"
    click S2REPOZE "https://github.com/identitypython/pysaml2/tree/master/src/saml2/s2repoze/plugins/"
    click TOOLS "https://github.com/identitypython/pysaml2/tree/master/src/saml2/tools/"
    click Examples "https://github.com/identitypython/pysaml2/tree/master/example/"
    click Docs "https://github.com/identitypython/pysaml2/tree/master/docs/"
    click Tests "https://github.com/identitypython/pysaml2/tree/master/tests/"

    %% Styles
    classDef network fill:#a2f5a2,stroke:#084f08
    classDef app fill:#d0eaff,stroke:#005b9f
    classDef core fill:#cfe2f3,stroke:#084f8f
    classDef ext fill:#fce5cd,stroke:#a65f0d
    classDef data fill:#e7e6e6,stroke:#6f6f6f
    classDef misc fill:#f3f3f3,stroke:#999999
```
