SAMLSPServer Component

Properties   Methods   Events   Configuration Settings   Errors  

The SAMLSPServer component represents a SAML service provider.

Syntax

TsbxSAMLSPServer

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.
  
  view source

  server.LoadIDPMetadata("their_metadata.xml"); // contains "<?xml version="1.0"?><md:EntityDescriptor ID="ab12" ... </md:EntityDescriptor>";
• Configure the main server capabilities:
  
  view source

  // 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:
  
  view source

  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.
  
  view source

  server.SaveMetadata("my_metadata.xml");

You are now ready to start the server:
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 component with short descriptions. Click on the links for further details.

Active	Tells whether the server is active and ready to process requests.
ArtifactResolutionService	The location of the artifact resolution service.
AssertionConsumerService	The location of the Assertion Consumer Service.
AssertionConsumerServiceBindings	Bindings supported by the Assertion Consumer Service.
BaseDir	Base directory on the server.
EncryptionCertificate	The certificate to be used to decrypt assertions.
ErrorOrigin	Indicates the endpoint where the error originates from.
ErrorSeverity	The severity of the error that happened.
ExternalCrypto	Provides access to external signing and DC parameters.
Host	Specifies the host address of the SP server.
Issuer	Name identifier of the issuer of the SP's requests.
LogoutPage	Specifies the location of the logout page.
MetadataURL	The SP's metadata location.
MetaSigningCertificate	Specifies the metadata signing certificate.
Port	Specifies the listening port number.
PreferredIDPToSPBinding	Specifies the preferred IdP to SP binding.
ProtectedResources	Specifies the list of protected resources.
RedirectOnLogoutPage	Specifies the location to redirect the user on logout.
ServerCertificates	The server's TLS certificates.
SignArtifactResolveRequests	Specifies whether to sign artifact resolution requests.
SignAuthnRequests	Specifies whether to sign Authn requests.
SigningCertificate	The certificate for signing the SP requests.
SigningChain	The signing certificate chain.
SignLogoutRequests	Specifies whether to sign Logout requests.
SignMetadata	Specifies whether to sign the metadata.
SingleLogoutService	The URL of the single logout service.
SingleLogoutServiceBindings	Defines single logout service bindings.
SocketSettings	Manages network connection settings.
SPToIDPBinding	Specifies the IdP to SP binding to use.
TLSSettings	Manages TLS layer settings.
URL	Specifies the base URL of this SP server.
UseTLS	Enables or disables the secure connection requirement.

Method List

---

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

Config	Sets or retrieves a configuration setting.
LoadIDPMetadata	Loads the metadata required for information exchange with the identity provider.
LoadIDPMetadataFromStream	Loads the metadata required for information exchange with the identity provider.
SaveMetadata	Saves the SP configuration to a metadata file.
SaveMetadataToStream	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 component with short descriptions. Click on the links for further details.

Accept	Reports an incoming connection.
Connect	Reports an accepted connection.
Disconnect	Fires to report a disconnected client.
Error	Information about errors during data delivery.
ExternalSign	Handles remote or external signing initiated by the server protocol.
Notification	This event notifies the application about an underlying control flow event.
SessionClosed	This event is fired when the SP server has closed a session.
SessionEstablished	This event is fired when a new session has been established.

Configuration Settings

---

The following is a list of configuration settings for the component 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 component (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 components 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.