0
# Python3-SAML
1

2
A comprehensive SAML 2.0 toolkit for Python applications that enables Single Sign-On (SSO) and Single Logout (SLO) functionality. This library allows you to implement SAML Service Provider (SP) integration with any Identity Provider (IdP), supporting both SP-initiated and IdP-initiated workflows with robust security features.
3

4
## Package Information
5

6
- **Package Name**: python3-saml
7
- **Language**: Python
8
- **Installation**: `pip install python3-saml`
9
- **Dependencies**: `lxml>=4.6.5`, `isodate>=0.6.1`, `xmlsec>=1.3.9`
10

11
## Core Imports
12

13
```python
14
from onelogin.saml2.auth import OneLogin_Saml2_Auth
15
from onelogin.saml2.settings import OneLogin_Saml2_Settings
16
```
17

18
Common imports for different components:
19

20
```python
21
from onelogin.saml2.response import OneLogin_Saml2_Response
22
from onelogin.saml2.utils import OneLogin_Saml2_Utils
23
from onelogin.saml2.constants import OneLogin_Saml2_Constants
24
from onelogin.saml2.errors import OneLogin_Saml2_Error, OneLogin_Saml2_ValidationError
25
```
26

27
## Basic Usage
28

29
```python
30
from onelogin.saml2.auth import OneLogin_Saml2_Auth
31

32
# Initialize with request data and settings
33
def init_saml_auth(request):
34
    auth = OneLogin_Saml2_Auth(request, old_settings)
35
    return auth
36

37
# Initiate SSO
38
def sso():
39
    auth = init_saml_auth(request)
40
    auth.login()  # Redirects to IdP
41

42
# Process SAML Response
43
def acs():  # Assertion Consumer Service
44
    auth = init_saml_auth(request)
45
    auth.process_response()
46
    
47
    if auth.is_authenticated():
48
        # User authenticated successfully
49
        attributes = auth.get_attributes()
50
        nameid = auth.get_nameid()
51
        session_index = auth.get_session_index()
52
        # Store session data
53
    else:
54
        # Authentication failed
55
        errors = auth.get_errors()
56

57
# Initiate Single Logout
58
def slo():
59
    auth = init_saml_auth(request)
60
    auth.logout()  # Redirects to IdP for logout
61

62
# Process Logout Request/Response
63
def sls():  # Single Logout Service
64
    auth = init_saml_auth(request)
65
    auth.process_slo(delete_session_cb=lambda: clear_session())
66
```
67

68
## Architecture
69

70
The python3-saml toolkit follows a modular architecture organized around SAML workflow components:
71

72
- **Auth**: Central orchestrator managing SSO/SLO workflows and request/response processing
73
- **Settings**: Configuration management with security validation and metadata generation
74
- **Message Processing**: Specialized classes for handling SAML requests and responses
75
- **Utilities**: Cryptographic operations, XML processing, and URL handling
76
- **Constants**: SAML 2.0 specification constants and error definitions
77

78
This design enables session-less operation to avoid conflicts with application session management while providing both high-level convenience methods and low-level control for custom implementations.
79

80
## Capabilities
81

82
### Authentication and SSO/SLO
83

84
Core SAML authentication functionality including SSO initiation, response processing, logout handling, and session management. The Auth class serves as the primary interface for all SAML operations.
85

86
```python { .api }
87
class OneLogin_Saml2_Auth:
88
    def __init__(self, request_data: dict, old_settings: dict = None, custom_base_path: str = None): ...
89
    def login(self, return_to: str = None, force_authn: bool = False, is_passive: bool = False, set_nameid_policy: bool = True, name_id_value_req: str = None) -> None: ...
90
    def process_response(self, request_id: str = None) -> None: ...
91
    def process_slo(self, keep_local_session: bool = False, request_id: str = None, delete_session_cb: callable = None) -> None: ...
92
    def logout(self, return_to: str = None, name_id: str = None, session_index: str = None, nq: str = None, name_id_format: str = None, spnq: str = None) -> None: ...
93
    def is_authenticated(self) -> bool: ...
94
    def get_attributes(self) -> dict: ...
95
    def get_nameid(self) -> str: ...
96
```
97

98
[Authentication and SSO/SLO](./authentication.md)
99

100
### Configuration and Settings
101

102
SAML configuration management including settings validation, metadata generation, and security parameter handling. Supports both JSON and dictionary-based configuration with comprehensive validation.
103

104
```python { .api }
105
class OneLogin_Saml2_Settings:
106
    def __init__(self, settings: dict = None, custom_base_path: str = None, sp_validation_only: bool = False): ...
107
    def get_sp_data(self) -> dict: ...
108
    def get_idp_data(self) -> dict: ...
109
    def get_security_data(self) -> dict: ...
110
    def get_sp_metadata(self) -> str: ...
111
    def check_settings(self, settings: dict) -> list: ...
112
```
113

114
[Configuration and Settings](./configuration.md)
115

116
### SAML Message Processing
117

118
Specialized classes for handling SAML protocol messages including authentication requests, logout requests/responses, and SAML response validation with comprehensive security checks.
119

120
```python { .api }
121
class OneLogin_Saml2_Response:
122
    def __init__(self, settings: OneLogin_Saml2_Settings, response: str): ...
123
    def is_valid(self, request_data: dict, request_id: str = None, raise_exceptions: bool = False) -> bool: ...
124
    def get_attributes(self) -> dict: ...
125
    def get_nameid(self) -> str: ...
126

127
class OneLogin_Saml2_Authn_Request:
128
    def __init__(self, settings: OneLogin_Saml2_Settings, force_authn: bool = False, is_passive: bool = False, set_nameid_policy: bool = True, name_id_value_req: str = None): ...
129
    def get_request(self, deflate: bool = True) -> str: ...
130
```
131

132
[SAML Message Processing](./message-processing.md)
133

134
### Utilities and Security
135

136
Comprehensive utilities for cryptographic operations, XML processing, URL handling, certificate management, and security validation. Includes robust error handling and SAML-specific constants.
137

138
```python { .api }
139
class OneLogin_Saml2_Utils:
140
    @staticmethod
141
    def generate_unique_id() -> str: ...
142
    @staticmethod
143
    def validate_sign(xml: str, cert: str = None, fingerprint: str = None, fingerprintalg: str = 'sha1', validatecert: bool = False, debug: bool = False, xpath: str = None, multicerts: list = None, raise_exceptions: bool = False) -> bool: ...
144
    @staticmethod
145
    def add_sign(xml: str, key: str, cert: str, debug: bool = False, sign_algorithm: str = OneLogin_Saml2_Constants.RSA_SHA256, digest_algorithm: str = OneLogin_Saml2_Constants.SHA256) -> str: ...
146
    @staticmethod
147
    def decrypt_element(encrypted_data: str, key: str, debug: bool = False, inplace: bool = False) -> str: ...
148
```
149

150
[Utilities and Security](./utilities.md)
151

152
## Types
153

154
```python { .api }
155
# Request data structure expected by Auth constructor
156
RequestData = dict  # Contains 'https', 'http_host', 'server_port', 'script_name', 'get_data', 'post_data'
157

158
# Settings structure for SAML configuration
159
SettingsDict = dict  # Contains 'sp', 'idp', 'security' sections
160

161
# Error constants for validation and processing
162
class OneLogin_Saml2_Error(Exception): ...
163
class OneLogin_Saml2_ValidationError(OneLogin_Saml2_Error): ...
164
```