Configuring SSO With Active Directory’s ADFS in Sugar 7.9.x and Lower


    Sugar allows single-sign-on authentication using Active Directory Federation Services (ADFS) and SAML so that Sugar can be integrated with a connected system using a single user ID and password. This article walks through configuring ADFS and Sugar to allow external authentication using SAML 2.0. For more information about external authentication methods, please refer to the Password Management documentation.

    Note: This article pertains to Sugar versions 7.9.x. If you are running a higher version, please refer to the Configuring SSO With Active Directory’s ADFS in Sugar 7.10.x and Higher article.


    • The ADFS role should be installed and configured correctly. If you are unsure about this, please contact your network’s system administrator to assist you.
    • The following steps require administrator access to the ADFS server. If you do not have this access, you can provide this guide to your system administrator to perform the necessary steps.
    • All users must have an email address added to their Active Directory account.

    Steps to Complete

    Exporting the Token-Signing Certificate

    Use the following steps to export the token signing certificate. You will need it later when we complete the steps in the Configuring Sugar section:

    1. Open the ADFS Management console on the ADFS server.
    2. In the tree view on the left, navigate to Service > Certificates.
    3. Right-click the Token-signing certificate and chose “View Certificate”.
    4. Navigate to the Details tab and click the “Copy to File” button.
    5. In the wizard, select “Base-64 encoded X.509 (.CER)” as the format and follow the wizard to store the certificate in an accessible location.

    Configuring a New ADFS Trust Relationship

    Use the following steps to configure a new trust relationship between Sugar and ADFS. This allows for communication between the two services.

    1. In the ADFS Management console, navigate to Trust Relationships > Relying Party Trusts in the tree view.
    2. Right-click on “Relying Party Trusts” and chose “Add Relying Party Trust”.
    3. A wizard will appear. Click “Start” to continue to the next screen.
    4. On the Select Data Source screen, choose the last option, “Enter data about the relying party manually”, and click “Next”.
    5. Enter a display name that will allow you to identify the newly configured trust relationship (e.g “SugarCRM” or “SugarCRM – Production” if you are planning on adding multiple Sugar instances). Click “Next”.
    6. In the profile selection, leave “AD FS profile” selected. This profile has support for SAML 2.0 as required by Sugar. Click “Next”.
    7. Optionally, configure a token encryption certificate. For the purpose of this guide, we will skip this step and click “Next”.
    8. To configure the Sugar endpoint, select “Enable support for SAML 2.0 WebSSO protocol” and enter the following URL in the field:
      https://<sugar url>/index.php?module=Users&action=Authenticate&platform=base

      Note: It is important that your instance is protected by SSL and your web server listens on HTTPS. This is required by ADFS, and the wizard will not allow you to continue if this requirement is not met.
    9. Click “Next” to display the Configure Identifiers page. Sugar will use “php-saml” by default. However, you will need to configure a unique identifier if you are planning to add multiple Sugar instances with an individual trust relationship for each. For more information, please refer to the Sugar Config Parameters section of this page. Click “Add” to add the identifier to the list, then click “Next”.
    10. The wizard will ask to configure multi-factor authentication. If this is required by your organization, you can configure this now, however, doing so is outside of the scope of this article.
    11. Click “Next” again to display the Issuance Authorization Rules page. Here you can configure the default behavior of either allowing access to all users or no users. You can change this later, too. Leave the default selection to permit all users to log in.
    12. Click “Next” to display an overview of the configured settings. Then click “Next” followed by “Close”. This will create a new entry in the “Relying Party Trusts” list. Right-click the entry you just created and select “Edit Claim Rules”.
    13. On the “Issuance Transform Rules” tab, add two rules which allow ADFS to work with Sugar. The first rule will map the email address configured in AD with ADFS. The second rule will transform the claim to format the NameID in the email format as required by Sugar.
      • Create the first rule with type “Send LDAP Attributes as Claims” and “Email” as the name, “Active Directory” as the Attribute store, “E-Mail Addresses” as the LDAP Attribute, and “E-Mail Address” as the Outgoing Claim Type.
      • Create the second rule with “Transform an Incoming Claim” as the type and “Email Claim” as the name, “E-Mail Address” as the Incoming claim type, “Name ID” as the Outgoing claim type, “Email” as the Outgoing name ID format, and “Pass through all claim values” selected. 
    14. Close the Claim Rules window after creating both rules.

    This concludes the configuration process on the ADFS server.

    Configuring Sugar

    Prior to configuring Sugar, complete the following prerequisites:

    • Verify that the site_url value in ./config.php is correct and matches the configured Service URL in ADFS.
    • Ensure that the Token Signing certificate that you saved per the Exporting the Token-Signing Certificate section is in an accessible location.
    • Make note of the hostname of the ADFS server.

    Use the following steps to configure Sugar to work with ADFS:

    1. Log into Sugar as an administrator and navigate to Admin > Password Management to open the SAML configuration page.
    2. At the bottom of the page, check the “Enable SAML Authentication” checkbox. The view will instantly update with the required fields. Fill in the required settings:
      • Login URL : https://<ADFS Host>/adfs/ls
      • X509 Certificate : Open the previously saved Token Signing certificate with a text editor (e.g. Notepad, Wordpad, TextEdit, Vi) and copy the contents of this file into the X509 Certificate field including the “—–BEGIN CERTIFICATE—–” and “—–END CERTIFICATE—–” delimiters.
    3. Click “Save”.

    Sugar Config Parameters

    The following parameters will automatically be written in the ./config_override.php file. They can also be manually configured.

    //When configuring multiple Sugar instances, it might be necessary to configure a unique trust identifier.
    //The default value is "php-saml"
    $sugar_config['SAML_issuer'] = '<Unique value>'

    //The following parameter selects SAML to be the authentication class
    $sugar_config['authenticationClass'] = 'SAMLAuthenticate';
    //This parameter configured the location where the SAML request must be sent to
    $sugar_config['SAML_loginurl'] = 'https://<adfs server>/adfs/ls';

    //Configuration parameter for the Single Logout (SLO) page
    $sugar_config['SAML_SLO'] = '';

    //The X509 token signing certificate
    $sugar_config['SAML_X509Cert'] = '';
    in User Log In Management

    Reach out to us for help