SAMLSPServer Class

Properties Methods Events Configuration Settings Errors

The SAMLSPServer class represents a SAML service provider.

Syntax

class secureblackbox.SAMLSPServer

Remarks

The Service Provider in the SAML exchange flow represents the web server that receives and accepts authentication assertions issued by the Identity Provider for single sign-on (SSO). Most commonly, an SP server is part of the application responsible for communicating with an Identity Provider to establish the authenticity of application users.

SAMLSPServer provides easy means of integrating the SAML Service Provider functionality into your application. It presents a fully-features SP endpoint with its own HTTP(S) and assertion validation engines.

Please find below a step-by-step guide on setting up your own SAML SP endpoint.

Register the IdP metadata using the load_idp_metadata method or its stream-based variant. Most IDPs let you download their metadata in XML format. The metadata file contains general parameters of the IdP endpoint, such as its web address and algorithm requirements.
```
  server.LoadIDPMetadata("their_metadata.xml"); // contains "<?xml version="1.0"?><md:EntityDescriptor ID="ab12" ... </md:EntityDescriptor>";   
```

Configure the main server capabilities:

  // public server endpoint (use "https://" and/or port 443 if required)
  server.URL = "http://sp.myapp.com";
  server.Port = 80; 

  // IdP triggers this URL to pull metadata
  server.MetadataURL = '/sp/metadata'; 

  // ACS is th "main" SP endpoint that receives assertions from the IdP
  server.AssertionConsumerService = '/sp/AssertionConsumerService';
  server.SPToIDPBinding = csbtRedirect; // the SP will use HTTP redirect to forward the browser to the IdP when required
  server.AssertionConsumerServiceBindings = 'POST'; // and we want the IdP to use POST to submit its assertions
  server.PreferredIDPToSPBinding = csbtPOST;

  // Single logout service setup
  server.SingleLogoutService = '/sp/SingleLogoutService';
  server.SingleLogoutServiceBindings = 'Redirect,POST,Artifact';
  server.LogoutPage = '/sp/logout';
  server.RedirectOnLogoutPage = 'https://www.nsoftware.com';

  // The document root of the server on the local system
  server.BaseDir = "D:\\Inetpub\\SAMLSP";

  // Security parameters: indicating that we want to sign both
  // the metadata and the requests
  server.SignAuthnRequests = true;
  server.SignMetadata = true;

  // We need to attach certificates to be able to sign.
  // Assume we have loaded our signing certificate into
  // a CertificateManager object.
  server.SigningCertificate = mgr.Certificate;
  server.MetaSigningCertificate = mgr.Certificate;

Personalize the server:

  server.Config("OrganizationName=My Organization Ltd");
  server.Config("OrganizationDisplayName=My Organization Pet Supplies");
  server.Config("OrganizationURL=http://myorg.com");
  server.Config("SigDigestMethod=http://www.w3.org/2001/04/xmlenc#sha256");
  server.Config("SigMethod=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256");
  server.Config("WantAssertionsSigned=true");

Optionally, save metadata to an XML file. This will let you send/upload it to the IdP, so they could set your SP up. Some IdPs can download the metadata right from your SP using the metadata_url that you've provided above, in which case saving it to a file is not necessary.
```
  server.SaveMetadata("my_metadata.xml");
```

You are now ready to start the server:

  server.Start();

The server should now be running on the local system, listening to incoming connections on the port that you have specified above (80). Use your browser to check if the server is responding by navigating to the metadata URL (http://127.0.0.1:80/sp/metadata). If the server has been set up right, you should see something like this:

Now let us actually try to use the SAML functionality. Copy an arbitrary file - for example, a recent photo of your cat - to the directory you provided earlier via the base_dir property (D:\Inetpub\SAMLSP). Having copied the file (suppose it is called clifford.jpg), try to access it in your browser by navigating to http://127.0.0.1:80/clifford.jpg.

This is where SAML kicks in. Since you are not authenticated for the SP server yet (we have just launched it, so no one is), the server redirects your browser to the IdP endpoint for authentication. The address of the IdP is taken from the their_metadata.xml file that you have loaded at the very beginning.

Note: you can configure which resources to restrict access to using the protected_resources property. If protected_resources is empty, the server considers all the files in base_dir and its subfolders to be protected.

It is now the IdP services turn to authenticate you. Most IdPs on this stage will present you with a login form. Yet, if you have signed in recently, the IdP may still remember you, in which case it will skip the form and proceed directly to the next step. After establishing and proving your identity, the IdP will generate an assertion, a signed proof that effectively states that the IdP knows who you are and have verified your identity rigorously. Think of the assertion as your unique pass to the resources protected by the SP. The IdP will then submit that assertion back to the SP at its assertion_consumer_service endpoint, again using your browser.

Note that the SP service knows nothing about how IdP authenticates you. All the SP is interested in is an assertion.

If the assertion is well-formed and its signature is valid, the SAML exchange completes. At this point the SP accepts the assertion and creates a session for you. You can now access the resources protected by the SP for as long as the session lasts. If this step succeeds, you should see the photo of your cat in your browser.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.


active	Tells whether the server is active and ready to process requests.
artifact_resolution_service	The location of the artifact resolution service.
assertion_consumer_service	The location of the Assertion Consumer Service.
assertion_consumer_service_bindings	Bindings supported by the Assertion Consumer Service.
base_dir	Base directory on the server.
encryption_cert_bytes	Returns raw certificate data in DER format.
encryption_cert_handle	Allows to get or set a 'handle', a unique identifier of the underlying property object.
error_origin	Indicates the endpoint where the error originates from.
error_severity	The severity of the error that happened.
external_crypto_custom_params	Custom parameters to be passed to the signing service (uninterpreted).
external_crypto_data	Additional data to be included in the async state and mirrored back by the requestor.
external_crypto_external_hash_calculation	Specifies whether the message hash is to be calculated at the external endpoint.
external_crypto_hash_algorithm	Specifies the request's signature hash algorithm.
external_crypto_key_id	The ID of the pre-shared key used for DC request authentication.
external_crypto_key_secret	The pre-shared key used for DC request authentication.
external_crypto_method	Specifies the asynchronous signing method.
external_crypto_mode	Specifies the external cryptography mode.
external_crypto_public_key_algorithm	Provide public key algorithm here if the certificate is not available on the pre-signing stage.
host	Specifies the host address of the SP server.
issuer	Name identifier of the issuer of the SP's requests.
logout_page	Specifies the location of the logout page.
metadata_url	The SP's metadata location.
meta_signing_cert_bytes	Returns raw certificate data in DER format.
meta_signing_cert_handle	Allows to get or set a 'handle', a unique identifier of the underlying property object.
port	Specifies the listening port number.
preferred_idp_to_sp_binding	Specifies the preferred IdP to SP binding.
protected_resources	Specifies the list of protected resources.
redirect_on_logout_page	Specifies the location to redirect the user on logout.
server_cert_count	The number of records in the ServerCert arrays.
server_cert_bytes	Returns raw certificate data in DER format.
server_cert_handle	Allows to get or set a 'handle', a unique identifier of the underlying property object.
sign_artifact_resolve_requests	Specifies whether to sign artifact resolution requests.
sign_authn_requests	Specifies whether to sign Authn requests.
signing_cert_bytes	Returns raw certificate data in DER format.
signing_cert_handle	Allows to get or set a 'handle', a unique identifier of the underlying property object.
signing_chain_count	The number of records in the SigningChain arrays.
signing_chain_bytes	Returns raw certificate data in DER format.
signing_chain_handle	Allows to get or set a 'handle', a unique identifier of the underlying property object.
sign_logout_requests	Specifies whether to sign Logout requests.
sign_metadata	Specifies whether to sign the metadata.
single_logout_service	The URL of the single logout service.
single_logout_service_bindings	Defines single logout service bindings.
socket_incoming_speed_limit	The maximum number of bytes to read from the socket, per second.
socket_local_address	The local network interface to bind the socket to.
socket_local_port	The local port number to bind the socket to.
socket_outgoing_speed_limit	The maximum number of bytes to write to the socket, per second.
socket_timeout	The maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.
socket_use_i_pv6	Enables or disables IP protocol version 6.
sp_to_idp_binding	Specifies the IdP to SP binding to use.
tls_auto_validate_certificates	Specifies whether server-side TLS certificates should be validated automatically using internal validation rules.
tls_base_configuration	Selects the base configuration for the TLS settings.
tls_ciphersuites	A list of ciphersuites separated with commas or semicolons.
tlsec_curves	Defines the elliptic curves to enable.
tls_force_resume_if_destination_changes	Whether to force TLS session resumption when the destination address changes.
tls_pre_shared_identity	Defines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated.
tls_pre_shared_key	Contains the pre-shared for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16.
tls_pre_shared_key_ciphersuite	Defines the ciphersuite used for PSK (Pre-Shared Key) negotiation.
tls_renegotiation_attack_prevention_mode	Selects renegotiation attack prevention mechanism.
tls_revocation_check	Specifies the kind(s) of revocation check to perform.
tlsssl_options	Various SSL (TLS) protocol options, set of cssloExpectShutdownMessage 0x001 Wait for the close-notify message when shutting down the connection cssloOpenSSLDTLSWorkaround 0x002 (DEPRECATED) Use a DTLS version workaround when talking to very old OpenSSL versions cssloDisableKexLengthAlignment 0x004 Do not align the client-side PMS by the RSA modulus size.
tlstls_mode	Specifies the TLS mode to use.
tls_use_extended_master_secret	Enables Extended Master Secret Extension, as defined in RFC 7627.
tls_use_session_resumption	Enables or disables TLS session resumption capability.
tls_versions	Th SSL/TLS versions to enable by default.
url	Specifies the base URL of this SP server.
use_tls	Enables or disables the secure connection requirement.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.


config	Sets or retrieves a configuration setting.
load_idp_metadata	Loads the metadata required for information exchange with the identity provider.
save_metadata	Saves the SP configuration to a metadata file.
start	Starts the SP server.
stop	Stops the IdP server.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.


on_accept	Reports an incoming connection.
on_connect	Reports an accepted connection.
on_disconnect	Fires to report a disconnected client.
on_error	Information about errors during data delivery.
on_external_sign	Handles remote or external signing initiated by the server protocol.
on_notification	This event notifies the application about an underlying control flow event.
on_session_closed	This event is fired when the SP server has closed a session.
on_session_established	This event is fired when a new session has been established.

Configuration Settings

The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.


BoundPort	The port that was bound by the server.
DualStack	Allows the use of ip4 and ip6 simultaneously.
HandshakeTimeout	The HTTPS handshake timeout.
MaxIssueInstantTimeDiff	The maximum issue-instant time delta.
PortRangeFrom	The lower bound of allowed port scope to listen on.
PortRangeTo	The higher bound of allowed port scope to listen on.
SendBufferSize	The network send buffer size.
ServerName	Specifies the server name for the created responses.
SessionTimeout	The HTTP session timeout.
SessionTTL	The SAML session time-to-live value.
TempPath	Path for storing temporary files.
CheckKeyIntegrityBeforeUse	Enables or disable private key integrity check before use.
CookieCaching	Specifies whether a cookie cache should be used for HTTP(S) transports.
Cookies	Gets or sets local cookies for the class (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterations	Specifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHE	Enables or disables finite field DHE key exchange support in TLS clients.
GlobalCookies	Gets or sets global cookies for all the HTTP transports.
HttpUserAgent	Specifies the user agent name to be used by all HTTP clients.
LogDestination	Specifies the debug log destination.
LogDetails	Specifies the debug log details to dump.
LogFile	Specifies the debug log filename.
LogFilters	Specifies the debug log filters.
LogFlushMode	Specifies the log flush mode.
LogLevel	Specifies the debug log level.
LogMaxEventCount	Specifies the maximum number of events to cache before further action is taken.
LogRotationMode	Specifies the log rotation mode.
MaxASN1BufferLength	Specifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepth	Specifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithm	Specifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolver	Specifies whether the client classes should use own DNS resolver.
UseSharedSystemStorages	Specifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSS	Enforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandom	Enables or disables the use of the OS PRNG.