- 06 Feb 2023
- 5 Minutes to read
Single Sign-On With SAML
- Updated on 06 Feb 2023
- 5 Minutes to read
|Installation Location||Administration > Features > SAML|
|Settings Location||Settings > SAML Settings|
Configuring Single Sign-On (SSO) involves details that vary based on provider and customer environment; these settings are strict and must be at the knowledge of the administrator configuring the connection.
If SSO is a new concept, it may take time and multiple attempts to accurately configure all the identifying data and settings, allowing for secure and reliable authentication. An administrator with experience in SSO or the organization's IT infrastructure can help streamline the process.
The Decisions Support team is available to help but may not be able to answer questions or solve problems that are unique to a customer organization.
The SSO Basics article can provide an overview of SSO and how to update the accounts once configured.
In addition to the module prerequisites, an X.509 Certificate in PEM format is needed. Below is an example of a PEM formatted certificate:
-----BEGIN CERTIFICATE----- MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3 DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ 98TwDIK/39WEB/V607As+KoYazQG8drorw== -----END CERTIFICATE-----
Version 8 Endpoints
Below is a list of endpoints used for version 8, along with an example of the endpoints.
AD Sync and SSO
This example will demonstrate how to configure Single Sign-On using the SAML module.
- Navigate to the System> Settings. Right-click SAML Settings and select Edit.
- In the Edit SAML Setting window, check the Enabled option. Then, under the Identity Providers section, select ADD.
When users close out of their browser or close out of Decisions, their session will end. This can be resolved by enabling Session Persistence in SAML Settings. To enable this feature, Enable Session Persistence will need to be checked. This will allow users to remain signed into Decisions until they log out.
- Configure the appropriate fields in the Add Identity Providers window. This information is based on the SSO provider information used for the organization. When complete, click OK.
Setting Name Description Display Name Name for Identity Provider Login URL The SSO login of the Identity Provider Logout URL The SSO logout URL of the Identity Provider Sign Logout Requests/Responses When set to true, logouts will be signed with a private certificate. Logout Signature Algorithm RSA-SHA1 and RSA-SHA256 are the available signature algorithms. Filename of PFX File Path to the private cert file on the server's filesystem. Password for PFX Password for the private cert IdP Issuer/Entity ID The ID of the identity provider. This value is only required to allow Identity Provider-initiated logins. SP Issuer/Entity ID Usually, the Base URL to the Decisions Portal. The Portal Base URL can be found by clicking the Profile icon in the Designer Studio, then selecting About from the menu. Name ID Policy Either email or transient ID based on Identity Provider X.509 Certificate The PEM formatted string of the X.509 cert RelayState Behaviour In SAML 2.0, RelayState is an optional parameter that designates a particular URL as the destination for users after successful Single Sign-On (SSO) authentication.
- Ignore relay state
The IDP will ignore the presence of a RelayState if it exists.
- Single-Encoded URL Redirect
Value of relay state is a url that has been encoded one time; so Decisions decodes it one time.
- Double-Encoded URL Redirect
Value of relay state is a url that has been encoded two times; so Decisions decodes it two times. 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 typically used to create the unknown user in the Decisions Portal so that they can log in. Users can choose to pick a Flow or create the Flow Behavior SAML User Not Found Flow. 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. The default Flow 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 after running the selected Flow. If the Flow creates the user, it should be true so that the user seamlessly gets logged in, or else they would have to try logging in a second time to get in.
- In the Edit SAML Settings window, click the dropdown list under Primary Identity Provider and select the created Identity Provider. Click SAVE to save SAML Settings.When using a SAML Login Flow from the option Run Flow on Each Login, Relay State is available as input in the Flow Designer on the Data Explorer panel. Auto Timeout should only be used with the built-in SignOn. In the HTML Portal, log out the user to return to their SSO Sign-in Page. To get Attributes passed in from the SAML Response, navigate to the Data Explorer panel, then SAML Response > Assertion > AttributeStatement.
- Navigate to System> Security > Accounts and right-click an account that should be able to use SAML SSO. Select Edit Account.
- In the Edit Entity window, locate the PERSONAL INFORMATION section and define the User Identifier value. This value should be used for the Identity Provider to send as the User Id. Click SAVE.
- Once at least one admin user can work with SSO, open the Settings.xml file at C:\Program Files\Decisions\Decisions Server.
- Find the line <EnableSingleSignOn>false</EnableSingleSignOn> and set the value to true. Save changes to the file. If the line is not present, add the line to the Settings.xml file.
- Restart the Decisions Server service to enable SAML SSO mode.
Using Email Address nameId Policy
When Identity Provider is using Email Address nameId Policy, use the following code:
$metadata['http://myDecisionsServer.Decisions.com/decisions'] = array( 'AssertionConsumerService' => 'AssertionConsumerService' => 'http://myDecisionsServer.Decisions.com/decisions/Primary/SAML/AssertionConsumer', 'SingleLogoutService' => 'http://myDecisionsServer.Decisions.com/decisions/Primary/Logout', 'NameIDFormat' => ***'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress'*** );
Using Transient namedId Policy
When Identity Provider is using Transient nameId Policy, use the following code:
$metadata['http://myDecisionsServer.Decisions.com/decisions'] = array( 'AssertionConsumerService' => 'http://myDecisionsServer.Decisions.com/decisions/Primary/SAML/AssertionConsumer', 'SingleLogoutService' => 'http://myDecisionsServer.Decisions.com/decisions/Primary/Logout', 'NameIDFormat' => ***'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'*** );