0
# Configuration and Settings
1

2
SAML configuration management including settings validation, metadata generation, certificate handling, and IdP metadata parsing. The configuration system provides comprehensive tools for setting up Service Provider configurations and integrating with Identity Providers.
3

4
## Capabilities
5

6
### SAML Settings Management
7

8
Core configuration class that handles SP (Service Provider), IdP (Identity Provider), and security settings with comprehensive validation and certificate management.
9

10
```python { .api }
11
class OneLogin_Saml2_Settings:
12
    def __init__(self, settings: dict = None, custom_base_path: str = None, sp_validation_only: bool = False):
13
        """
14
        Initialize SAML settings.
15
        
16
        Parameters:
17
        - settings: SAML configuration dictionary
18
        - custom_base_path: Path to settings files and certificates
19
        - sp_validation_only: Skip IdP validation if True
20
        """
21
```
22

23
**Settings Structure:**
24
```python
25
settings = {
26
    "strict": True,  # Enable strict validation
27
    "debug": False,  # Enable debug mode
28
    "sp": {
29
        "entityId": "https://sp.example.com/metadata/",
30
        "assertionConsumerService": {
31
            "url": "https://sp.example.com/acs",
32
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
33
        },
34
        "singleLogoutService": {
35
            "url": "https://sp.example.com/sls", 
36
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
37
        },
38
        "NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
39
        "x509cert": "",  # SP certificate
40
        "privateKey": ""  # SP private key
41
    },
42
    "idp": {
43
        "entityId": "https://idp.example.com/metadata",
44
        "singleSignOnService": {
45
            "url": "https://idp.example.com/sso",
46
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
47
        },
48
        "singleLogoutService": {
49
            "url": "https://idp.example.com/slo",
50
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
51
        },
52
        "x509cert": "IdP Certificate"
53
    },
54
    "security": {
55
        "nameIdEncrypted": False,
56
        "authnRequestsSigned": False,
57
        "logoutRequestSigned": False,
58
        "wantMessagesSigned": False,
59
        "wantAssertionsSigned": False,
60
        "signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
61
    }
62
}
63
```
64

65
### Configuration Data Access
66

67
Methods to retrieve specific configuration sections and validate settings.
68

69
```python { .api }
70
def get_sp_data(self) -> dict:
71
    """
72
    Get Service Provider configuration data.
73
    
74
    Returns:
75
    Dictionary containing SP configuration
76
    """
77

78
def get_idp_data(self) -> dict:
79
    """
80
    Get Identity Provider configuration data.
81
    
82
    Returns:
83
    Dictionary containing IdP configuration
84
    """
85

86
def get_security_data(self) -> dict:
87
    """
88
    Get security configuration data.
89
    
90
    Returns:
91
    Dictionary containing security settings
92
    """
93

94
def get_contacts(self) -> dict:
95
    """
96
    Get contact person data.
97
    
98
    Returns:
99
    Dictionary containing contact information
100
    """
101

102
def get_organization(self) -> dict:
103
    """
104
    Get organization data.
105
    
106
    Returns:
107
    Dictionary containing organization information
108
    """
109
```
110

111
### Certificate Management
112

113
Handle X.509 certificates for SP and IdP cryptographic operations.
114

115
```python { .api }
116
def get_sp_cert(self) -> str:
117
    """
118
    Get SP x509 public certificate.
119
    
120
    Returns:
121
    SP certificate string or None
122
    """
123

124
def get_sp_key(self) -> str:
125
    """
126
    Get SP x509 private key.
127
    
128
    Returns:
129
    SP private key string or None
130
    """
131

132
def get_sp_cert_new(self) -> str:
133
    """
134
    Get new SP certificate for cert rollover.
135
    
136
    Returns:
137
    New SP certificate string or None
138
    """
139

140
def get_idp_cert(self) -> str:
141
    """
142
    Get IdP x509 public certificate.
143
    
144
    Returns:
145
    IdP certificate string or None
146
    """
147
```
148

149
### URL Configuration
150

151
Access to SAML endpoint URLs for SSO and SLO operations.
152

153
```python { .api }
154
def get_idp_sso_url(self) -> str:
155
    """
156
    Get IdP Single Sign-On URL.
157
    
158
    Returns:
159
    SSO URL string
160
    """
161

162
def get_idp_slo_url(self) -> str:
163
    """
164
    Get IdP Single Logout URL.
165
    
166
    Returns:
167
    SLO URL string
168
    """
169

170
def get_idp_slo_response_url(self) -> str:
171
    """
172
    Get IdP SLO response URL.
173
    
174
    Returns:
175
    SLO response URL string
176
    """
177
```
178

179
### Settings Validation
180

181
Comprehensive validation methods for SAML configuration components.
182

183
```python { .api }
184
def check_settings(self, settings: dict) -> list:
185
    """
186
    Validate complete SAML settings.
187
    
188
    Parameters:
189
    - settings: Settings dictionary to validate
190
    
191
    Returns:
192
    List of validation error strings
193
    """
194

195
def check_idp_settings(self, settings: dict) -> list:
196
    """
197
    Validate IdP-specific settings.
198
    
199
    Parameters:
200
    - settings: Settings dictionary to validate
201
    
202
    Returns:
203
    List of IdP validation errors
204
    """
205

206
def check_sp_settings(self, settings: dict) -> list:
207
    """
208
    Validate SP-specific settings.
209
    
210
    Parameters:
211
    - settings: Settings dictionary to validate
212
    
213
    Returns:
214
    List of SP validation errors
215
    """
216

217
def check_sp_certs(self) -> bool:
218
    """
219
    Validate SP certificates exist and are valid.
220
    
221
    Returns:
222
    True if certificates are valid, False otherwise
223
    """
224
```
225

226
### Metadata Generation
227

228
Generate and validate SAML metadata XML for Service Provider registration with Identity Providers.
229

230
```python { .api }
231
def get_sp_metadata(self) -> str:
232
    """
233
    Generate SP metadata XML.
234
    
235
    Returns:
236
    Complete SP metadata XML string
237
    """
238

239
def validate_metadata(self, xml: str) -> list:
240
    """
241
    Validate SP metadata XML.
242
    
243
    Parameters:
244
    - xml: Metadata XML to validate
245
    
246
    Returns:
247
    List of validation error strings
248
    """
249
```
250

251
### Configuration State Management
252

253
Control validation modes and debug settings.
254

255
```python { .api }
256
def set_strict(self, value: bool) -> None:
257
    """
258
    Set strict validation mode.
259
    
260
    Parameters:
261
    - value: Whether to enable strict mode
262
    """
263

264
def is_strict(self) -> bool:
265
    """
266
    Check if strict mode is active.
267
    
268
    Returns:
269
    True if strict mode is enabled
270
    """
271

272
def is_debug_active(self) -> bool:
273
    """
274
    Check if debug mode is active.
275
    
276
    Returns:
277
    True if debug mode is enabled
278
    """
279

280
def get_errors(self) -> list:
281
    """
282
    Get validation error list.
283
    
284
    Returns:
285
    List of validation error strings
286
    """
287
```
288

289
### Path Management
290

291
Methods for accessing toolkit directory paths and configuration locations.
292

293
```python { .api }
294
def get_base_path(self) -> str:
295
    """
296
    Get the base toolkit folder path.
297
    
298
    Returns:
299
    Absolute path to the base toolkit directory
300
    """
301

302
def get_cert_path(self) -> str:
303
    """
304
    Get the certificate folder path.
305
    
306
    Returns:
307
    Absolute path to the certificate directory
308
    """
309

310
def get_lib_path(self) -> str:
311
    """
312
    Get the library folder path.
313
    
314
    Returns:
315
    Absolute path to the library directory
316
    """
317

318
def get_schemas_path(self) -> str:
319
    """
320
    Get the schemas folder path.
321
    
322
    Returns:
323
    Absolute path to the XSD schemas directory
324
    """
325
```
326

327
## SP Metadata Generation
328

329
Advanced metadata generation with certificate management, signing, and organizational information.
330

331
```python { .api }
332
class OneLogin_Saml2_Metadata:
333
    @classmethod
334
    def builder(cls, sp: dict, authnsign: bool = False, wsign: bool = False, valid_until: str = None, cache_duration: int = None, contacts: dict = None, organization: dict = None) -> str:
335
        """
336
        Build complete SP metadata XML.
337
        
338
        Parameters:
339
        - sp: SP configuration data
340
        - authnsign: Whether AuthN requests are signed
341
        - wsign: Whether assertions should be signed
342
        - valid_until: Metadata expiry date
343
        - cache_duration: Cache duration in seconds
344
        - contacts: Contact person information
345
        - organization: Organization information
346
        
347
        Returns:
348
        Complete SP metadata XML string
349
        """
350
```
351

352
### Certificate Metadata Management
353

354
Add X.509 certificates to metadata for key management and encryption.
355

356
```python { .api }
357
@classmethod
358
def add_x509_key_descriptors(cls, metadata: str, cert: str = None, add_encryption: bool = True) -> str:
359
    """
360
    Add X.509 certificate descriptors to metadata.
361
    
362
    Parameters:
363
    - metadata: Existing metadata XML
364
    - cert: X.509 certificate to add
365
    - add_encryption: Whether to add encryption key descriptor
366
    
367
    Returns:
368
    Updated metadata XML with key descriptors
369
    """
370
```
371

372
### Metadata Signing
373

374
Digitally sign metadata XML for enhanced security and trust.
375

376
```python { .api }
377
@staticmethod
378
def sign_metadata(metadata: str, key: str, cert: str, sign_algorithm: str = OneLogin_Saml2_Constants.RSA_SHA256, digest_algorithm: str = OneLogin_Saml2_Constants.SHA256) -> str:
379
    """
380
    Sign metadata XML with provided key/certificate.
381
    
382
    Parameters:
383
    - metadata: SAML metadata XML to sign
384
    - key: X.509 private key for signing
385
    - cert: X.509 certificate for signing
386
    - sign_algorithm: Signature algorithm (default: RSA-SHA256)
387
    - digest_algorithm: Digest algorithm (default: SHA256)
388
    
389
    Returns:
390
    Signed metadata XML
391
    """
392
```
393

394
## IdP Metadata Parsing
395

396
Parse Identity Provider metadata to automatically configure SAML settings.
397

398
```python { .api }
399
class OneLogin_Saml2_IdPMetadataParser:
400
    @classmethod
401
    def get_metadata(cls, url: str, validate_cert: bool = True, timeout: int = None, headers: dict = None) -> str:
402
        """
403
        Retrieve IdP metadata XML from URL.
404
        
405
        Parameters:
406
        - url: URL where IdP metadata is published
407
        - validate_cert: Whether to validate HTTPS certificates
408
        - timeout: Request timeout in seconds  
409
        - headers: Additional HTTP headers
410
        
411
        Returns:
412
        Raw metadata XML string
413
        
414
        Raises:
415
        Exception if metadata is invalid or URL unreachable
416
        """
417
```
418

419
### Remote Metadata Processing
420

421
Retrieve and parse remote IdP metadata in a single operation.
422

423
```python { .api }
424
@classmethod
425
def parse_remote(cls, url: str, validate_cert: bool = True, entity_id: str = None, timeout: int = None, **kwargs) -> dict:
426
    """
427
    Retrieve and parse remote IdP metadata.
428
    
429
    Parameters:
430
    - url: IdP metadata URL
431
    - validate_cert: Certificate validation flag
432
    - entity_id: Specific entity ID for multi-entity metadata
433
    - timeout: Request timeout
434
    - **kwargs: Additional parameters passed to parse method
435
    
436
    Returns:
437
    Parsed settings dictionary
438
    """
439
```
440

441
### Metadata XML Parsing
442

443
Parse IdP metadata XML and extract SAML configuration data.
444

445
```python { .api }
446
@classmethod
447
def parse(cls, idp_metadata: str, required_sso_binding: str = OneLogin_Saml2_Constants.BINDING_HTTP_REDIRECT, required_slo_binding: str = OneLogin_Saml2_Constants.BINDING_HTTP_REDIRECT, entity_id: str = None) -> dict:
448
    """
449
    Parse IdP metadata XML and extract configuration.
450
    
451
    Parameters:
452
    - idp_metadata: IdP metadata XML
453
    - required_sso_binding: Required SSO binding (POST or REDIRECT)
454
    - required_slo_binding: Required SLO binding (POST or REDIRECT)
455
    - entity_id: Specific entity ID for multi-entity metadata
456
    
457
    Returns:
458
    Dictionary with extracted IdP settings
459
    """
460
```
461

462
**Extracted Settings Structure:**
463
```python
464
{
465
    "idp": {
466
        "entityId": "https://idp.example.com/metadata",
467
        "singleSignOnService": {
468
            "url": "https://idp.example.com/sso",
469
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
470
        },
471
        "singleLogoutService": {
472
            "url": "https://idp.example.com/slo", 
473
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
474
        },
475
        "x509cert": "single_cert_string",
476
        # OR for multiple certificates:
477
        "x509certMulti": {
478
            "signing": ["cert1", "cert2"],
479
            "encryption": ["cert3", "cert4"]
480
        }
481
    },
482
    "security": {
483
        "authnRequestsSigned": True
484
    },
485
    "sp": {
486
        "NameIDFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
487
    }
488
}
489
```
490

491
## Usage Patterns
492

493
### Settings Configuration from Files
494
```python
495
# Load from settings.json and advanced_settings.json
496
settings = OneLogin_Saml2_Settings(custom_base_path="/path/to/config")
497

498
# Load from dictionary
499
settings_dict = {
500
    "sp": {...},
501
    "idp": {...},
502
    "security": {...}
503
}
504
settings = OneLogin_Saml2_Settings(settings_dict)
505

506
# Validate configuration
507
errors = settings.check_settings(settings_dict)
508
if errors:
509
    print(f"Configuration errors: {errors}")
510
```
511

512
### Metadata Generation
513
```python
514
from onelogin.saml2.metadata import OneLogin_Saml2_Metadata
515
from onelogin.saml2.settings import OneLogin_Saml2_Settings
516

517
settings = OneLogin_Saml2_Settings(config_dict)
518
sp_data = settings.get_sp_data()
519

520
# Generate basic metadata
521
metadata_xml = OneLogin_Saml2_Metadata.builder(sp_data)
522

523
# Generate signed metadata with organizational info
524
contacts = {
525
    "technical": {
526
        "givenName": "Tech Team",
527
        "emailAddress": "tech@example.com"
528
    }
529
}
530

531
organization = {
532
    "en-US": {
533
        "name": "My Organization",
534
        "displayname": "My Org",
535
        "url": "https://myorg.com"
536
    }
537
}
538

539
signed_metadata = OneLogin_Saml2_Metadata.builder(
540
    sp_data,
541
    authnsign=True,
542
    wsign=True,
543
    contacts=contacts,
544
    organization=organization
545
)
546

547
# Sign the metadata
548
sp_key = settings.get_sp_key()
549
sp_cert = settings.get_sp_cert()
550
final_metadata = OneLogin_Saml2_Metadata.sign_metadata(
551
    signed_metadata, sp_key, sp_cert
552
)
553
```
554

555
### IdP Metadata Integration
556
```python
557
from onelogin.saml2.idp_metadata_parser import OneLogin_Saml2_IdPMetadataParser
558

559
# Parse remote IdP metadata
560
idp_settings = OneLogin_Saml2_IdPMetadataParser.parse_remote(
561
    "https://idp.example.com/metadata",
562
    entity_id="https://specific.idp.entity.id"
563
)
564

565
# Merge with existing SP settings
566
complete_settings = {
567
    "sp": sp_configuration,
568
    **idp_settings
569
}
570

571
# Initialize settings with parsed IdP data
572
settings = OneLogin_Saml2_Settings(complete_settings)
573
```
574

575
### Certificate Management
576
```python
577
# Get certificates for validation
578
sp_cert = settings.get_sp_cert()
579
sp_key = settings.get_sp_key()
580
idp_cert = settings.get_idp_cert()
581

582
# Validate certificate availability
583
cert_valid = settings.check_sp_certs()
584

585
# Access security configuration
586
security_config = settings.get_security_data()
587
print(f"Require signed assertions: {security_config.get('wantAssertionsSigned')}")
588
```