Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Title: How do we configure  Configuring SAML for our environment?Single Sign On

Brief description:

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:

Table of Contents
maxLevel3


Configuring SAML for Unanet

Below is information on requirements for SAML implementation.

...

  • Identity Provider Issuer Id
  • Identity Provider Single Sign - On URL
  • X.509 Certificate used for message signing

...

   com.unanet.security.SamlLoginModule sufficient
        serviceProvider="https://erp.unanet.net/erp
        acsUrl="https://erp.unanet.net/erp/action/login/validate
        idp="https://app.onelogin.com/saml/metadata/123456"
        idpSSOUrl="https://erp.onelogin.com/trust/saml2/http-post/sso/123456"
        keystoreFile="/home/erp/unanet/config/saml.jks"
        keystorePass="changeit"
        proxyUri="https://erp.unanet.net/erp
        allowIdpInitiatedSSO="true";
  com.unanet.security.UnanetLoginModule required;
};


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  EntityID attribute value from EntityDescriptor  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  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  Note that only the public key from Identity Provider’s signing certificate is expected in this file.

...

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.

...

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

-----BEGIN CERTIFICATE-----

...

-----END CERTIFICATE-----


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:

<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing"><KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"><X509Data><X509Certificate> <<- Abbreviated 
</X509Certificate></X509Data></KeyInfo></KeyDescriptor>

The next step is to create the keystore with the certificate. 
This  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.

...

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

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.

...