SugarCRM SupportKnowledge BaseUser Log In ManagementConfiguring SSO With Active Directory's ADFS in Sugar 8.0 and Higher

Configuring SSO With Active Directory's ADFS in Sugar 8.0 and Higher

Overview

Sugar/SugarIdentity allows single-sign-on authentication using Active Directory Federation Services (ADFS) and SAML so that it can be integrated with a connected system using a single user ID and password. This article walks through configuring ADFS to allow external authentication using SAML 2.0.

For more information about external authentication methods, refer to the following pages:

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

Prerequisites

  • 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 steps in this article require administrator access to the ADFS server. If you do not have administrator access to the server, you can provide this guide to your system administrator to perform the necessary steps.
  • You must be a Sugar administrator to configure the SAML settings for your instance. For instances that do not use SugarIdentity, SAML is configured in Sugar. For instances that use SugarIdentity, SAML is configured in SugarIdentity via the Cloud Settings console.
  • All Sugar or SugarIdentity users must have an email address added to their Active Directory account.

Steps to Complete

The following sections explain how to download the ADFS Metadata file and configure a new ADFS trust relationship between Sugar/SugarIdentity and ADFS.

Downloading the ADFS Metadata File

Use the following steps to find and download the ADFS metadata file:

Note: If you already know the path to the metadata file on your ADFS server, please skip to Step 4.

  1. Open the ADFS Management console on the ADFS server.
  2. In the tree view on the left, navigate to Service > Endpoints.
  3. Scroll down to the Metadata section then locate the Federation Metadata-type file to verify the metadata file's path on your ADFS server.
  4. Download the ADFS metadata file by navigating your browser to the metadata file's path on your ADFS server. For the example shown in the image below, we would navigate to: https://{your_adfs_server}/FederationMetadata/2007-06/FederationMetadata.xml. The ADFS metadata file will be imported when configuring the SAML Authentication in Sugar or in SugarIdentity via the Cloud Settings console.
    Note: Replace {your_adfs_server} with your organization's ADFS server URL.
    ADFS MetadataFile  

Once you have downloaded the ADFS metadata file, you can then configure SAML in Sugar or in SugarIdentity via the Cloud Settings console. For instances that do not use SugarIdentity, refer to the Password Management documentation for more information. For instances that use SugarIdentity, refer to the SugarIdentity Guide for more information. Once you have configured SAML in Sugar or in SugarIdentity via the Cloud Settings console as well as exported the metadata file containing the SAML settings, you will need to configure a new ADFS trust relationship using the steps in the section below.

Configuring a New ADFS Trust Relationship

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

  1. Open the ADFS Management console then navigate to Trust Relationships > Relying Party Trusts from the tree view on the left.
  2. Click "Add Relying Party Trust..." from the Actions pane on the right then click "Start" to continue to the next screen.
    ADFS AddRelyingPartyTrust
  3. On the Select Data Source screen, choose the "Import data about the relying party from a file" option to import the metadata file you exported from Sugar or SugarIdentity via the Cloud Settings console. Click "Next".
    ADFS SelectDataSource ImportMetadataFile
  4. Enter a display name that will allow you to identify the newly configured trust relationship (e.g "SugarCRM"). Click "Next".
  5. On the Choose Issuance Authorization Rules screen, you can configure the default behavior of either allowing access to all users or no users. Please note that you can change this setting later, too. Leave the default selection to permit all users to log in. Click "Next".
  6. On the Finish screen, leave the "Open the Edit Claim Rules dialog for this relying party trust when the wizard closes" checkbox enabled and click "Close".
    ADFS AddRelyingPartyTrust Finish 
  7. On the "Issuance Transform Rules" tab, add two rules which allow ADFS to work with Sugar or SugarIdentity. The first rule will map the email address configured in Active Directory with ADFS. The second rule will transform the claim to format the Name ID in the email format as required by Sugar and SugarIdentity.
    • Create the first rule with type "Send LDAP Attributes as Claims" and the following settings:
      • Claim rule name : Email
      • Attribute store : Active Directory
      • LDAP Attribute : E-Mail Addresses
      • Outgoing Claim Type : E-Mail Addresses
        email transform rule
    • Create the second rule with type "Transform an Incoming Claim" and the following settings:
      • Claim rule name : Email Claim
      • Incoming Claim Type : E-Mail Address
      • Outgoing Claim Type : Name ID
      • Outgoing name ID format : Email
      • Pass through all claim values : selected
        nameid tranform rule
  8. Close the Claim Rules window after creating both rules.

The configuration process on the ADFS server is now complete.

Mapping Attributes for ADFS

For instances that use SugarIdentity, if you wish to have the attributes (e.g. email, title) from ADFS map to the SugarIdentity user fields (e.g. email, title), you will need to set up the attribute mapping in ADFS. Once the attribute mapping is configured, going forward, when a new ADFS user is created or the user's attributes are modified in ADFS, these changes will sync to SugarIdentity when the user logs into Sugar. For more information on setting up the attribute mapping, please refer to the Configuring SAML Attribute Mapping for SugarIdentity article.

Application

Once you have completed the configuration process on the ADFS server along with the SAML configuration in Sugar or in SugarIdentity via the Cloud Settings console, going forward, when a user navigates to Sugar they will be redirected to the ADFS login page to enter their ADFS credentials. Once the user's login credentials are authenticated in ADFS, they will be directed back to their Sugar instance and be automatically logged in.

Last modified: 2019-11-07 20:38:24