SecureBlackbox 2020 macOS Edition

Questions / Feedback?

SAMLSPServer Module

Properties   Methods   Events   Configuration Settings   Errors  

The SAMLSPServer component represents a SAML service provider.

Syntax

nsoftware.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 LoadIDPMetadata 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 MetadataURL 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 BaseDir 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 ProtectedResources property. If ProtectedResources is empty, the server considers all the files in BaseDir 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 AssertionConsumerService 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 module with short descriptions. Click on the links for further details.

ActiveTells whether the server is active and ready to process requests.
ArtifactResolutionServiceThe location of the artifact resolution service.
AssertionConsumerServiceThe location of the Assertion Consumer Service.
AssertionConsumerServiceBindingsBindings supported by the Assertion Consumer Service.
BaseDirBase directory on the server.
EncryptionCertificateThe certificate to be used to decrypt assertions.
ErrorOriginIndicates the endpoint where the error originates from.
ErrorSeverityThe severity of the error that happened.
ExternalCryptoProvides access to external signing and DC parameters.
HostSpecifies the host address of the SP server.
IssuerName identifier of the issuer of the SP's requests.
LogoutPageSpecifies the location of the logout page.
MetadataURLThe SP's metadata location.
MetaSigningCertificateSpecifies the metadata signing certificate.
PortSpecifies the listening port number.
PreferredIDPToSPBindingSpecifies the preferred IdP to SP binding.
ProtectedResourcesSpecifies the list of protected resources.
RedirectOnLogoutPageSpecifies the location to redirect the user on logout.
ServerCertificatesThe server's TLS certificates.
SignArtifactResolveRequestsSpecifies whether to sign artifact resolution requests.
SignAuthnRequestsSpecifies whether to sign Authn requests.
SigningCertificateThe certificate for signing the SP requests.
SigningChainThe signing certificate chain.
SignLogoutRequestsSpecifies whether to sign Logout requests.
SignMetadataSpecifies whether to sign the metadata.
SingleLogoutServiceThe URL of the single logout service.
SingleLogoutServiceBindingsDefines single logout service bindings.
SocketSettingsManages network connection settings.
SPToIDPBindingSpecifies the IdP to SP binding to use.
TLSSettingsManages TLS layer settings.
URLSpecifies the base URL of this SP server.
UseTLSEnables or disables the secure connection requirement.

Method List


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

ConfigSets or retrieves a configuration setting.
LoadIDPMetadataLoads the metadata required for information exchange with the identity provider.
SaveMetadataSaves the SP configuration to a metadata file.
StartStarts the SP server.
StopStops the IdP server.

Event List


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

AcceptReports an incoming connection.
ConnectReports an accepted connection.
DisconnectFires to report a disconnected client.
ErrorInformation about errors during data delivery.
ExternalSignHandles remote or external signing initiated by the server protocol.
NotificationThis event notifies the application about an underlying control flow event.
SessionClosedThis event is fired when the SP server has closed a session.
SessionEstablishedThis event is fired when a new session has been established.

Configuration Settings


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

BoundPortThe port that was bound by the server.
DualStackAllows the use of ip4 and ip6 simultaneously.
HandshakeTimeoutThe HTTPS handshake timeout.
MaxIssueInstantTimeDiffThe maximum issue-instant time delta.
PortRangeFromThe lower bound of allowed port scope to listen on.
PortRangeToThe higher bound of allowed port scope to listen on.
SendBufferSizeThe network send buffer size.
ServerNameSpecifies the server name for the created responses.
SessionTimeoutThe HTTP session timeout.
SessionTTLThe SAML session time-to-live value.
TempPathPath for storing temporary files.
CheckKeyIntegrityBeforeUseEnables or disable private key integrity check before use.
CookieCachingSpecifies whether a cookie cache should be used for HTTP(S) transports.
CookiesGets or sets local cookies for the component (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterationsSpecifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHEEnables or disables finite field DHE key exchange support in TLS clients.
GlobalCookiesGets or sets global cookies for all the HTTP transports.
HttpUserAgentSpecifies the user agent name to be used by all HTTP clients.
LogDestinationSpecifies the debug log destination.
LogDetailsSpecifies the debug log details to dump.
LogFileSpecifies the debug log filename.
LogFiltersSpecifies the debug log filters.
LogFlushModeSpecifies the log flush mode.
LogLevelSpecifies the debug log level.
LogMaxEventCountSpecifies the maximum number of events to cache before further action is taken.
LogRotationModeSpecifies the log rotation mode.
MaxASN1BufferLengthSpecifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepthSpecifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithmSpecifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolverSpecifies whether the client components should use own DNS resolver.
UseSharedSystemStoragesSpecifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSSEnforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandomEnables or disables the use of the OS PRNG.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 macOS Edition - Version 20.0 [Build 8165]