The SAMLSPServer component represents a SAML service provider.
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.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.
The following is the full list of the properties of the module 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.|
The following is the full list of the methods of the module 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.|
|SaveMetadata||Saves the SP configuration to a metadata file.|
|Start||Starts the SP server.|
|Stop||Stops the IdP server.|
The following is the full list of the events fired by the module 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.|
The following is a list of configuration settings for the module 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.|