Single Sign-On With SAML

Last Updated: 03/22/2016 Introduced in Verision: 3.2

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)
  • 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 > Modules Folder, locate Decisions.SAML module, right-click it and select Install Module action.

installSamlModule

Note: to install Module in Decisions 3.5 or newer, 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.

moduleInstalled

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

editSamlSettings

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

enableSamlIntegration

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

addNewProvider

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
  • 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
  • 509 Certificate: the PEM formatted string of the x.509 cert
  • Process Flow if Not User: 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
  • Flow Process Type: Use Run In Background
  • Pick Flow: this is the Flow that will be run when 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.

identityProviderSettings

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

selectIdp

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 accidently do this to yourself, you can disable SSO and then log in with local user.

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.

editAccount

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.

setUserIdentifier

Once you have enabled at least one admin user to work with SSO, edit the Decisions settings.xml file and make 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.

 

Meta Data

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