Single Sign-On With SAML

Last Updated: 09/04/2018 Introduced in Version: 3.2

Warning: Setting up Single Sign On involves very detailed settings and every provider and customer environment is different.  If SSO is new to you, it may take time and several attempts to get all of the identifying data and settings correct to allow for secure and reliable authentication.  We recommend making sure you have someone from your organization with experience in SSO and your IT infrastructure available to streamline the process.  Our support team is available to help, but may not be not be able to answer questions or solve problems that are unique to your company.

Note: Accounts created before the following module is installed will need to be updated before using single sign on. Please contact support on how to update the account. 

 

This tutorial demonstrates how to setup Decisions single sign-on with SAML.

Example:

First, we are going to need the following information from the Identity Provider (external application) to set up Decisions:

  • Logout URL
  • Login URL
  • NameId Policy (Email or TransientID)
  • User ID Attribute Name (only needed if NameId policy is Transient)
  • X.509 Certificate as a PEM (not fingerprint). This can be provided as a .crt certificate file, but if provided as a crt we need to convert to PEM formatted string. This conversion can be done using OpenSSL

using C:\OpenSSL-Win32\bin>openssl.exe x509 -in “c:\certs\server2.crt” –out ducert.pem -outform PEM
Running this command will output a .pem file which can be opened in a text editor. You’ll need the contents of this text file for the Decisions SAML settings.

Next, we are going to set up Decisions.

In Decisions Portal navigate to the System > Administration > Features Folder, locate Decisions.SAML module  and select Install Module action.

 

Note: to install Module in Decisions please read the following document.

Then, System notifies that SAML Module was installed and Service Host Manager has to be restarted. We restart Service Host Manager.

After SHM is restarted, we navigate to the System > Settings in the Portal, locate SAML Settings, right-click it and select Edit action.

 

 

In the resulting Edit SAML Settings window, under SAML Integration we check Enabled check-box.

 

Then, in the Identity Providers we click Add New link.

 

 

Next, we enter the Identity Provider Settings:

  • Display Name: Enter whatever you want to describe this IdP
  • Login URL: The SSO login of the IdP
  • Logout URL: The SSO logout URL of the IdP
  • Sign Logout Requests/Responses: When set to true, logouts will be signed with your private certificate.
  • Filename of PFX File: Path to the private cert file on the server’s filesystem.
  • Password for PFX: If the private cert has a password, specify it here.
  • IdP Issuer/Entity ID: The ID of the identity provider. This value is only required if you wish to allow IdP-initiated logins.
  • SP Issuer/Enity ID: Usually the Base URL to the Decisions Portal (Note: can be found in the Settings.xml file)
  • Name ID Policy: Either email or transient ID based on IdP
  • X.509 Certificate: The PEM formatted string of the X.509 cert. (Often starts with ‘—–BEGIN CERTIFICATE—–‘)
  • Process If User Not Found: When enabled, the selected Flow will be run if a user with an unknown ID tries to log in. This Flow is normally used to create the unknown user in the Decisions Portal so that they can log in.
  • Processing Type: Set to Run Flow In Background.
  • Pick Flow: This is the Flow that will be run when an unknown user tries logging in. We have a default Flow that can be used for creating unknown users. It is named SAMLDefaultCreateAccount.
  • Retry Login After: When set to true, the system will try to log in the user after running the selected Flow. If the Flow creates the user, normally you’d want this set to true so that the user seamlessly gets logged in, or else they would have to try logging in a second time to get in.

When finished, we can click Ok to save and continue.

 

Then, in the Edit SAML Settings window select the Identity Provider that we have just created as your Primary Identity Provider. Click OK and Save to save SAML Settings.

 

Before we Enable SAML SSO, we need to configure at least one Admin user to work with SAML SSO or else we will be left with no admin users who can log into the system after enabling. When SSO is enabled, no local users can log in. If you accidentally do this to yourself, you can disable SSO and then log in with local user.

Auto Timeout should be only used with the Native SignOn. In the HTML Portal, we logout the user, hence they go back to their SSO Sign-in Page and it would work. But in case of Silverlight, we are locking the screen until the user credentials are entered. Since only the identity provider can verify these credentials, the screen can’t be unlocked in this situation.

We navigate to the System > Security > Accounts Folder in the Portal, select an account that should be able to use SAML SSO and use Edit Account action.

 

 

In the Edit Account resulting window we locate Personal Information section and define User Identifier value. The value you want to use, is the value you expect the Identity Provider to send as the User Id.

 

 

Once you have enabled at least one admin user to work with SSO, edit the Decisions settings.xml file located at C:\Program Files\Decisions\Decisions Services Manager\Settings

Be sure the following line exists (add it if it doesn’t) and is set to true:
<EnableSingleSignOn>true</EnableSingleSignOn>

enableSingleSignOnTrue

After editing and saving settings.xml, we need to restart Service Host Manager. We are now in SAML SSO mode.


Metadata

Note: You’ll want to replace the “http://myDecisionsServer.Decisions.com/decisions” with the URL to your Decisions installation.

Example, when Identity Provider is using Email Address nameId Policy

$metadata[‘http://myDecisionsServer.Decisions.com/decisions’] = array(

 ‘AssertionConsumerService’ => ‘http://myDecisionsServer.Decisions.com/decisions/SAML/AssertionConsumer.ashx’,

 ‘SingleLogoutService’ => ‘http://myDecisionsServer.Decisions.com/decisions/logout.aspx’,

 ‘NameIDFormat’ => ‘urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress’

);

Example, when Identity Provider is using Transient nameId Policy

$metadata[‘http://myDecisionsServer.Decisions.com/decisions’] = array(

 ‘AssertionConsumerService’ => ‘http://myDecisionsServer.Decisions.com/decisions/SAML/AssertionConsumer.ashx’,

 ‘SingleLogoutService’ => ‘http://myDecisionsServer.Decisions.com/decisions/logout.aspx’,

 ‘NameIDFormat’ => ‘urn:oasis:names:tc:SAML:2.0:nameid-format:transient’

);


General Information

When debug logging is enabled SAML requests and responses are logged at C:\Program Files\Decisions\Decisions Services Manager\Logs\SAML

The “AuthResponse…xml” log files will contain the certificate value that the Identity Provider server is sending back to us. This certificate needs to match the value used to configure Decisions settings.

Additional Resources