Configure the SAML Identity Provider

Integrate CSM with a SAML-compliant identity provider such as Microsoft Active Directory Federation Services (ADFS).

Each identity provider uses a different procedure for integrating with CSM. The procedures in this section provide some sample guidelines on how to configure CSM with each identity provider. Refer to the specific identity provider documentation for guidelines on installing and initially configuring the identity provider, and to ensure that the correct configuration steps are followed for the desired implementation.

A convenient way to create the configuration is to import the identity provider’s metadata. This configures all the required settings except for the selection of the type of ID. However, you can manually enter all the data and import the signing certificate, if needed.

To configure the SAML identity provider:

  1. In CSM Administrator, create a Blueprint.
  2. From the toolbar menu, select Tools > Edit SAML Settigs.
  3. Select the Identity Provider page.
  4. Select Import Metadata.
  5. When prompted for a file name, select the Service Provider's metadata .xml file. For example, use the metadata file from ADFS.

    The following information is automatically imported from the metadata file. If it is not, you can manually enter information into the writable fields.

    Option Description
    Entity URL A URL that uniquely identifies the identity provider. This is provided by the identity provider.
    Organization Name (Optional) The name of the identity provider, used only for display.
    Organization URL (Optional) The main URL of the identity provider, used only for display.
    Single-Sign-On URL The URL of the identity provider’s authentication service. This should always be a secure URL (beginning with https:).

    The identity provider signing certificate (a standard .cer file) is used to verify messages from the identity provider.

    Signing certificates are normally managed by network IT staff; IT should be knowledgeable about the procedure for obtaining new certificates. Certificates must be obtained from trusted certificate authorities (such as VeriSign, Thawte, GoDaddy, and more).

  6. If you have changed the SSO URL or are re-routing requests to a SSO URL outside the CSM environment, you must list proxy SSO URLs here. Select Add and provide the URL(s). They are added to the safe URLs list in the form-action attribute in the Content Security Policy header.
  7. From the Type of ID options, select the type of ID (SAML Name ID) to request from the identity provider:
    • Email Address: Select this option to use email addresses as the SAML Name ID. See Use E-mail Address as the Name ID.

      When using email address, ensure that the Email Attribute is set on the Email Address Field of the User/Customer Business Objects (User Info and Customer-Internal).

    • Windows Login: Select this option to use the Windows login ID as the SAML Name ID. This option must be selected if you want to automatically update user imports from SAML. See Use Windows Login as the Name ID.
  8. Select the Hide SAML authentication window check box to hide the SAML authentication window used by the CSM Desktop Client.

    This should be used only with ADFS and when users are normally logged into the same network, in which case users are never prompted to log in and so the browser window might be considered an unnecessary distraction.

  9. Select the appropriate signing options to configure SAML signing certificates according to your identity provider's parameters. When an authentication response is returned, it may consist of many SAML assertions. Identity providers may sign the entire response, sign individual assertions, or both. For example, ADFS signs individual assertions but not entire responses. Consult documentation from your identity provider to determine the appropriate settings. You must select at least one option.
  10. Optionally, select the Force check box to disable Force Authentication. Authentication is forced by default; this means users are required to enter their credentials each time they access CSM.

    Cherwell strongly recommends that you do not disable Force Authentication, as it decreases security. If you are considering disabling Force Authentication (due to network/physical server environments, or to make it easier for users to maintain a session), please contact Cherwell Support to ensure you understand the implications.

Optional web.config settings:

  • Adjust the server time allowance to allow for differences in clocks on the identity provider and local servers. This setting will default to 60 seconds but can be overridden by a setting in the web.config files for both Cherwell Service and the REST API. To override the default setting, specify a value in seconds in the web.config files as follows:

    <add key="SAMLServerTimeAllowance" value="90" />

  • If using SAML and a non-ADFS identity provider, you must add this setting to the web.config file in the Cherwell Service folder. Specify the setting under the <appSettings> section as follows:

    <add key="IdpIsAdfs" value="false"/>

    If you have upgraded and are using ADFS, you do not need to add the setting.