python3-saml Toolkit

1.16.0 · active · verified Thu Apr 09

The python3-saml library provides a robust SAML (Security Assertion Markup Language) toolkit for Python, enabling applications to act as a Service Provider (SP) for Single Sign-On (SSO) and Single Logout (SLO). It simplifies integration with various Identity Providers (IdPs). The current version is 1.16.0, and it maintains an active release cadence with updates typically every few months, focusing on security, bug fixes, and compatibility.

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to initialize the `OneLogin_Saml2_Auth` object with example settings and dummy request data. It shows how to obtain the Single Sign-On (SSO) URL for initiating an authentication flow and how to generate Service Provider (SP) metadata. For production, SAML settings must be securely loaded and contain valid certificate data and endpoint URLs for both the SP and the IdP.

import os
import json
from onelogin.saml2.auth import OneLogin_Saml2_Auth
from onelogin.saml2.settings import OneLogin_Saml2_Settings
from onelogin.saml2.constants import OneLogin_Saml2_Constants

# Dummy request data, replace with actual request data from your web framework
# This simulates the data typically extracted from a Flask/Django/FastAPI request object.
dummy_request_data = {
    'http_host': 'localhost:8000',
    'script_name': '/saml/sso',
    'server_port': '8000',
    'get_data': {}, # GET parameters
    'post_data': {}, # POST parameters
    'query_string': '',
    'https': 'off', # 'on' or 'off'
    'requested_url': 'http://localhost:8000/saml/sso',
    'metadata': {} # Used for metadata generation
}

# SAML settings are critical for proper functioning and security.
# In a real application, load these from a secure configuration management system,
# e.g., a JSON file specified by an environment variable.
settings_path = os.environ.get('ONELOGIN_SAML_SETTINGS_PATH', '')
settings_data = {}

if settings_path and os.path.exists(settings_path):
    try:
        with open(settings_path, 'r') as f:
            settings_data = json.load(f)
        print(f"Loaded settings from {settings_path}")
    except Exception as e:
        print(f"Error loading settings from {settings_path}: {e}")
else:
    # Minimal settings for demonstration (NOT PRODUCTION READY).
    # You MUST configure these with real SP and IdP details, including certificates.
    print("Using default minimal settings. Please provide a settings file for production.")
    settings_data = {
        'strict': True,
        'debug': True,
        'sp': {
            'entityId': 'http://localhost:8000/saml/metadata/',
            'assertionConsumerService': {
                'url': 'http://localhost:8000/saml/acs/',
                'binding': OneLogin_Saml2_Constants.BINDING_HTTP_POST
            },
            'singleLogoutService': {
                'url': 'http://localhost:8000/saml/sls/',
                'binding': OneLogin_Saml2_Constants.BINDING_HTTP_REDIRECT
            },
            'NameIDFormat': OneLogin_Saml2_Constants.NAMEID_EMAIL_ADDRESS,
            'x509cert': '', # Your SP public certificate
            'privateKey': '' # Your SP private key
        },
        'idp': {
            'entityId': 'http://idp.example.com/saml/metadata/',
            'singleSignOnService': {
                'url': 'http://idp.example.com/saml/sso/',
                'binding': OneLogin_Saml2_Constants.BINDING_HTTP_REDIRECT
            },
            'singleLogoutService': {
                'url': 'http://idp.example.com/saml/slo/',
                'binding': OneLogin_Saml2_Constants.BINDING_HTTP_REDIRECT
            },
            'x509cert': '' # IdP public certificate
        }
    }

try:
    # Initialize SAML toolkit with request data and settings
    auth = OneLogin_Saml2_Auth(dummy_request_data, settings_data)

    # Example 1: Get the SSO URL to redirect the user for login
    sso_url = auth.get_sso_url()
    print(f"\nSAML Auth initialized. SSO URL for IdP: {sso_url}")

    # Example 2: Get SP metadata (typically exposed at a /saml/metadata URL)
    settings = OneLogin_Saml2_Settings(settings_data)
    sp_metadata = settings.get_sp_metadata()
    print("\nGenerated SP Metadata (truncated to 500 chars):\n" + sp_metadata[:500] + "...")

    # In a real scenario, you'd handle SAML responses like this:
    # if 'SAMLResponse' in dummy_request_data['post_data']:
    #     auth.process_response()
    #     if not auth.is_authenticated():
    #         print(f"Authentication failed: {auth.get_errors()}")
    #     else:
    #         print(f"User authenticated: {auth.get_nameid()}")

except Exception as e:
    print(f"Error during SAML initialization or operation: {e}")

view raw JSON →