SecureBlackbox 2020 iOS Edition

Questions / Feedback?

SAMLSPServer Class

Properties   Methods   Events   Configuration Settings   Errors  

The SAMLSPServer class represents a SAML service provider.

Syntax

SecureBlackboxSAMLSPServer
SecureBlackboxSAMLSPServerSwift

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 class 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.
- encryptionCertBytesReturns raw certificate data in DER format.
- encryptionCertHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
- errorOriginIndicates the endpoint where the error originates from.
- errorSeverityThe severity of the error that happened.
- externalCryptoCustomParamsCustom parameters to be passed to the signing service (uninterpreted).
- externalCryptoDataAdditional data to be included in the async state and mirrored back by the requestor.
- externalCryptoExternalHashCalculationSpecifies whether the message hash is to be calculated at the external endpoint.
- externalCryptoHashAlgorithmSpecifies the request's signature hash algorithm.
- externalCryptoKeyIDThe ID of the pre-shared key used for DC request authentication.
- externalCryptoKeySecretThe pre-shared key used for DC request authentication.
- externalCryptoMethodSpecifies the asynchronous signing method.
- externalCryptoModeSpecifies the external cryptography mode.
- externalCryptoPublicKeyAlgorithmProvide public key algorithm here if the certificate is not available on the pre-signing stage.
- 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.
- metaSigningCertBytesReturns raw certificate data in DER format.
- metaSigningCertHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
- 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.
- serverCertCountThe number of records in the ServerCert arrays.
- serverCertBytes:(int)serverCertIndexReturns raw certificate data in DER format.
- serverCertHandle:(int)serverCertIndexAllows to get or set a 'handle', a unique identifier of the underlying property object.
- signArtifactResolveRequestsSpecifies whether to sign artifact resolution requests.
- signAuthnRequestsSpecifies whether to sign Authn requests.
- signingCertBytesReturns raw certificate data in DER format.
- signingCertHandleAllows to get or set a 'handle', a unique identifier of the underlying property object.
- signingChainCountThe number of records in the SigningChain arrays.
- signingChainBytes:(int)signingChainIndexReturns raw certificate data in DER format.
- signingChainHandle:(int)signingChainIndexAllows to get or set a 'handle', a unique identifier of the underlying property object.
- signLogoutRequestsSpecifies whether to sign Logout requests.
- signMetadataSpecifies whether to sign the metadata.
- singleLogoutServiceThe URL of the single logout service.
- singleLogoutServiceBindingsDefines single logout service bindings.
- socketIncomingSpeedLimitThe maximum number of bytes to read from the socket, per second.
- socketLocalAddressThe local network interface to bind the socket to.
- socketLocalPortThe local port number to bind the socket to.
- socketOutgoingSpeedLimitThe maximum number of bytes to write to the socket, per second.
- socketTimeoutThe maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.
- socketUseIPv6Enables or disables IP protocol version 6.
- SPToIDPBindingSpecifies the IdP to SP binding to use.
- TLSAutoValidateCertificatesSpecifies whether server-side TLS certificates should be validated automatically using internal validation rules.
- TLSBaseConfigurationSelects the base configuration for the TLS settings.
- TLSCiphersuitesA list of ciphersuites separated with commas or semicolons.
- TLSECCurvesDefines the elliptic curves to enable.
- TLSForceResumeIfDestinationChangesWhether to force TLS session resumption when the destination address changes.
- TLSPreSharedIdentityDefines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated.
- TLSPreSharedKeyContains the pre-shared for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16.
- TLSPreSharedKeyCiphersuiteDefines the ciphersuite used for PSK (Pre-Shared Key) negotiation.
- TLSRenegotiationAttackPreventionModeSelects renegotiation attack prevention mechanism.
- TLSRevocationCheckSpecifies the kind(s) of revocation check to perform.
- TLSSSLOptionsVarious 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.
- TLSTLSModeSpecifies the TLS mode to use.
- TLSUseExtendedMasterSecretEnables Extended Master Secret Extension, as defined in RFC 7627.
- TLSUseSessionResumptionEnables or disables TLS session resumption capability.
- TLSVersionsTh SSL/TLS versions to enable by default.
- 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 class 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 class with short descriptions. Click on the links for further details.

- onAcceptReports an incoming connection.
- onConnectReports an accepted connection.
- onDisconnectFires to report a disconnected client.
- onErrorInformation about errors during data delivery.
- onExternalSignHandles remote or external signing initiated by the server protocol.
- onNotificationThis event notifies the application about an underlying control flow event.
- onSessionClosedThis event is fired when the SP server has closed a session.
- onSessionEstablishedThis 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.

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 class (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 classes 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 iOS Edition - Version 20.0 [Build 8166]