PySAML2: Python SAML 2.0 Implementation

7.5.4 · active · verified Fri Apr 10

PySAML2 is a pure Python implementation of the SAML Version 2 Standard. It provides a comprehensive toolkit for building both Service Providers (SP) and Identity Providers (IdP), handling SAML assertions, requests, and responses. The library is designed to work within WSGI environments but can also be utilized in non-WSGI contexts. The current version, 7.5.4, demonstrates active development with recent releases and ongoing maintenance.

Warnings

breaking PySAML2 v7.0.0 introduced a breaking change by replacing the default encryption method `rsa-1_5` with `rsa-oaep-mgf1p` for improved security. This may require updating configurations or interoperability testing with existing Identity Providers.
Fix: Review your SAML configurations for encryption algorithms. If interoperability issues arise, ensure both SP and IdP support `rsa-oaep-mgf1p` or adjust configuration if an alternative is necessary and supported.
gotcha PySAML2 relies on the external `xmlsec1` binary for critical cryptographic operations like signature validation and XML encryption/decryption. This binary must be installed at the system level.
Fix: Install `xmlsec1` on your operating system (e.g., `sudo apt-get install xmlsec1` on Debian/Ubuntu, `sudo yum install xmlsec1-openssl` on RHEL/CentOS/Fedora, `brew install xmlsec1` on macOS).
gotcha PySAML2 has transitioned to Python 3 only. Python 2 compatibility has been dropped, and using it with Python 2 will result in errors.
Fix: Ensure your project runs on Python 3.9 or newer, as specified by the library's `requires_python` metadata.
gotcha The configuration of PySAML2 entities (SP/IdP) is critical and often complex, typically involving a Python module that defines a `CONFIG` dictionary. Misconfigurations are a common source of errors.
Fix: Refer to the official PySAML2 documentation's 'Configuration of PySAML2 entities' section. Utilize the provided example configuration files as a starting point and adapt them carefully, paying close attention to entity IDs, endpoints, certificates, and metadata.

Install

pip install pysaml2 Install PySAML2

Imports

Config
```
from saml2.config import Config
```
Saml2Client
```
from saml2.client import Saml2Client
```
BINDING_HTTP_REDIRECT
```
from saml2 import BINDING_HTTP_REDIRECT
```

Quickstart

This quickstart demonstrates the basic initialization of a PySAML2 Service Provider (SP) client. It sets up a minimal configuration using `saml2.config.Config` and creates a `saml2.client.Saml2Client` instance. For a functional SAML flow, you would need real IdP metadata, proper key/certificate files, and a web server to handle redirects and POST requests. Remember that `xmlsec1` must be installed on your system for signature and encryption operations.

import os
from saml2.config import Config
from saml2.client import Saml2Client
from saml2 import BINDING_HTTP_REDIRECT

# Minimal configuration for a Service Provider (SP)
# In a real application, this would be loaded from a file or more extensive setup.
SP_CONFIG = {
    "entityid": "http://localhost:8080/saml2/metadata",
    "service": {
        "sp": {
            "endpoints": {
                "assertion_consumer_service": [
                    ("http://localhost:8080/saml2/acs", BINDING_HTTP_REDIRECT),
                ],
                "single_logout_service": [
                    ("http://localhost:8080/saml2/slo", BINDING_HTTP_REDIRECT),
                ],
            },
            "idp": {
                # Example IdP metadata URL - replace with your actual IdP's metadata
                "http://idp.example.com/metadata": None
            },
            "key_file": os.environ.get("SAML_SP_KEY_FILE", "pki/mykey.pem"),
            "cert_file": os.environ.get("SAML_SP_CERT_FILE", "pki/mycert.pem"),
        }
    },
    "metadata": [
        {
            "class": "saml2.mdstore.MetaDataFile",
            "metadata": [(os.environ.get("SAML_IDP_METADATA_FILE", "idp.xml"),)]
        },
    ],
    "debug": True,
}

def initialize_saml_client():
    sp_config = Config()
    sp_config.load(SP_CONFIG, metadata_reload=False)
    client = Saml2Client(config=sp_config)
    print("SAML2 Client initialized successfully.")
    print(f"SP Entity ID: {client.config.entityid}")
    # In a real app, you would now use 'client' to handle SAML flows
    # e.g., create_authn_request, parse_response, etc.

if __name__ == "__main__":
    # Ensure dummy cert/key files exist for basic execution if not provided via env vars
    os.makedirs("pki", exist_ok=True)
    if not os.path.exists("pki/mykey.pem"):
        with open("pki/mykey.pem", "w") as f:
            f.write("# Dummy private key content\n")
    if not os.path.exists("pki/mycert.pem"):
        with open("pki/mycert.pem", "w") as f:
            f.write("# Dummy public certificate content\n")
    if not os.path.exists("idp.xml"):
        with open("idp.xml", "w") as f:
            f.write("<EntityDescriptor entityID='http://idp.example.com/metadata'/>")
    
    initialize_saml_client()

view raw JSON →