Title: Configuring SAML for Single Sign On
Unanet supports Single Sign On (SSO) in the Cloud environment through SAML integration with leading identity management providers such as AD FS, 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.
The information below is intended as an overview of SAML functionality as used in the Unanet environment.
Cloud and On Premise customers are responsible for creating relying party trusts and claims where applicable, however, the main goal for Cloud customers is to provide the metadata information which contains Identity Provider Issuer Id, Identity Provider Single Sign On URL, and the X.509 Certificate used for message signing.
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
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 an X.509 Certificate
An 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 SAML tool site can also prove helpful. After copying the contents of the X.509 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 X.509 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
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
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
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
- keystoreFile – The full path to
saml.jksfile we have just created.
- keystorePass – The password for the
saml.jkskeystore file, which in our case would be "changeit."
Configure unanet.authentication=jaas in the
You can also increase logging at this point in the
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
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.
Adding an entry for the Logout Redirect URL property (unanet.logout.redirect) will help prevent confusion for users logging out of their SAML configured system as it will redirect users to a place other than the Unanet login page.
Navigate to Admin > Properties > Unanet > General > Display Options and enter a URL in the box for Logout Redirect URL.