Configuring SSO With Active Directory's ADFS

Overview

Sugar and 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.

If you are using SugarLive in Sugar Serve, you can also set up SSO in SugarLive using SAML 2.0. To do so, you will also need to configure ADFS as an identity provider for Amazon Web Services (AWS). Refer to this blog post on Amazon's website for details on this setup.

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

Password Management documentation (for instances that do not use SugarIdentity)
SugarIdentity Guide (for instances that use SugarIdentity)
Understanding Security Layers for User Authentication 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.
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.

Open the ADFS Management console on the ADFS server.
In the left-tree menu, navigate to Service > Endpoints.
Scroll down to the Metadata section in the Endpoints list, then locate the Federation Metadata-type file to verify the metadata file's path on your ADFS server.
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.
Note: Replace {your_adfs_server} with your organization's ADFS server URL.

Once you have downloaded the ADFS metadata file, you can then configure SAML in Sugar or in SugarIdentity.

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 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 or SugarIdentity and ADFS which allows for communication between the two services:

Open the ADFS Management console then navigate to Trust Relationships > Relying Party Trusts from the left-tree menu.
Click "Add Relying Party Trust..." from the Actions pane on the right, then click "Start" to proceed to the next screen.
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 from SugarIdentity. Click "Next".
Enter a display name that will allow you to identify the newly configured trust relationship (e.g., "SugarCRM"). Click "Next".
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".
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".
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
- 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
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 in to 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, 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.