SugarCRM SupportKnowledge BasePassword ManagementConfiguring SSO With Active Directory's ADFS

Configuring SSO With Active Directory's ADFS

Overview

Sugar allows single-sign-on authentication using ADFS and SAML which allows Sugar to be integrated into a connected system using a single user ID and password. This article walks through configuring ADFS and Sugar in order 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 6.x and 7.x.

Prerequisites

  • The ADFS role should be installed and configured correctly. If you are unsure about this, please contact your 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 AD account.

Steps to Complete

Exporting the Token-Signing Certificate

Use the following steps to export the token signing certificate to have it available later when we configure Sugar:

  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".
    adfs certificate-export
  4. Navigate to the Details tab and click "Copy to File" in the bottom right corner.
    export certificate
  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.
     base64 encoded export

Configuring a New ADFS Trust Relationship

Use the following steps to configure a new trust relationship between Sugar and ADFS which allows for communication between the two:

  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".
    manual metadata
  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 which 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&dataOnly=1&platform=base
    SAML WebSSO
    Note: It is important that your instance is protected by SSL and your webserver 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. Click "Add" to add the identifier to the list, then click "Next".
    pt identifier
  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. This can be changed afterward. 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".
    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.
      email transform rule
    • 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. 
      nameid tranform rule
  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 the Token Signing certificate saved in the Exporting the Token-Signing Certificate section is in an accessible location.
  • Make a 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 which brings opens the SAML configuration page.
  2. At the bottom of the page, check the Enable SAML Authentication checkbox. The view will update with the required fields. Fill in the required settings:
    • Login URLhttps://<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.
    sugar password management
  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 select 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 page
$sugar_config['SAML_SLO'] = '';

//The X509 token signing certificate
$sugar_config['SAML_X509Cert'] = '';

LarsB

Last modified: 10/06/2016 05:38pm

Back to top Contents