SugarCRM SupportProduct GuidesSugarCloud ServicesSugarIdentitySugarIdentity Guide

SugarIdentity Guide

Overview

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

Note: Only some SugarCloud instances use SugarIdentity. Refer to the section below to determine if yours is configured to do so. Existing customers will be notified before their instances begin using the service.

Supported Regions

The SugarIdentity service is supported in the following regions:

  • APAC
  • Canada
  • EU
  • Germany
  • North America
  • UK

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 SugarCloud 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. Beginning with version 10.2.0, administrators can also navigate to the Admin page to see if the SugarCloud Settings link appears. 

Prerequisites

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

For information on supported platforms, refer to the SugarCloud Services Supported Platforms page.

Accessing Multiple SugarIdentity-Enabled Instances

Your organization may use multiple SugarIdentity-enabled instances such as your Sugar production environment as well as sandbox environments, and you can log in and access these instances from within the same browser. Each SugarIdentity-enabled instance that you use is associated with a unique tenant ID that is used to authenticate in SugarCloud Settings. Please keep in mind that the number of tenants (e.g. production, sandboxes) and user accounts that you access will determine how the login screen will appear when logging into the SugarIdentity-enabled instance(s). 

If your regular use of Sugar just consists of accessing a single tenant (e.g. ABC Production) and user account, the standard login screen will appear when logging into Sugar. But in circumstances where you access multiple user accounts in the tenant(s) (e.g. ABC Production, ABC Test Sandbox), the login screen will display an account selector similar to the image below and list the last ten users that you have logged in as for the current Sugar instance you are accessing. Each user will be identified by their username or first and last name (if using OIDC authentication) as well as the tenant name and tenant ID for the Sugar instance to which they belong. To access the user's account, simply click on the desired username (e.g. jsmith) on the screen. To log in to an unlisted user's account, click the "Show log in form" link then enter the user's login credentials on the following screen.
SCS LoginScreen ShowLogInForm

Please note that an account selector will also appear on the login screen when accessing SugarCloud Settings if you have logged into multiple user accounts in the tenant(s). The account selector will display a list of the last ten users that you logged in as across the various tenants. If you wish to log in to an unlisted tenant or admin user account, simply click the "Log into another tenant" link then enter the tenant ID followed by the user's login credentials to access the SugarCloud Settings console.
SCS LoginScreen LogIntoAnotherTenant

Accessing the SugarCloud Settings Console

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

For Sugar versions 10.0.x:

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

For Sugar versions 10.3.0 and higher:

  •  Admin > SugarCloud Settings 

You will automatically be authenticated in SugarCloud Settings because you have an active Sugar session. Alternatively, you can navigate directly to the SugarCloud Settings console via the URL where you will need to enter your tenant ID (supplied by Sugar) and credentials to log in. If your Sugar instance uses multi-factor authentication, you will need to use an authenticator app (e.g., Authy, Google Authenticator) and enter the 6-digit verification code generated from the app when logging in to the SugarCloud Settings console. Please note that logging in to the SugarCloud Settings console will automatically log you into your SugarIdentity-enabled instance and vice versa since they both share the same login service. 

Note: The SugarCloud Settings console only allows one active session at a time.

Setting Your Language

You have the option to choose the primary language you wish to be displayed in the SugarCloud Settings console by clicking the Language link on the bottom right of the Cloud Setting's login screen. The Language dropdown list will appear and you can simply select the desired language you wish to display. Please note that administrators can also set the default language globally via Admin > Locale in the Sugar application. For more information on configuring the default language in Sugar, refer to the System documentation. Also, if any languages are disabled in Sugar via Admin > Languages, they will not be available to select in the Language dropdown list in SugarCloud Settings. 
SugarIdentity CS Language1

The following languages are available for use in SugarCloud Settings:

Albanian Hungarian
Arabic Italian
Brazilian Portuguese Japanese
Bulgarian Korean
Catalan Latvian
Chinese (Simplified) Lithuanian
Chinese (Traditional) Norwegian
Croatian Polish
Czech Portuguese
Danish Romanian
Dutch Russian
English (UK) Serbian
English (US) Slovak
Estonian Spanish
Finnish Spanish (Latin)
French Swedish
German Thai
Greek Turkish
Hebrew Ukrainian

Logging Out

When you are done working in the SugarCloud Settings console and wish to log out, simply click the Logout icon on the upper right of the SugarCloud Settings page. You will also be automatically logged out of the SugarCloud Settings console when you log out of your SugarIdentity-enabled instance. Please note that logging out of the SugarCloud Settings console will not log you out of Sugar.
SCS Logout1

Tenant Settings

The tenant settings can be accessed by clicking the Gear icon at the top of the SugarCloud Settings page and selecting "Tenant Profile". The Tenant Settings page will open to display the tenant ID and region associated to the particular SugarIdentity-enabled instance and allow you to configure the tenant name and a custom logo. As a best practice, if your organization uses multiple SugarIdentity-enabled instances (e.g. production, sandboxes), please update the tenant name (e.g. ABC Production, ABC Test Sandbox) to be unique for each instance so that it is easier to differentiate them. This is especially helpful in identifying which instance a user belongs to when the account selector appears on the login screen. 
SCS TenantProfileSetting

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 SugarCloud Settings application. To configure a new SugarCloud Settings icon, simply 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.
SCS TenantSettingsPage

SCIM Settings

If your organization uses SAML and has already configured SAML authentication in SugarIdentity, you have the option to configure SCIM (System for Cross-domain Identity Management) for the identity provider (e.g. OneLogin, Okta) which will allow user identity information (e.g. email, phone number) to automatically sync from the identity provider to SugarIdentity in real-time. Please note that the sync behavior will be different depending on whether you have SCIM configured or not as summarized in the table below:

SCIM Configured Sync Behavior
Yes Data sync occurs in real-time
No Data sync occurs when the SAML user next logs into Sugar

To configure SCIM for the identity provider, you will need to obtain the required SCIM credentials (e.g. Server URL, Bearer Token) by clicking the Gear icon at the top of the SugarCloud Settings page and selecting "SCIM Settings".
SCS SCIMSettings

On the SCIM Settings page, click the Create Client button to generate the "Server URL", "Username", "Password", and "Bearer Token" values. For more information on configuring SCIM for the different identity providers, refer to the Configuring SCIM for SugarIdentity WIth Okta or Configuring SCIM for SugarIdentity articles. Please note that the SCIM credentials required for configuring SCIM will vary between identity providers (e.g. OneLogin, Okta). For example, when configuring SCIM for OneLogin, you will only need the "Server URL" and "Bearer Token" values.
CS SCIMSettingsValues 

Changing Password

In addition to the Change Password option in Sugar, administrators also have the ability to change their password in SugarIdentity via the SugarCloud Settings console. Simply click the Gear icon at the top of the SugarCloud Settings page and select "Change Password". The Change Password screen will open and display the Old, New, and Confirm password fields as well as your organization's configured password requirements (if any). 
SCS ChangePassword

To change your Sugar password, simply enter your current password, new password, and confirmed password making sure to meet all the password requirements listed on the screen. Please note that the password requirements for Sugar can be configured in the SugarCloud Settings console by clicking the Authentication tab and selecting "Setup Password". Administrators can set the minimum and maximum lengths required for the password, as well as indicate if any special characters are needed. Additional requirements such as upper case, lower case letters, and numbers can also be a part of the password requirements. Once you have entered the new password, click "Confirm" to preserve the change. A success message will appear once the password has been updated successfully; click "Continue" to be directed back to the SugarCloud Settings console. You will also receive an email notification confirming that your Sugar password has been changed. 

User Management

The Users tab in the SugarCloud Settings console allows you to perform various actions such as creating user records for your Sugar instance. To access the Users list view, simply click the Users tab and select "List Users". The actions menu also includes the Create New User and Create Multiple Users options which allows you to create new users via the edit view layout as well as import a list of users using a .csv file. Please note that clicking the Create New User option from Sugar will also navigate you directly to the Create User page in the SugarCloud Settings console.
SCS UsersTab

SugarIdentity User Fields

The SugarIdentity user record in the SugarCloud 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, SAML, or OIDC 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) 1 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 Authentication1 The username (e.g. john@example.com) associated with the user authenticating the LDAP directory
User Name (OIDC Authentication1 The unique alphanumeric ID (e.g. User ID) associated with the user defined in the identity provider (e.g. Okta, Auth0)
User Name (SAML Authentication1 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

1 Depending on whether the user is set up to access Sugar using Local, LDAP, OIDC, or SAML authentication will determine the value that appears in the Login column of the Users list view. For example, if the user is set up for local authentication, the Login column will display "Regular Login". If the user is set up for both local authentication and SAML authentication, then the Login column will display "Regular Login" and "SAML" for the user.

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. Please note that you can preview a new user's account to ensure that it is set up correctly by logging in to their account using the "Impersonate (Log in as)" option. For more information, refer to the Impersonating Users section below.

When using LDAPSAML, or OIDC, 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, SAML, and OIDC, please note that the user must already exist in the LDAP server or identity provider before they can be manually provisioned in SugarIdentity.

For best practices around user creation for SugarIdentity, please refer to the section below.  

Best Practices When Creating Users

Before creating users in Sugar, please review the following best practices first depending on your scenario: 

Creating Users With SAML and SCIM

If you use SAML and have configured SCIM for the Identity Provider (e.g. OneLogin), when a new user is created in the identity provider and assigned to the SCIM application, the SAML user will be automatically created in Sugar in real-time.

As a best practice, if you wish to assign teams and roles to the user, please do so as soon as you assign the user to the SCIM application since the user could potentially log into Sugar before their access has been appropriately restricted.

Creating Users With SSO

When using LDAPSAML, or OIDC, if the "Auto Create Users" option is enabled, then adding a new user to your directory service or identity provider (e.g. Okta) will automatically create a new user record in Sugar when the LDAP, SAML, or OIDC user logs into Sugar for the first time. If you wish to assign teams and roles to the user, it is recommended that this option not be enabled since the user can log into Sugar before their access has been appropriately restricted.

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. When creating the user in SugarIdentity, you must complete the User Name field for the LDAP, SAML, or OIDC authentication as follows: 

  • LDAP User Name: Enter the user's email address (e.g. john@example.com) defined in your LDAP server. 
  • SAML User Name: Enter the user's email address (e.g. john@example.com) defined in your identity provider. 
  • OIDC User Name: Enter the unique ID (e.g. User ID) associated with the user's account in the identity provider (e.g. Okta, Google).

Once the user's account has been configured properly, the user can then access Sugar. For information on attribute mapping, refer to the sections below for LDAP, SAML, and OIDC.

Creating Users Without SSO

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 that allows them to create their Sugar password and access their account. If you wish to assign teams and roles to the user, it is recommended that this option not be enabled since the user could potentially log in to Sugar before their access has been appropriately restricted.

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.

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 SugarCloud Settings console. Please note that clicking the Create New User option from Sugar will navigate you directly to the Create User page in the SugarCloud 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.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console and skip step 2. 
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the SugarCloud 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. 
    • If you use LDAP, SAML, or OIDC, you will need to click the "Add LDAP authentication", "Add SAML authentication", or "Add OIDC authentication" link. Do not enable the "Send email to user" checkbox if you are only creating a new user for LDAP, SAML, or OIDC authentication without local authentication.
      • For LDAP and SAML, enter the user name (e.g. john@example.com) defined in your LDAP server or identity provider. The Email field should contain the mail attribute defined in the LDAP server or identity provider.
      • For OIDC, enter the unique alphanumeric ID (e.g. User ID) associated with the user's account in the identity provider (e.g. Okta, Google).

      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. Beginning with version 10.2.0, you can also update existing user records via the Import Users option in the Sugar application.

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.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console and skip step 2. 
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the SugarCloud Settings console in a new browser tab.
  3. Next, click the Users tab in SugarIdentity and select "Create Multiple Users".
    SCS Users CreateMultipleUsers
  4. Click the download link to download the import file template then enter your data into the appropriate columns adhering to the following guidelines:
    • The First Name, Last Name, Email, Status, and User Name fields are required for import. 
    • If you use LDAPSAML, or OIDC, be sure to include the user's LDAP, SAML, or OIDC user name 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, select the import file, then click "Next". Please note that 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, SAML, or OIDC

If you use LDAP, SAML, or OIDC, 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. If you use SAML and have configured SCIM for the identity provider (e.g. OneLogin), then please disregard this option since SCIM allows new SAML users to be automatically created in Sugar regardless of this setting.

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".
  • To enable auto-create for an instance that is configured with OIDC, navigate to Authentication > Setup OIDC 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, or OIDC 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. 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.

Viewing Users

The Users list view displays all user records in Sugar as well as some key user fields such as Name, User Name, Email, etc. To access the list view, simply click the Users tab and select "List Users". To view the user's basic contact information and other employment-related information, click the user's name (e.g. John Smith) in the list view. If you wish to view other stock and/or custom user fields that do not appear in the SugarCloud Settings console, you will need to navigate back to your Sugar instance. 

The Login column in the Users list view will display "Regular Login", "LDAP", "OIDC", or "SAML" depending on the type of authentication (e.g. Local Authentication, SAML Authentication) configured in the user's record. For example, if the user is set up for local authentication, the Login column will display "Regular Login", and the user will access their account using Sugar credentials. If the user is set up for both local authentication and SAML authentication, then the Login column will display "Regular Login" and "SAML" for the user (e.g. John Smith).

You can also sort the Users list view by a field column in either ascending or descending order by clicking the appropriate column header (e.g. Department). Please note that you can only sort the list view by one column at a time. To adjust the size of the columns in the list view, place your cursor on the column divider, and when the left-and-right arrow appears, click and drag the column to your desired size. The set column width will be preserved when you navigate away from the page or logout from SugarCloud Settings. Clearing or resetting the relevant browser cookies will revert the column width(s) back to the default size.
SCS ViewingUsersViaLV

Impersonating Users

Beginning with Sugar version 11.1.0, administrators have the ability to log in as non-admin users in their organization using the "Impersonate (Log in as)" option in the SugarCloud Settings console. When impersonating a user in Sugar, the administrator will be able to access and view the same modules and settings as the user's actual account without having to obtain their login credentials.

Some common use cases for impersonating a user in Sugar are:

  • Reproducing or troubleshooting a user-reported issue directly from the user's account.
  • Previewing a new user's account to ensure that it is set up correctly before the user first logs in to Sugar.  
  • Previewing a user's account after assigning new teams and roles to ensure that the proper permissions and restrictions are in place. 
  • Creating and/or configuring dashboards for users directly in their account. 
  • Performing any necessary tests or validating user interface changes in the user's account.

To impersonate a user, navigate to the Users list view in the SugarCloud Settings console, and click the down arrow to the far right of the desired user's row and select "Impersonate (Log in as)". This will initiate the impersonation session, and the selected user's account will automatically open in a new browser tab. A purple banner will display above the navigation bar on every screen during the impersonation session, with text similar to the following: "Administrator, you are currently impersonating Chris Olliver". The user will be able to utilize their Sugar account concurrently while you are impersonating as them.

Note: Please keep in mind the guidelines in the section below when impersonating users in Sugar.
SCS UsersLV ImpersonateOption

Note: If you have Sugar open in another browser tab when you initiate the impersonation session, and the impersonated user does not have access to the page (e.g. Administration page) in that tab, you will see an Access Denied warning message appear on the screen. Simply refresh the page and the impersonation session will load in the tab. 

The impersonation session will remain active until Sugar's access token expires. Once the access token expires, the current impersonation session will abruptly end, and you will run into the effects of a known issue in Sugar 11.1 where you will begin to impersonate your own user account. When this occurs, click the Finish Impersonating button in the purple banner, and initiate a new impersonation session in the SugarCloud Settings console if you wish.

Once you have performed the necessary actions in the user's account, be sure to click the Finish Impersonating option to end the session and avoid any unexpected behaviors in Sugar. The Finish Impersonating option can be found in the following locations during the impersonation session:

  • Purple impersonation banner
    Impersonation FinishImpersonating Button
  • User menu:
    Impersonation UserMenu FinishImpersonating

Once you click the Finish Impersonating option, you will be logged out of the impersonation session. Please note that if you have other Sugar tabs open in the browser, you can refresh the page and your Sugar admin account will reload in those tabs. You can also navigate back to your Sugar account by entering your instance URL in a new browser tab.

Impersonation Rules

When impersonating a user in Sugar, please keep in mind the following guidelines:

  • User impersonation is supported for Sugar versions 11.1.0 and higher.
  • The impersonation session will be active until the Access Token Lifetime expires (default 60 minutes). You can view the Access Token Lifetime value defined for your instance on the Advanced Settings page in the SugarCloud Settings console.
  • You can only impersonate one user at-a-time. 
  • You can impersonate users with an active or inactive status.  
  • You cannot impersonate another system administrator user.
  • You can continue accessing the SugarCloud Settings console during the impersonation session. 
  • If you happen to click the Impersonate option for another user while already impersonating a user, this will end the current impersonation session and start a new session for the selected user. 
  • Any changes made in the user's account will be logged as being made by the user and not by you, the administrator. 
  • Each impersonation session that an admin user initiates will get logged in the system with the following info: Start date/time, admin user's SRN (user ID), and impersonated user's SRN. Please note that this information is only accessible by Sugar Support. 

Searching Users

You can perform a search in the Users list view to pull up relevant records that you wish to view. Simply enter a keyword (e.g. john) in the Search box and as you begin typing, the search will immediately start returning results for records matching the search term. As you make changes to the text entered in the search box, the search results will update dynamically to display additional and/or new matching records. All records matching the search term will display in the list view below the Search bar. The following fields are included in the Users list view search:

  • Name (Full Name)
  • First Name
  • Last Name
  • User Name
  • Title
  • Department
  • Email
  • Phone 

The search in SugarCloud Settings uses the "starts-with" search. So, for example, performing a search for "john" will pull up "John Smith" and "Sue Johnson" as the user's first and/or last name begins with "john". You can also perform a partial search by entering a part of the keyword in the search box. So, entering "jac" will pull up "Jacob Rivers", "Robert Jackson", and "Jackson Westin" in the search results. If you update the search term to be "ja", then the search results will also include "Janet Rose" and "Tim Jansen", as well as Jim Albertson with user name "jalbertson". 
SCS SearchResults

Editing Users

SugarIdentity user records may be edited at any time to modify or add information via the SugarCloud Settings console. If you wish to edit other stock and/or custom user fields that do not appear in SugarIdentity, you will need to navigate back to Sugar to make the appropriate changes. 

Editing Users With SAML and SCIM

If you use SAML and have configured SCIM for the Identity Provider (e.g. OneLogin), you can modify the user's mapped attributes (e.g. phone, title) directly in the identity provider and the changes will sync to SugarIdentity in real-time. For more information on attribute mapping, refer to the SAML Attribute Mapping section. Please note that modifying the user fields in SugarIdentity will not sync back to the identity provider. 

Editing Users With SSO

For customers using LDAP, SAML, or OIDC, you can modify the mapped attributes directly in the LDAP server or identity provider to maintain consistent data since the changes will sync to SugarIdentity when the user next logs into Sugar. Please note that modifying the user fields in SugarIdentity will not sync back to the LDAP server/identity provider. 

The attribute mapping behavior is as follows for LDAP, SAML, and OIDC:

  • LDAPLDAP attributes map to the SugarIdentity user fields by default.
  • SAML: Only the Name ID claim (email address) is mapped by default to the SAML User Name field in SugarIdentity, but you can set up the attribute mapping in the identity provider to have other SAML attributes mapped to SugarIdentity user fields.
  • OIDC: The attribute mapping varies between the identity providers.  

Editing Users Without SSO

Use the following steps to edit an existing user record in SugarIdentity:

  1. Log in to Sugar and navigate to Admin > User Management.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console and skip step 2. 
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the SugarCloud 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.
    SCS Users ListUsers1
  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 SugarCloud Settings, select the user record from the Users list view, edit it, then save.

Mass Editing via List View

Mass updating allows you to apply the same changes to multiple user records at once from the Users list view. Once you have located the desired records on the list view, you can either choose individual user records or select all records displayed on the current set of list view results by clicking the checkbox to the left of the Actions menu. 

Use the following steps to mass update user records from the list view: 

  1. Log in to Sugar and navigate to Admin > User Management.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console and skip step 2. 
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the SugarCloud Settings console in a new browser tab.
    Sugar Users CreateNewUser1
  3. Next, click the Users tab, select "List Users", then use the list view search to identify users you wish to modify.
  4. Select the desired users then choose "Mass Update" from the Actions menu.
    Note: To select all records displayed on the current set of list view results, click the checkbox to the left of the Actions menu. A dialog will appear below the list view's column headers indicating that you have selected all records on the list view's current result set. To select all records in the results set, click "Select all records" in the dialog. You can clear the selections for all records on the result set by either clicking the "Clear selections" link in the subsequent dialog or clicking the checkbox option again to remove the checkmarks. 
    SCS Users MassUpdate1
  5. The Mass Update panel will appear below the search bar. Set values for the field(s) (e.g. User Type) you wish to alter. If you do not wish to mass update the records, simply click the Cancel button.
    SCS MassUpdate Panel
  6. To mass update several fields at once, click the plus button to the right of the row to add additional fields. Click the minus button that appears to remove the field(s).
  7. Click "Update" to save the changes to all of the selected user records.

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. Users that have been deactivated do not count against the number of licensed user accounts for your instance. When changing the user's status to "Inactive", please also consider updating the Employee Status field for the user in the Sugar application to update their employment status in the Employees module.   

The steps to deactivate a user in Sugar will vary depending on how SugarIdentity has been configured. Please refer to the section below that best applies to your scenario:

Deactivating Users With SAML and SCIM

If you use SAML and have configured SCIM for the Identity Provider (e.g. OneLogin), you can deactivate the user from the identity provider and the change will automatically sync to SugarIdentity and update the user's status to "Inactive". Once the user's status has been changed in the identity provider, please confirm that the status change is reflected correctly in Sugar. 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.

Deactivating Users With SSO

If you use LDAPSAML, or OIDC, you will need to deactivate the user from the LDAP server or identity provider first before following the steps in the section below. Please note that changing the user's status in SugarIdentity will not sync back to the Identity Provider. 

Deactivating Users Without SSO

Use the following steps to deactivate a user in Sugar:

  1. Log in to Sugar and navigate to Admin > User Management.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console and skip step 2. 
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the SugarCloud 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.
    SCS Users ListUsers1
  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. Please note that you can also mass update the user's status via the Mass Update option in the Users list view. 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 SugarCloud 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.

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.

Note: Deleting the user record via the SugarCloud Settings console will delete the corresponding user and employee records from Sugar.  

The steps to delete a user from Sugar will vary depending on how SugarIdentity has been configured. Please refer to the section below that best applies to your scenario:

Deleting Users With SAML and SCIM

If you use SAML and have configured SCIM for the Identity Provider (i.e. OneLogin), you can delete the user from the identity provider and the user record will be automatically deleted from Sugar in real-time. Once the user has been deleted from the identity provider, please confirm that the user's record has been deleted accordingly in Sugar.

Deleting Users With SSO

If you use LDAPSAML, or OIDC, you will need to delete the user from the LDAP server or identity provider first before following the steps in the section below. 

Deleting Users Without SSO

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

  1. Log in to Sugar and navigate to Admin > User Management.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console and skip step 2. 
  2. Click the triangle in the Users module tab and select "Create New User". You will be directed to SugarIdentity in the SugarCloud Settings console in a new browser tab.
  3. Click the Users tab then select "List Users".
    SCS Users ListUsers1
  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.
    SCS UsersLV Delete

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 various settings such as local password rules, multi-factor authentication, and OAuth2 token lifetimes as well as set up LDAPSAML, or OIDC 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 SugarCloud 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 login screen, the new password must conform with your configured password requirements, which will appear on the reset password screen.   

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 Multi-Factor Authentication

SugarIdentity supports multi-factor authentication, a security mechanism, which provides an added layer of security when logging in to Sugar to prevent unauthorized users from gaining access to your users' accounts. When using multi-factor authentication, your users will be required to use an authenticator app (e.g., Authy, Google Authenticator, Microsoft Authenticator) when logging in to Sugar and enter a new 6-digit code generated from the app each time they log in to verify their identity. So, identity verification using an authenticator app will be a required step to access their Sugar account. Please note that you will also need to use an authenticator app when logging in directly to the SugarCloud Settings console.

Once multi-factor authentication is enabled for your Sugar instance, the following Sugar products will also use multi-factor authentication when logging in using SugarIdentity:

Use the following steps to enable multi-factor authentication for your Sugar instance:

  1. Log in to Sugar and navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console.
  2. Click the Authentication tab in the SugarCloud Settings console and select "Setup Password".
    CS Authentication SetupPassword
  3. Place a check in the Enable box under the Multi-Factor Authentication section of the page, then click "Save". 
    CS EnableMFA
  4. A pop-up message will display asking for confirmation. Click "Confirm" to proceed.

Note: Multi-factor authentication only applies to users who log in using Sugar credentials or use LDAP authentication

Once multi-factor authentication is enabled for your instance, all users who log in using Sugar credentials or use LDAP authentication will need to install an authenticator app (e.g., Authy) on their mobile device and use multi-factor authentication on their next log in. The first time they log in to Sugar after multi-factor authentication has been enabled, they will be prompted to scan a QR code using the authenticator app to pair the app with Sugar. The authenticator app will then generate a 6-digit code which the user must enter during the login process to access their account. Going forward, users will be required to enter a new 6-digit code from their authenticator app each time they log in to Sugar. For more information on logging in to Sugar using multi-factor authentication, refer to the Getting Started documentation. 

If you wish to disable multi-factor authentication for your instance, click the Enable checkbox option to remove the checkmark and click "Save". Once disabled, the multi-factor authentication will be reset for all users, and an authenticator app will no longer be needed the next time they log in to Sugar. If multi-factor authentication is enabled again later, users will need to re-authenticate using an authenticator app and scan the QR code to pair the app with their Sugar account.

Resetting Multi-Factor Authentication

If a user can no longer access their authenticator app because, for example, they lost their mobile device, administrators may reset the multi-factor authentication for their account. Performing this action will reset multi-factor authentication for the user and they will be required to re-authenticate using an authenticator app the next time they log in to Sugar. Please note that users also have the ability to reset multi-factor authentication for their account by using the Reset Multi-Factor Auth option in their Sugar account. For more information, refer to the Getting Started documentation.

Use the following steps to reset multi-factor authentication for a user:

  1. Log in to Sugar and navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console.
  2. In the Users list view, locate the desired user and click the record actions menu to the far right of the record's row then select "Reset Multi-Factor Authentication".
    CS ResetMFA1
  3. A pop-up message will display asking for confirmation. Click "Confirm" to proceed.

Note: Administrators can also reset multi-factor authentication for their own user account in the SugarCloud Settings console using the same steps above.  

The next time the user logs in to Sugar, they will be required to scan the QR code to pair the authenticator app with their Sugar account.

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 SugarCloud Settings console:

  1. Log in to Sugar and navigate to Admin > Password Management. You will be directed to SugarIdentity in the SugarCloud Settings console in a new browser tab.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console.
  2. Click the Authentication tab in the SugarCloud Settings console and select "Setup LDAP support".
    SCS Authentication 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.
    Encryption
    • Select "SSL" for LDAPS if the LDAP server supports it.
    • Select "TLS" for StartTLS if the LDAP server supports it.
    • Select "none" for no encryption.
    Select the appropriate option from the dropdown to use Secure Socket Layer (SSL), Transport Layer Security (TLS), or no encryption when connecting to the LDAP server.
    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
    • Enter "636" if using SSL encryption.
    • Enter "389" if using "TLS" or no encryption.
    Enter the default port number. 
    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 (SSO) if it is implemented at your organization. When users in your system attempt to log in to 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.

To configure SAML authentication in SugarIdentity, you must first configure ADFS, Google, Okta, and OneLogin to allow external authentication then obtain the identity provider metadata file to import some key data (e.g. Login URL, Entity ID, X509 Certificate). When configuring the identity provider (e.g. Okta, OneLogin, Google) for single sign-on, you must enter the Assertion Consumer Service URL which can be obtained from the SAML settings page in SugarCloud Settings. Once you have obtained the necessary metadata file, refer to the Importing IdP Metadata File section below to configure SAML authentication.
SCS Authentication SetupSAMLSupportPage

Note: If you have configured SAML authentication for SugarIdentity before December 1, 2020, and would like your users to be able to initiate login to Sugar from their Okta, OneLogin, or G Suite dashboard, refer to the Reconfiguring SAML Authentication Using ACS URL for SugarIdentity article.

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 SugarCloud Settings console in a new browser tab.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console.
  2. Click the Authentication tab in the SugarCloud Settings console and select "Setup SAML support".
    SCS Authentication 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 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 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 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 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 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 any ID to define your company. 

  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 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 (e.g. Assertion Consumer Service URL) which you will need 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 article to configure a new ADFS trust relationship.
CS ExportMetadataFile

SAML Attribute Mapping

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 next logs into Sugar. If you have configured SCIM for the identity provider (e.g. OneLogin), then the changes will automatically sync to SugarIdentity in real-time.

Configuring OIDC Authentication

SugarIdentity can be configured to accept OpenID Connect (OIDC) for single sign-on if it is implemented at your organization. When users in your system attempt to log in to Sugar, the application will authenticate them against OpenID Connect. 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.

To configure OIDC authentication in SugarIdentity, you must first obtain some key information (e.g. OIDC Server Authentication Endpoint, Client ID, Client Secret). The instructions for doing so with Auth0, Azure, Google, and Okta are covered in the following knowledge base articles. Once you have obtained the necessary information, refer to the following steps below to configure OIDC authentication.

Use the following steps to configure OIDC authentication in SugarIdentity via the SugarCloud Settings console:

  1. Log in to Sugar and navigate to Admin > Password Management. You will be directed to SugarIdentity in the SugarCloud Settings console in a new browser tab.
    Note: For Sugar versions 10.2.0 and higher, navigate to Admin > SugarCloud Settings to access the SugarCloud Settings console.
  2. Click the Authentication tab in the SugarCloud Settings console and select "Setup OIDC support".
    SCS Authentication SetupOIDCSupport1
  3. Select the "Enable OIDC Authentication" option to enable OIDC and reveal the OIDC configuration fields.
  4. Enter the appropriate values in the following fields, then click "Save" to commit the changes.
    Field Description
    OIDC Server Authentication Endpoint

    Enter the authentication endpoint which is used by the Login Service to obtain authorization from the resource owner via user-agent redirection.

    OIDC Server Token Endpoint Enter the token endpoint which is used by the Login Service to obtain an access token by presenting its authorization grant or refresh token.
    OIDC Server Userinfo Endpoint Enter the user info endpoint which is used to obtain the user information from the identity provider (e.g. Okta).
    ClientID Enter the Client ID obtained from the identity provider (e.g. Okta).
    Client Secret Enter the Client Secret obtained from the identity provider (e.g. Okta).
    Scopes

    Choose the scopes to use during OIDC authentication: 

    • OpenID: Used to obtain the ID token.
    • Profile: Used to read the user's first and last name.
    • Email: Used to read the user's email address.
    • Address: Used to read the user's address.
    • Phone: Used to read the user's phone number.

    Note: The OpenID, Email, and Profile options are required for OIDC and must be selected. 

    Redirect URI

    This field is pre-populated by default. The value is required to be entered when configuring the identity provider (e.g. Okta) for OpenID Connect. 

  5. Click "Save" to preserve the settings.

Once OIDC authentication is configured, when creating new users in SugarIdentity, you will need to enter the user's OIDC user name, which is a unique alphanumeric ID (e.g. User ID) that is defined in the identity provider (e.g. Okta). It is recommended that the Show Full Names option in Admin > System Settings be enabled in your Sugar instance to avoid having the alphanumeric IDs display in Sugar. 

OIDC Attribute Mapping

By default, certain attributes (e.g. first name, last name) from the identity provider (e.g. Okta) will map to the SugarIdentity user fields once you configure the OIDC authentication. Please note that when a new user is created in the identity provider (e.g. Okta) or the OIDC attributes are modified, these changes will sync to SugarIdentity when the user next logs into Sugar.

The following table outlines the general attribute mapping between OIDC and SugarIdentity, but please note that the default attribute mapping varies between the identity providers.

OIDC Attributes SugarIdentity User Fields 
sub User Name
email Email
given_name Fiirst Name
family_name Last Name
phone_number Work Phone
address.street_address Address Street
address.locality Address City
address.region address.street_address
address.postal_code Address Postal Code
address.country Address Country

The following table below outlines the default attribute mapping between the supported identity providers and SugarIdentity.

Note: The user's address, phone, title, and department attributes do not map between Auth0, Azure, Google and SugarIdentity. So, you will need to manually enter/update this information when creating the user(s) in SugarIdentity or when these OIDC attributes are modified in the identity provider if you wish to maintain consistent data.   

Identity Provider Attributes Mapped to SugarIdentity 
Auth0

First Name, Last Name, Email 

Azure First Name, Last Name, Email
Google First Name, Last Name, Email
Okta

First Name, Last Name, Email, Work Phone, Address 

Note: If you wish to have the "Title" and "Department" attributes mapped to SugarIdentity, you will need to set up the attribute mapping in Okta.

Configuring OAuth2 Token Lifetimes

When a user logs in to Sugar, an access token and a refresh token are returned which regulate the user's session timeouts in Sugar. By default, Sugar's access token lifetime is 60 minutes and the refresh token lifetime is 20160 minutes (2 weeks). When an access token expires during an active user session, Sugar will renew the user's access and refresh tokens until the user's activity stops. If the user's activity stops but they have Sugar open in a browser tab, Sugar will continue to pull for another access token until the refresh token expires. However, if the user closes their browser tab without logging out of their account, Sugar will stop renewing the user's access token at this point. If the user later opens Sugar in a new browser tab and the last refresh token is still valid, Sugar will then renew the access token using this refresh token, and the user will still be logged in. 

To configure the Access Token Lifetime and Refresh Token Lifetime settings for your organization, simply click the Authentication tab and select "Advanced Settings" in the SugarCloud Settings console. By default, the Access Token Lifetime is set to 60 minutes and the Refresh Token Lifetime is set to 20160 minutes on the Advanced Settings page.
SCS AdvancedSettings AT&RT

To update the token lifetime values, simply enter the whole number value (e.g. 90) in the desired field (e.g. Access Token Lifetime), keeping in mind the following guidelines:

  • The access token lifetime must be less than the refresh token lifetime.
  • The access token lifetime must be at least 5 minutes.
  • The refresh token lifetime must not exceed 20160 minutes.

After entering your desired value, click "Save" to preserve your changes. Please keep in mind that the new access and refresh token lifetimes will not take effect until the user's current access token expires in their user session. Once expired, Sugar will then renew the user's access and refresh tokens using the new value(s) configured in SugarCloud Settings.

Note: If your instance of Sugar gets provisioned to use the SugarIdentity service and you use custom access and refresh token lifetimes, the custom token values will appear in "minutes" on the Advanced Settings page. However, if your custom access token value is less than 5 minutes and/or your refresh token value is greater than 20160 minutes, then the Advanced Settings page will display the system default value(s), which Sugar will use instead of your invalid custom value(s).

Last modified: 2021-08-26 16:43:20