SugarCRM SupportDocumentationSugarCloud ServicesSugarIdentitySugarIdentity Guide

SugarIdentity Guide

Overview

SugarIdentity allows customers to securely manage user identities as well as access to applications and services in the SugarCRM ecosystem. SugarIdenity provides a federated identity solution based on industry standards and supports comprehensive single sign-on for the Sugar application, Sugar Plug-in for Outlook, and Sugar Mobile. The SugarIdentity service is managed via the Cloud Settings console. When a Sugar instance uses SugarIdentity, the administrator will access SugarIdentitiy in the Cloud Settings console to create and manage user recordsmanage password requirements, as well as set up LDAP or SAML authentication. 

Supported Regions

The SugarIdentity service is supported in the following regions:

  • APAC
  • EU
  • North America

Determining if Your Instance Uses SugarIdentity

To check if your Sugar instance uses SugarIdentity, navigate to your user profile in Sugar and click "Edit". If your instance is SugarIdentity-enabled, a pop-up message will appear stating that you (i.e. Sugar admin) need to access Cloud Settings to make changes to read-only fields (e.g. First Name, Last Name, Title). For regular users, the message will indicate to contact the Sugar administrator to make changes to read-only fields.

Prerequisites

The following prerequisites must be met in order to access and perform actions in the Cloud Settings console:

Accessing the Cloud Settings Console

You can access the Cloud Settings console from a Sugar instance that is SugarIdentity-enabled by navigating to:

  • Admin > User Management and selecting the Create New User option in the Users module tab's actions menu
  • Admin > Password Management

You will automatically be authenticated in Cloud Settings because you have an active Sugar session. Alternatively, you can navigate directly to the Cloud Settings console via the URL where you will need to enter your tenant ID (supplied by Sugar) and credentials to log in.

Tenant Settings

The tenant settings can be accessed via the gear icon at the top of every Cloud Settings page. Click on the gear icon to view your tenant ID and configure the Cloud Settings name and icon. Replacing the Sugar cube logo at the top of the screen with your own image, such as your company's logo, can help to further differentiate between the Sugar application and the Cloud Settings application.
CS GearIcon TenantSettings

To configure a new Cloud Settings icon, navigate to the Tenant Settings page via the gear icon, upload an image file to the "Select Custom Logo" field, and click "Save". For best results, upload a .png image that is sized 25 x 25 pixels and has a transparent background. Images larger than 160 x 160 pixels cannot be used.

User Management

The Users tab in the Cloud Settings console allows you to create and edit user records for your Sugar instance.

SugarIdentity User Fields

The SugarIdentity user record in the Cloud Settings console contains the contact information for the user and other employment-related settings. The User fields are as follows:

Field Description
Address City The user's employment city
Address Country The user's employment country
Address Postal Code The user's employment address's postal code
Address State The user's employment state or region
Address Street The user's employment street address
Create Date The date the user record was created
Created By The Sugar user or SSO provider that created the user record
Department The user's employment department
Email The user's primary email address
Note: If you use LDAP, the email address should match the mail attribute defined in the LDAP server.
First Name The user's first name
Last Name The user's last name
Modified By The Sugar user or SSO provider that last modified the user record
Modified Date The date the user record was last modified
Send Email to User A checkbox that controls whether the new user will receive a welcome email to create a password for Sugar login
Note: Do not enable this checkbox:
  • If you wish to assign teams and roles to the user first before they can access their Sugar account. For more information, refer to the section below. 
  • If you are only creating a new user for LDAP or SAML authentication. 
Status The active or inactive state of the user record
Sugar Resource Name The unique alphanumeric ID associated with the user's record which can be used to troubleshoot any log in issues
Title The user's employment title
User Type The user's type (i.e. a Regular user or a System Administrator)
User Name (Local Authentication) The unique name (e.g. jsmith) that the user will enter to log in to Sugar and that the other users will see when they view fields on records such as "Assigned to" and "Created By"
Note: Usernames cannot contain space characters.
User Name (LDAP Authentication) The username (e.g. john@example.com) associated with the user authenticating the LDAP directory
User Name (SAML Authentication) The Name ID claim (e.g. john@example.com) for the user that is defined in the identity provider (e.g. Okta)
Work Phone The user's phone number

Creating Users

There are different methods for creating users in SugarIdentity including via the Create New User option as well as importing a list of users using a .csv file. You can configure the user's basic and employment-related information in SugarIdentity. If you wish to configure additional user settings as well as assign teams and roles to the user, you will need to navigate back to your Sugar instance to make the appropriate changes. When using LDAP or SAML, you have the option to allow new users that are added to your directory service or identity provider automatically created as new users in Sugar when they log into Sugar for the first time. For LDAP and SAML, please note that the user must already exist in the LDAP server or identity provider before they can be provisioned in SugarIdentity.

Best Practices When Creating Users

When creating users in SugarIdentity, if the "Send email to user" or "Send email to imported users" option is enabled, the new user will receive a welcome email which allows them to create their Sugar password and access their account. Since the user could potentially log into Sugar before the admin has assigned teams and roles to the user, it is recommended that this option not be enabled. As a best practice, create the new user(s) with the Send email option disabled then assign teams and roles to the user from your Sugar instance. Once the user's account has been configured properly, have the user click the "Forgot Password?" link on the Sugar login screen to reset their password and access Sugar.

When using LDAP or SAML, if the "Auto Create Users" option is enabled, a new user record will be automatically created when the LDAP/SAML user logs into Sugar for the first time. Since the user can log into Sugar without having any teams and roles assigned to them first, it is recommended that this option not be enabled. As a best practice, create the new user(s) in SugarIdentity with the "Send email to user" option disabled then assign teams and roles to the user from your Sugar instance. Once the user's account has been configured properly, the user can then access Sugar.

Basic User Creation

The most common method of user creation is via the Create New User option which can be accessed via the Users module tab in Sugar or the Users tab in the Cloud Settings console. Please note that clicking the Create New User option from Sugar will navigate you directly to the Create User page in the Cloud Settings console where you can enter the necessary information to create the new user.

The following steps cover creating a new user via the Create New User option:

  1. Log in to Sugar and navigate to Admin > User Management.
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
    Sugar Users CreateNewUser1
  3. Enter appropriate values for the fields in the edit view layout. All required fields are marked with a red asterisk and must be completed prior to saving. If the "Send email to user" option is enabled, a welcome email will be sent to the user's primary email address asking them to create a Sugar password that conforms with your configured password requirements. Do not enable this option if you wish to assign teams and roles to the user first before they can access their Sugar account. For more information, refer to the section above. 
    Note: If you use LDAP or SAML, you will need to click the "Add LDAP authentication" or "Add SAML authentication" link then enter the user name (e.g. john@example.com) defined in your LDAP server/identity provider. The Email field should contain the mail attribute defined in the LDAP server or identity provider. Do not enable the "Send email to user" checkbox if you are only creating a new user for LDAP or SAML authentication without local authentication.
    CS CreateUser 1
  4. Click "Save".

Creating via Import

The import function allows you to import and create multiple user records in SugarIdentity by using a .csv file instead of creating them one-by-one.   

The following steps cover importing a list of users via the Create Multiple Users option:

  1. Log in to Sugar and navigate to Admin > User Management.
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
  3. Next, click the Users tab in SugarIdentity and select "Create Multiple Users".
    CS Users CreateMultipleUsers
  4. In Step 1, download the import file template then enter your data into the appropriate columns. Please note that the First Name, Last Name, Email, and User Name fields are required for import. If you use LDAP or SAML, then be sure to include the user's LDAP or SAML username (e.g. john@example.com) in the import file. If you already have a .csv file containing the data to import, make sure to manipulate the file to meet the format of the import template to ensure that the import goes through properly. Once your import file is ready to upload, click the Select File button on the page, select the import file then click "Next".
    Note: If the "Send email to imported users" option is enabled, a welcome email will be sent to the user's primary email address asking them to create a Sugar password that conforms with your configured password requirements. Do not enable this option if you wish to assign teams and roles to the users first before they can access their Sugar account. For more information, refer to the section above. 
    CS Importwizard Step1
  5. In Step 2, confirm the import file properties then click "Import".

If there are any errors detected during the import, the Import results page will display the records that failed to import.

Auto-Creating Users for LDAP and SAML

If you use LDAP or SAML, you can have users that are added to your directory service or identity provider automatically created as new users in Sugar by enabling the "Auto Create Users" option in SugarIdentity. Do not enable this option if you wish to assign teams and roles to the user first before they can access their Sugar account. For more information, refer to the section above. 

Note: The user will count against the number of licensed user accounts for your instance. SugarCloud customers can monitor the number of active users counting against their license via the SugarCloud Insights page.

  • To enable auto-create for an instance that is configured with LDAP, navigate to Authentication > Setup LDAP Support. Enable the "Auto Create Users" option, which is located in the lower portion of the form, and then click "Save".
  • To enable auto-create for an instance that is configured with SAML, navigate to Authentication > Setup SAML Support. Enable the "Auto Create Users" option, which is located about halfway down the form, and then click "Save".

Once the "Auto Create Users" option is enabled, a new user record will be automatically created when the LDAP/SAML user logs into Sugar for the first time. Please note that the mapped LDAP attributes will sync to SugarIdentity by default including the user's LDAP username. In order to have SAML attributes map to the SugarIdentity user fields, you will need to set up the attribute mapping in the identity provider (e.g. Okta). For more information on setting up the attribute mapping, refer to the Configuring SAML Attribute Mapping for SugarIdentity article.

Editing Users

SugarIdentity user records may be edited at any time to modify or add information via the Cloud Settings console. If you wish to edit other stock and/or custom user fields which do not appear in SugarIdentity, you will need to navigate back to Sugar to make the appropriate changes. For customers using LDAP or SAML, you can make changes to the mapped attributes directly in the LDAP server or identity provider if you wish to maintain consistent data since the changes will sync to Cloud Settings when the user next logs into Sugar. Making changes to the user fields in SugarIdentity will not sync back to the LDAP server/identity provider.

Please note that LDAP attributes map to the SugarIdentity user fields by default. For SAML, only the Name ID claim is mapped by default to SugarIdentity but you can set up the attribute mapping in the identity provider to have other SAML attributes mapped to SugarIdentity user fields.

Use the following steps to edit an existing user record from Sugar:

  1. Log in to Sugar and navigate to Admin > User Management.
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
    Sugar Users CreateNewUser1
  3. Next, click the Users tab, select "List Users", then click the name of the user you wish to edit in the Users list view.
    CS Users ListUsers
  4. In the user record's edit view, enter appropriate values for the user fields.
  5. Click "Save".

The changes to the user's record will be synced to Sugar and the updates can be viewed in Admin > User Management. To edit a user's record without logging into Sugar first, simply log in to Cloud Settings, select the user record from the Users list view, edit it, then save.

Deactivating Users

When a user is no longer a member of your organization, it is best practice to deactivate them instead of deleting them. This ensures that the user will no longer be able to log in to Sugar, but that their historical data remains intact in Sugar still. In addition to the Sugar application, the user will no longer be able to access the Sugar Plug-in for Outlook and the Sugar Mobile app once they are deactivated. Please note that deactivating user records will not update any related records and will only prevent the user from being assigned to records and such.  

Note: Users that have been deactivated do not count against the number of licensed user accounts for your instance.

If you use LDAP or SAML, then you will need to deactivate the user from the LDAP server or identity provider first before following the steps below as the status change does not sync back from SugarIdentity to the Identity Provider. 

Use the following steps to deactivate a user from Sugar:

  1. Log in to Sugar and navigate to Admin > User Management.
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
    Sugar Users CreateNewUser1
  3. Click the Users tab, select "List Users", then click the name of the user you wish to deactivate in the Users list view.
    CS Users ListUsers
  4. In the user record's edit view, change the Status field to "Inactive" then click "Save".

The user is now deactivated and can no longer log in to the SugarCRM applications and services. If you wish to reassign the user's records, simply log in to Sugar then navigate to Admin > User Management and select "Reassign Records" in the Users module tab's actions menu. For more information on reassigning an inactive user's records, refer to the User Management documentation.

Deleting Users

If a user record is invalid or should no longer appear in your organization's Sugar instance, it may be deleted from SugarIdentity via the Cloud Settings console. Please note that deleting user records will not delete any related records and will only prevent the user from logging into Sugar and being assigned to records. Also, please keep in mind that if a user is no longer a member of your organization, it is best to deactivate them by changing the Status field to "Inactive" instead of deleting them. This way, the user's historical data remains intact in Sugar still but the user will no longer be able to log in to Sugar. In addition to the Sugar application, the user will also no longer be able to access the Sugar Plug-in for Outlook and Sugar Mobile app once they are deleted.

Note: It is recommended that you reassign the user's records first in Sugar before deleting the user record in SugarIdentity. For more information on reassigning a user's records in Sugar, refer to the User Management documentation.

Use the following steps to delete an existing user from Sugar:

Note: If you use LDAP or SAML, then you will need to delete the user from the LDAP server or identity provider first before following the steps below.

  1. Log in to Sugar and navigate to Admin > User Management.
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
  3. Click the Users tab then select "List Users".
    CS Users ListUsers
  4. Locate the user you wish to delete in the Users list view then click the trash icon to the far right of the record's row. A pop-up message will display asking for confirmation. Click "Confirm" to proceed.
    CS DeleteUser

The user is now deleted from Sugar and can no longer log in to the SugarCRM applications and services. 

Authentication Management

The authentication management capabilities in SugarIdentity allow admin users to configure local password rules and set up LDAP and SAML authentication.

Configuring Local Passwords

Use the following steps to configure the password rules for users logging in to Sugar:

  1. Log in to Sugar and navigate to Admin > Password Management. You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
  2. Configure the password options (e.g. Password Length, Password Expiration) accordingly on the Configure Password page.
  3. Click "Save" to preserve your changes and apply the configuration to Sugar.

Note: When users reset their password by clicking the "Forgot Password?" link on the Sugar login screen, the new password must conform with your configured password requirements.   

Password Fields

The password fields are as follows:

  • Password Length : Click and drag the sliders to indicate the minimum and the maximum number of characters allowed in a password.
  • Must contain one upper case letter (A-Z) : Enable this option to require at least one uppercase letter in every password.
  • Must contain one lower case letter (a-z) : Enable this option to require at least one lowercase letter in every password.
  • Must contain one number (0-9) : Enable this option to require at least one numerical character in every password.
  • Must contain at least one special character : Enable this option to require at least one special character (e.g. #, &, *) in every password.
  • Password Expiration : Select one of the following options to control how long users can utilize their passwords before being forced to choose a new one.
    • None : Passwords will never expire and users will never be forced to choose a new one.
    • Password Expires in : Passwords will expire x days, weeks, or months after their last password was saved.
    • Password Expires upon x logins : Passwords will expire after the user has logged in using their current password x times.
  • Login Lockout : Select one of the following options to control how many times a user may attempt to log in with incorrect credentials before they are prohibited from attempting to log in.
    • None : Users will never be prevented from attempting to log in to Sugar due to invalid credentials.
    • Lockout users after x failed login attempts : Users will be prevented from attempting to log in to Sugar after submitting invalid credentials x times in a row. You can also configure a timeframe in minutes, hours, or days to enable the login again.

Configuring LDAP Authentication

SugarIdentity can be configured to accept Lightweight Directory Access Protocol (LDAP) authentication if your organization has implemented LDAP or Active Directory authentication. When users in your system attempt to log in to Sugar, the application will authenticate their credentials against your LDAP directory or Active Directory. If authentication is successful, the user is granted access to Sugar. If the authentication is unsuccessful, SugarIdentity will then attempt to verify the provided credentials against its own database of valid user names and passwords. When a tenant is configured to use LDAP authentication, the user email must be defined in the LDAP server.

Use the following steps to configure LDAP authentication in SugarIdentity via the Cloud Settings console:

  1. Log in to Sugar and navigate to Admin > Password Management. You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
  2. Click the Authentication tab in the Cloud Settings console and select "Setup LDAP support".
    CS SetupLDAPSupport
  3. Select the "Enable LDAP Authentication" option to enable LDAP and reveal the LDAP configuration fields.
    CS EnableLDAPAuthentication
  4. Enter the appropriate values in the following fields then click "Save" to commit the changes.
    Field Suggested Values Description
    Authentication

    Enter "username@MYSERVER.MYDOMAIN.com" or "domain\\userfirstname.userlastname" for the User Name, and the corresponding Password.

    Note: The latter username format requires double backslashes after the domain. Sugar will automatically remove one backslash upon Save.

    Check this box to enable the User Name and Password fields.

    Note: You must add a service account user (read-only access) to your Active Directory to authenticate via Sugar.

    Auto Create Users Typically, this box remains disabled.

    Enable this checkbox to automatically create a new Sugar user when an LDAP user logs into Sugar for the first time.

    Note: The user will count against the number of licensed user accounts for your instance.

    Bind Attribute For Active Directory, enter userPrincipalName  A case-sensitive value
    Enable LDAP Authentication   Uncheck this box if you would like to disable LDAP authentication.
    Group Membership

    Group DN : Enter the group DN name

    • ou=groups
    • dc=example
    • dc=com

    Group Name : Enter the group name

    • cn=sugarcrm

    Group Attribute : The attribute of the group that will be used to filter against the User Attribute

    • MemberUid

    User Attribute : A unique identifier used to check if the user is a member of the group

    • uid

    Enable this checkbox if you wish to specify that the user is a member of a specific group. 

    Login Attribute For Active Directory, enter sAMAccountName A case-sensitive value
    Port 389 Enter the port number. 389 is the default port.
    Server MYSERVER.MYDOMAIN.com

    Enter the FQDN of your Active Directory Server which should be your Domain Controller.

    User DN ou=people, dc=openldap, dc=com

    Enter the user DN name.

    User Filter is_user_id=1 

    Enter any additional parameters to apply when authenticating users.

Once LDAP is configured, when creating new users in SugarIdentity, you will need to enter the user's LDAP username (e.g. john@example.com) that is defined in your LDAP server.

LDAP Attribute Mapping

By default, LDAP attributes map to the SugarIdentity user fields as described below. When an LDAP user is created in SugarIdentity or the LDAP attributes are modified, these changes will sync to SugarIdentity when the user logs into Sugar. 

LDAP Attributes SugarIdentity User Fields 
givenName given_name
sn family_name
mail email
telephoneNumber phone_number
title title
department department
street address.street_address
l address.locality
st address.region
postalCode address.postal_code
c address.country

Configuring SAML Authentication

SugarIdentity can be configured to accept Security Assertion Markup Language (SAML) for single sign-on if it is implemented at your organization. When users in your system attempt to log into Sugar, the application will authenticate them against SAML. If authentication is successful, the user is granted access to Sugar. If the authentication is unsuccessful, SugarIdentity will then attempt to verify the provided credentials against its own database of valid user names and passwords. Please note that the "Name ID" gets mapped by default to the SAML User Name field in SugarIdentity.

In order to configure SAML authentication in SugarIdentity you must first obtain the identity provider metadata file to import some key data (e.g. Login URL, Entity ID, X509 Certificate). The instructions for doing so with Google, Okta, and ADFS are covered in the following knowledge base articles. Once you have obtained the necessary metadata file, please refer to the Importing IdP Metadata File section below to configure SAML authentication.

Importing IdP Metadata File

Once you have obtained the identity provider metadata file, use the following steps to import the file and configure SAML authentication:

  1. Log in to Sugar and navigate to Admin > Password Management. You will be directed to SugarIdentity in the Cloud Settings console in a new browser tab.
  2. Click the Authentication tab in the Cloud Settings console and select "Setup SAML support".
    CS SetupSAMLSupport
  3. Select the "Enable SAML Authentication" option to enable SAML and reveal the SAML configuration fields.
  4. Click the "Import IdP metadata file" link in the Quick Links menu.
    CS EnableSAMLAuthentication
  5. Find and select the identity provider metadata file. The data (e.g. Login URL, Entity ID, SLO URL, X509 Certificate) it contains will instantly appear on the SAML form in SugarIdentity.
  6. Optionally, complete any other desired fields on the SAML form based on your needs.
    Note: If using Okta with single logout enabled, you will need to complete the "Sign Logout Request", Request Signing Private Key", and "Request Signing Certificate" fields in order to digitally sign the logout request.
    Field Description
    Auto Create Users

    Check this box to automatically create a new username in the Sugar database if it does not already exist. When enabled, a new Sugar user is created for every SAML user logging into the application. 

    Note: This will occupy an active Sugar license for each created user.

    Request Signing Certificate

    Add the Request Signing certificate containing the X.509 certificate to be used to sign the AuthN and Logout requests.

    Note: The certificate should match the private key. 

    Request Signing Method

    Select the digital signing method for request and response to the identity provider. The recommended options are either "RSA-SHA256" or "RSA-SHA512". 

    Request Signing Private Key

    Add the Request Signing Private key to be used to sign the AuthN and Logout requests.

    Note: The private key must be added in order to sign the logout request, logout response, and/or AuthN request.

    Sign AuthN Request

    Enable this checkbox to sign the AuthN request using the private key and certificate.  

    Note: The "Request Signing Private Key", "Request Signing Certificate", and "Request Signing Method" fields must be completed in order to sign the AuthN request.

    Sign Logout Request

    Enable this checkbox to sign the logout request using the private key and certificate.

    Note: The "Request Signing Private Key", "Request Signing Certificate", and "Request Signing Method" fields must be completed in order to sign the logout request.

    Sign Logout Response

    Enable this checkbox to sign the logout response using the private key and certificate. 

    Note: The "Request Signing Private Key", "Request Signing Certificate", and "Request Signing Method" fields must be completed in order to sign the logout response.

    SLO URL

    Enter the single logout endpoint to which SugarIdentity will send logout requests. When SugarIdentity sends a logout request to the identity provider (e.g. Okta), it will extend that request and terminate active sessions for all other service providers that are sharing the session established via SAML.

    Note: Single logout requests can be initiated from either the identity provider or SugarIdentity. This field will be auto-populated if single logout is enabled in Okta. 

    SugarCRM Entity ID

    Enter a valid URI for the service provider entity. 

  7. Click "Save" to preserve the settings.

When using ADFS, please refer to the section below as you will need to export an XML metadata file in order to configure a new trust relationship between SugarIdentity and ADFS. 

Exporting Metadata File for ADFS

When using ADFS, you will need to export an XML metadata file containing the SAML settings which you will need in order to configure a new trust relationship between SugarIdentity and ADFS to allow communication between the two services. Simply click the "Export metadata file" link in the Quick Links menu to download the necessary file. Please note that you will only be able to export a file if the required fields have been completed and saved. Once you have the metadata file, follow the steps in the Configuring SSO With Active Directory's ADFS in Sugar 8.0 and Higher article to configure a new ADFS trust relationship. CS ExportMetadataFile

SAML Attribute Mapping

In order to have SAML attributes map to the SugarIdentity user fields, you will need to set up the attribute mapping in the identity provider (e.g. Okta) using the predefined SAML attribute values. For more information on setting up the attribute mapping, refer to the Configuring SAML Attribute Mapping for SugarIdentity article. Once the attribute mapping is configured, when a SAML user is created in the identity provider or the SAML attributes (e.g. email) are modified, these changes will sync to SugarIdentity when the user logs into Sugar. 

Last modified: 2019-11-13 20:13:14