Single Sign-On With SAML
- Updated on 07 Oct 2019
- 5 minutes to read
First, gather 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
- Open SSL Download
- Command to run to convert crt to PEM
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, set up Decisions.
In Decisions Portal navigate to the System > Administration > Features Folder, locate Decisions.SAML module and select Install Module action.
After Service Host Manager is restarted, navigate to theSystem > Settings in the Portal, locate SAML Settings, right-click it and select Edit action.
In the resulting Edit SAML Settings window, under SAML Integration check Enabled check-box.
Then, in the Identity Providers select Add New.
Next, enter the Identity Provider Settings:
|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/Entity 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, select 'Ok' to save and continue.
Then, in the Edit SAML Settings window select the Identity Provider that was just created as the Primary Identity Provider. Select 'Ok' and Save to save SAML Settings.
Before we Enable SAML SSO, configure at least one Admin user to work with SAML SSO or else there will be no admin users who can log into the system after enabling. When SSO is enabled, no local users can log in. If this is accidentally done, disable SSO and then log in with local user.
Auto Timeout should be only used with the Native SignOn. In the HTML Portal, logout the user, hence they go back to their SSO Sign-in Page and it would work.
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 locate Personal Information section and define User Identifier value. The value that should be used, is the value expecting the Identity Provider to send as the User Id.
Once at least one admin user is enabled 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:
After editing and saving settings.xml, restart Service Host Manager. You are now in SAML SSO mode.
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'*** );
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'*** );
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.