Title: Configuring SAML for Single Sign On
Unanet supports Single Sign On (SSO) in the Cloud through SAML integration with leading identity management providers such as Duo, OneLogin, Okta, etc. Multi-factor authentication and password complexity requirements can also be satisfied through these products. There are multiple third party ID providers that can provide authentication that Unanet can accept via SAML configuration.
For On Premise systems, the only traditional SSO method (supported by Unanet for years) that still works is the IIS Login Module.
What’s covered in this document:
Configuring SAML for Unanet
Below is information on requirements for SAML implementation.
Service restarts will need to occur, so some amount of outage time should be expected in this process.
- We support SAML V2.0
- If your Identity Provider (IdP) supports a default relay state it can be left blank. Unanet will correctly handle routing the user to their home dashboard by default.
- All assertions in authentication responses must be signed.
- Authentication responses can also be signed, but it is not required.
- Unanet only requires that responses contain a Subject with a Name Id in unspecified format, this format being: “urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified”.
- The Subject’s Name Id must match the Unanet Username in the person profile.
- Unanet does not support Single Logout (SLO).
Unanet specifics for SAML integration:
Single Sign On URL
Default Relay State
Can be left blank
SAML/AD username needs to match Unanet Username
An example of the Single Sign On URL can be: https://erp.unanet.net/erp/action/login/validate
Root Domain: .net
Site Context: erp
To complete the setup, the Unanet webserver will require the following information for your IdP configuration:
- Identity Provider Issuer Id
- Identity Provider Single Sign On URL
- X.509 Certificate used for message signing
You can either configure and submit this information specifically or provide a copy of your IdP metadata file.
With this information, On Premise customers can configure files and import the X.509 certificate as a trusted certificate in the Java keystore.
Once Cloud customers provide the metadata, Unanet Support can configure this information against the customer Cloud site.
One site that has proven helpful in creating/validating files as well as troubleshooting SAML integration issues is https://www.samltool.com/online_tools.php.
The SAML information needs to be entered in the jaas.config file located in the \\unanet\config directory.
Example configuration file for ‘erp’ customer site utilizing OneLogin.
Glossary of SAML terms
serviceProvider: The Service Provider’s Entity Id. This is how the Unanet instance identifies itself to the Identity Provider.
acsUrl: The Service Provider’s Assertion Consumer Service URL. This is the Unanet instance’s URL that accepts and processes authorization responses from the Identity Provider (IdP). This will always be the same action, regardless of Unanet instance, but the URL prefix, through context, will be specific for each Unanet instance.
Idp: The Identity Provider’s Entity Id. This is how the Identity Provider identifies itself to Unanet. EntityID attribute value from EntityDescriptor element.
idpSSOUrl: The Identity Provider’s Single Sign On URL. This is the URL of the Identity Provider that will respond to authentication requests from Unanet. Location attribute value from the SingleSignOnService HTTP-Redirect binding element within the IDPSSODescriptor element.
keystoreFile: The full path to a Java keystore file containing the Identity Provider’s signing certificate. This file must contain the Identity Provider’s signing certificate with an alias of “idp_signing”. Note that only the public key from Identity Provider’s signing certificate is expected in this file.
keystorePass: The password for the Java keystore file identified in keystoreFile. This is the password used to create the keystore file and is required to access the signing certificate contained within it.
allowIdpInitiatedSSO: If set to “true”, allows Identity Provider initiated Single Sign On. If your Identity Provider presents authenticated users with a menu of accessible applications, you will want to set this option to “true” to allow the menu link to Unanet to work directly.
Creating a Keystore from a X.509 Certificate
A X.509 signing certificate in a certificate file, typically a .cer file is required as well.
In the metadata file, you will find information about the SSL certificate. However, there may be more than one certificate in the file. The one Unanet requires is contained within a KeyDescriptor element with use=”signing”. There may be others with use=”encryption”, but those would not prove helpful. Additionally, we have yet to support IdP encrypted message exchange.
Therefore, the correct certificate information would be within “signing” as displayed in the abbreviated example below:
This is where the samltool site can also prove helpful. After copying the contents of the X509 Certificate element, you can paste it into https://www.samltool.com/format_x509cert.php and click the ‘Format X.509 certificate’ button. This will create formatted text contents for a CER file, including header, footer and line breaks. You can then copy and paste the generated contents into a file with a .cer extension and save.
Abbreviated Example of Certificate Format
Obtain x509 certificate for AD FS installation on Server 2016 (easier option if using AD FS)
Browse to: https://<ADFS FQDN>/FederationMetadata/2007-06/FederationMetadata.xml
The exact URL can be found by opening AD FS -> Service -> Endpoints in the MMC. Scroll down until you see “Metadata” and find the type: “Federation Metadata”. You will want the URL path listed here that ends in .xml.
Open the downloaded FederationMetadata.xml file and find the following portion:
<KeyDescriptor use="signing"><KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"><X509Data><X509Certificate> <<- Abbreviated
The next step is to create the keystore with the certificate. This can be done utilizing the Java keytool, although the openSSL tool is an option as well. Since keytool is installed with your required Java version, this may be the preferred option to utilize.
To use the Java keytool, if java/bin is not configured in your server’s path, navigate to your JAVA_HOME directory. In this example, the path is C:\Program Files\Java\jdk1.x.0_xxx\bin.
You can then run the import with this example of syntax. The alias of idp_signing is required as that is hard coded into the software.
keytool -importcert -trustcacerts -keystore saml.jks -storepass changeit -noprompt -alias idp_signing -file Unanet_x509_signing.cer
The result of this command will be a new keystore file named saml.jks(this file will be located in the bin directory where the syntax was run), using the keystore password of changeit, and containing the signing certificate with the required alias of idp_signing.
It is a best practice to keep these files in one place for ease of management. If you wanted to create/keep the saml.jks file in the \\unanet\config directory with all the other files custom to your site, the syntax would appear as such:
c:\Program Files (x86)\Java\jre1.8.0_191\bin>keytool -importcert -trustcacerts -keystore "d:\unanet\config\saml.jks" -storepass <password> -noprompt -alias idp_signing -file d:\cert\Unanet_x509_signing.cer
To complete the SAML Login Module configuration, we can now define the following in the jaas.config file:
- keystoreFile – As the full path to saml.jks file we have just created.
- keystorePass – The password for the saml.jks keystore file, which in our case would be "changeit".
Configure unanet.authentication=jaas in the unanet.properties file.
You can also increase logging at this point in the unanet.properties file:
unanet.log.level=FINER is the best option
unanet.security.saml.debug=true to troubleshoot any issues that may come along with implementing SAML
When using the FINER option, logging needs to be written to a configured file, such as: unanet.log.output=c:/tomcat/logs/unaruntime.log
Next, Tomcat Properties needs to point to the location of the Unanet jaas.config file. One option to access Tomcat properties is to double click the Tomcat8.exe file.
Navigate to the Java tab > Java Options and enter the path to the jaas.config file preceded by
Restart Tomcat service
After all configurations are in place, restart the Tomcat service and test access or view logging in \\tomcat\logs to see what issues may exist.