Single Sign-On With SAML
  • 01 Dec 2023
  • 7 Minutes to read
  • Dark
    Light

Single Sign-On With SAML

  • Dark
    Light

Article Summary

Module Details

Last Modified8.17
Installation LocationAdministration > Features > SAML
Restart Required?No
Step Location N/A
Settings Location Settings > SAML Settings
Prerequisites
  • SAML Module Installed.
  • Logout URL
  • Login URL
  • NameId Policy (Email or TransientID)
  • User ID Attribute Name
    (only needed if NameId Policy is Transient)

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 configure all the identifying data and settings accurately, 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. 

Accounts created before the required module is installed will need an update before using SSO. Please contact the Support team on how to update an account.

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.

SAML Assertion Consumer Endpoints
For some SAML ACS endpoints, identity providers may require Primary to be included as part of the endpoint ie, [baseportalurl]:[port]/Primary/SAML/AssertionConsumer
EndpointExample endpoint
LoginURL[baseportalurl]:[port]/Login
LogoutURL[baseportalurl]:[port]/Logout
SAML[baseportalurl]:[port]/SAML/AssertionConsumer
or
[baseportalurl]:[port]/Primary/SAML/AssertionConsumer
TokenHandler[baseportalurl]:[port]/HandleTokenResponse

AD Sync and SSO

Users cannot simultaneously set up an Active Directory Sync with Single Sign-On (via SAML and OpenID Modules). Doing so will result in an error that requires users to reset their sign-on setup.

Example

This example will demonstrate how to configure Single Sign-On using the SAML module.

  1. Navigate to the System> Settings. Right-click SAML Settings and select Edit.
  2. In the Edit SAML Setting window, check the Enabled option. Then, under the Identity Providers sectionselect 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.
  3. 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 NameDescription
    Display NameProvide a Name for the Identity Provider
    Metadata Document PreferenceSpecifies the preferred method for obtaining metadata

    No Metadata DocumentConfigure SAML without providing any metadata

    Fetch Metadata From URLEnables the retrieval of metadata from a specified URL.


    Metadata URLField to provide the metadata URL


    Refresh Metadata if All Certificates Fail Determines whether the metadata should be refreshed if all the certificates associated with the Identity Provider (IDP) fail to validate during the authentication process.

    Read Metadata From FileEnables retrieval of metadata by reading it from a specified file.

    Read Metadata From Text Enables retrieval of metadata from provided text
    Use Expired Metadata if Refresh FailsAllows to utilize expired metadata if the refresh process fails to retrieve the latest version.
    Override Assertion Consumer URL in Auth RequestsAllows the to replace the default Assertion Consumer URL with a specified URL when sending authentication requests

    Assertion Consumer URLField to enter the "Override Assertion Consumer URL".
    Login URLThe SSO login of the Identity Provider
    Logout URLThe SSO logout URL of the Identity Provider
    Sign Logout Requests/ResponsesWhen set to true, logouts will be signed with a private certificate.


    Logout Signature AlgorithmRSA-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 PFXPassword for the private cert 
    IdP Issuer/Entity IDThe ID of the identity provider. This value is only required to allow Identity Provider-initiated logins.
    SP Issuer/Entity IDUsually, 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 PolicyEither email or transient ID based on Identity Provider
    Ignore Date ConditionsAllows for bypassing the enforcement of validity dates in SAML responses received from the identity provider.
    Authorization Context Comparison AttributeThe "Authorization Context Comparison Attribute" setting provides options for comparing attributes in the authorization context.

    ExactIf set to "exact" or omitted, then the resulting authentication context in the authentication statement MUST be the exact match of at least one of the authentication contexts specified.

    MinimumIf set to "minimum", then the resulting authentication context in the authentication statement MUST be at least as strong (as deemed by the responder) as one of the authentication contexts specified.

    MaximumIf set to "maximum", then the resulting authentication context in the authentication statement MUST be as strong as possible (as deemed by the responder) without exceeding the strength of at least one of the authentication contexts specified.

    BetterIf set to "better", then the resulting authentication context in the authentication statement MUST be stronger (as deemed by the responder) than any one of the authentication contexts specified.
    Specify Authentication MethodsAllows the selection of the authentication context classes that can be used during the authentication process.
    X.509 CertificateThe PEM formatted string of the X.509 cert
    RelayState BehaviourIn 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
    The value of the relay state is a URL that has been encoded one time, so Decisions decodes it one time.


    Double-Encoded URL Redirec
    The value of the relay state is a URL that has been encoded two times, so Decisions decodes it two times.
    Allow JWT Redirect LoginEnabling this will expose a new field, "Remote JWT Endpoint URL".
    This will allow Decisions to send a correlation value to a third-party app. (In order to use this feature, the 3rd party app must have an endpoint to receive the JWT response). The 3rd party app should generate a random correlation ID (so that it can match the request to the response) and redirect the user to our login endpoint with a 'CorrelationId' parameter.
    Run Flow on Each LoginWhen 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.
    Process If User Not FoundThis section gives a handling mechanism if the user is not found in the Decisions.

    Redirect to URL
    Allows the platform to redirect the user to a designated URL, such as an error Page or a custom-defined location, to handle the situation where the user is not found


    URLField to specify the redirect URL


    Add UserID ParameterIf enabled, then an extra query parameter will be added to the end of the chosen URL. The name of the query parameter will be whatever you've entered for the UserId parameter name, and the value will be the user ID from the SAML response.

    Run Flow in Background
    Allows to run a Flow when an unknown user tries to log in.


    Edit 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.

    None
    No handling mechanism is required.

  4. 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.
  5. Navigate to System> Security > Accounts and right-click an account that should be able to use SAML SSO. Select Edit Account.
  6. 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 IdClick SAVE.
  7. Once at least one admin user can work with SSO, open the Settings.xml file at C:\Program Files\Decisions\Decisions Server.

  8. 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.
    <EnableSingleSignOn>true</EnableSingleSignOn>

  9. Restart the Decisions Server service to enable SAML SSO mode. 

Metadata

Replace the "http://myDecisionsServer.Decisions.com/decisions" with the URL to the Decisions installation.

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'***	  
);

Feature Changes

DescriptionVersionDeveloper Task
Allow 3rd party app to receive JWT after SAML login
8.17[DT-039287]


For further information on Modules, visit the Decisions Forum.



Was this article helpful?