SAML Single Sign-on 


    Security Assertion Markup Language (SAML) Single Sign-on allows you to authenticate  your users with the help of an identity provider that the users already use to authenticate other application or services. You can create multiple SAML configurations and associate different accounts with these configuration.  


    Note: An account can be associated with only one SAML configuration.

     

    How does SAML work  

     

    SAML exchanges authentication and authorization data between two entities, namely an Identity Provider(IdP) and a Service Provider(SP). Here, ServiceDesk Plus MSP acts as the SP and upon integration, users can directly log in to the application from the IdP without providing any login credentials.

    For example, you can set up Active Directory Federation Service (ADFS) as the IdP to allow your users to log into ServiceDesk Plus MSP. The following screenshot shows  how a user logs in to an application configured with SAML.

     

    Configuring SAML Authentication for Accounts  

    Role Required: SDAdmin

    1. Go to Admin >> Account Details >> SAML Single Sign On.

    2. Click New SAML Configuration and provide a name for the configuration and click Create.

    3. To associate accounts with this SAML configuration, select the preferred accounts using the Associated Accounts combo box.

    4. Configure ServiceDesk Plus MSP as service provider with your IdP, using the details Entity ID, Assertion Consumer URL, Singel Logout Service URL, SP Certificate File, and SP Metadata File under the Service Provider Details section.
      Note: 

      • Changes in the alias URL from the Self Service Portal settings and changing the service from HTTP to HTTPS will be reflected in the Assertion Consumer URL and Single Logout Service URL. You will have to reconfigure SAML authentication in both SP and IdP portals by regenerating the SP certificate. 

      • First, you must configure ServiceDesk Plus MSP as a Service Provider with your Identity Provider. We have tested SAML 2.0 with ADFS 3.0Okta, and OneLogin as the Identity Providers. Click the respective IdPs for configuration information. After configuring ServiceDesk Plus MSP as a service provider in your IdP domain, return to the SAML configuration page in ServiceDesk Plus MSP.
    5. Under the Configure Identity Provider Details section, provide the following details as obtained from your IdP.

      • Login URL

      • Logout URL

      • Name ID Format: Choose an option using the drop-down list.

      • Algorithm: Choose an option using the drop-down list.

      • Certificate: Choose an appropriate certificate file.

    6. Finally, click Save.

     

    Note:

    • Select Mark as Default SAML configuration under the Account Association section to apply the SAML configuration to all accounts that are not associated with or any other configuration except excluded accounts.

    • Use the toggle Enable SAML Single Sign-On ? to enable/disable the current SAML configuration.  

    • Use the toggle Collapse the login form by default to hide/show login form for the associated accounts when SAML Single Sign-on is enabled.

    SAML_Configuration

     

    Managing SAML Configurations

    You can view, edit, delete, or disable SAML configurations or exclude accounts from the

    SAML Configuration list view page. You can access it under Admin >> Account Details >> SAML Single Sign On.

     

    • To view or edit SAML Configuration details, click the Name of the preferred configuration or the edit icon against it.

    • To delete a configuration, click the delete icon against the preferred configuration and confirm the delete operation.

    • To exclude certain accounts from a SAML configuration, click Excluded Accounts, select the preferred account and click Save. 

    Manage_SAML
    • To enable/disable SAML authentication across all configured accounts, use the SAML Single Sign On toggle button. To enable/disable specific SAML Configurations, click the Name of the configuration and use Enable SAML Single Sign-On ? toggle button. 

    Note:

    • An account can be associated with only one SAML configuration. An alert will be shown to confirm changes when excluded accounts or accounts associated with any other SAML configuration are selected.

    • To revert excluded accounts, click Excluded Accounts, deselect the desired accounts, and click Save.  

    Log into ServiceDesk Plus MSP using SAML

    The Log in with SAML Single Sign-on option will be show in the account-based login page for the accounts associated with a SAML configuration or if a default configuration is available.

    The common login page will display Log in with SAML Single Sign-on option only when a default SAML configuration is available. 

    Login SAML

    Users can either log in using the Local Authentication (enabled by default) or log in using SAML by clicking the link below the Log In button. If Local Authentication is disabled, the IdP login page will be displayed. 

    When the login name generated by the IdP does not match with the login name of a user in ServiceDesk Plus MSP, a new user will be created along with login credentials based subject to the following conditions.

    The domain name of the user will be matched with existing domains and the matched domain's account association is checked. If the domain is associated with a single account, then a user will be created under the particular account. If the domain is associated with multiple accounts or if there is no domain matching the user's domain name, then the SAML configuration is checked for its association with accounts. If the SAML configuration is associated with only single account, then the user will be  created for the particular account. In all other cases, new users will not be created.

    Note:
    For new users, the login name will be generated based on IdP and password will be generated based on Active Directory/LDAP settings.
    New user addition is supported only if dynamic user addition is enabled.

    During email-based login, users will not be added via dynamic user addition even if the option is enabled.

    Log out using SAML 

    ServiceDesk Plus MSP supports SAML single logout service. Using this, you can choose to log out from ServiceDesk Plus MSP only or from all the services integrated with the IdP.

    Click the profile icon and if you have configured SAML logout in your IdP domain, you will find two options listed:

    • Click Log out to log out of ServiceDesk Plus MSP alone.

    • If you click Log Out of SAML, to log out of all the services integrated with the IdP. 

     

    Troubleshooting

     

    Error Code

    Reason

    Solution

    4

    The IdP certificate file is not uploaded right.

    Reconfigure the IdP details.

    8

    SAML response is not received from IdP.

    ServiceDesk Plus supports only POST binding method. Ensure that the IdP follows POST binding method.

    10

    Error in validating the logout response of the IdP.

    Refer errors 42, 44, 50, 4, and 36. Contact support@servicedeskplusmsp.com.

    21, 22, 23

    The IdP response Status is Failure.

    Reconfigure the IdP details by following the instructions given here.

    35

    The IdP response is not signed. ServiceDesk Plus MSP accepts only signed responses.

    Configure the IdP settings for ServiceDesk Plus MSP to sign assertion and responses.

    36

    Unable to verify IdP signature in the SAML response.

    Upload the correct IdP certificate file in the SAML configuration page of ServiceDesk Plus MSP.

    40

    Entity IDs in the SAML response and ServiceDesk Plus MSP are not the same.

    Reconfigure the SP details in your IdP portal.

    42

    The destination URL in the SAML response does not match the actual URL from which the response is called.

    Reconfigure the SP details in your IdP portal.

     

    If you have configured a proxy server (say azure app proxy) to externalize the application, add proxyname="<external_url>" and proxyport="<external_port>" attributes to the connector tag in the server.xml file.

    44

    The Issuer field is empty in the SAML response.

    Contact support@servicedeskplusmsp.com.

    46, 47, 51

    The SAML response will not be validated as the System Time Stamp does not match the Standard Time.

    Set proper time and time zone in the application server.

    48

    The user has configured Assertion Encryption, which is not supported in ServiceDesk Plus MSP.

    Change Assertion Encryption to Assertion Sign in the IdP, which will sign the assertion but not encrypt it.

    49

    Issuer name is missing in the SAML assertion.

    Reconfigure the SP and IdP.

     

    If the error persists, email us at support@servicedeskplusmsp.com with the log files.

    50

    The SAML assertion from the IdP is not for the intended user/requester.

    Log in again by using SAML authentication.

    52 (In ServiceDesk Plus MSP)

    The SAML response is not mapped with the right user, and dynamic user addition is disabled in the Self-Service Portal settings.

     

    If the user does not exist in ServiceDesk Plus MSP, create a new user manually with the login name generated by the IdP.

    If the user already exists in the application, change the Name ID attribute in the IdP portal to match the login name in ServiceDesk Plus MSP.

     

    60

    User not found (during email based SAML login).

    If the user does not exist in ServiceDesk Plus MSP, create a new user manually and configure email address.

    If the user already exists in the application, configure their email address to match the login email ID in ServiceDesk Plus MSP.

    61

    Login is disabled for the user.

    Enable login for the user.

    62

    More than one user is configured with the login email ID.

    Ensure that the login email address is configured only with one user. This error is thrown if the login email ID is configured as a primary/secondary email address of another user.

     

    FAQs

    1. Despite having valid login credentials, why am I added as a new user in ServiceDesk Plus MSP when logging in using SAML?

    When you log in using SAML, the IdP provides a login name in the SAML response. This login name is generated based on the NameID attribute configured in the IdP. The application does not map this with your credentials because your login name in ServiceDesk Plus MSP is not the same as the login name in the SAML response. Now there are two possibilities:

    • If dynamic user addition is enabled, you will be added as a new user with the login name generated by the IdP and password as configured in the Active Directory/LDAP settings.

    • If dynamic user addition is disabled, an error message will be displayed and you will not be able to log in to ServiceDesk Plus MSP.

    To solve this, reconfigure your IdP settings by choosing the right NameID attribute.

     

    2. Why am I added as a separate user even after configuring my IdP to return the correct login name?

    If the user falls under a domain, the IdP should return the domain name of the user along with the login name.

    For example, if Peter is a technician with login name peter in the Zylker domain, then the IdP should return Zylker\peter as the login name.

    If the above case fails, a new user will be created.

     

    Choose the proper NameID attribute and reconfigure the IdP to solve this.

     

    3. How to fix alignment issues in the login page after enabling SAML as shown in the below image?

     

    1. Go to Admin >> Self-Service Portal Settings.  

    2. Click Customize now under Login Page customization.

      In the HTML editor, add the classes shown in the screenshot.These classes will also be available under <server_home>\custom\login\default.html

       

      .sign-line{  

        text-align: center;

        display: block;

        border-bottom: 1px solid #ccc;

        margin:10px 0;

      }

      .or-ctr{

        background: #fff;

        position: relative;

        top: 8px;

        padding: 0 4px;

        font-size: 12px;

        color: #727272;

      }

      .sign-saml{

        color: #009adb;

        text-decoration: none;

      }

    3.  Click Save and check to see if the link now appears aligned. 

     

    Copyright © 2017, ZOHO Corp. All Rights Reserved.