What you need to know about the new SugarIdentity service!

The 'idm_mode' config setting was moved out of config.php and into the database. It's now necessary to update the config table to disable this setting for a local backup. Instructions updated below.

Those who have been around a while will know that SugarCRM Inc. was built around a single product called “Sugar”. Sugar is such a part of our DNA today that we often use “Sugar” and “SugarCRM” terms interchangeably. I’m sure that many Sugar Developers out there would be surprised to learn that we sell more than just Sugar at SugarCRM!

Sugar has been good to us but the way apps were built in 2004 and how apps are developed today are much different. We’ve been thinking about how we want to build, deploy, and maintain new applications and services today and in the future. This has led us to a long term investment to develop a framework for new cloud-based services that are tightly integrated with Sugar.

The tip of the spear is a new set of identity and access management services that we call SugarIdentity. Coming to a Sugar instance near you in June 2019!

What is SugarIdentity service?

SugarIdentity is a set of user authentication and access management microservices that will improve how we manage Sugar cloud users today. Regardless of the SugarCRM products and services you are using, you will be able to manage your end users in one place. This will make life easier for Sugar administrators while allowing SugarCRM engineers and Sugar Developers to more easily integrate Sugar and other applications and services including those built by partners and ISVs in the future.

It will offer improved OAuth 2.0 support, leverages OpenID Connect, and will also address a frequent customer request to support SAML Web Single Sign On (SSO) with the MS Outlook Plug-In.

SugarIdentity also supports the concept of Service Accounts which can be used to implement secure Server to Server integrations much easier without involving end user credentials.

It also provides a new Cloud Settings user interface that Sugar administrators will use to manage end users and some subtle but important changes to end user login experience.

We plan to start on-boarding new Sugar cloud customers in some regions to SugarIdentity service in June 2019.

Frequently Asked Questions

We’ve just recently finished up our SugarIdentity Beta where we asked a handful of partners and customers to test drive the new system. We received a lot of valuable input that we used to improve these services. We also received a number of questions from Sugar Developers that we wanted to share below:

How do I know if a given Sugar instance is using SugarIdentity?

SugarConfig settings are updated in order to connect a Sugar instance to SugarIdentity services. This will be done automatically for our Sugar cloud customers. SugarIdentity does not currently support Sugar on-premise installations. In practice, you can check the public metadata REST endpoint for any given Sugar cloud instance to see if it is operating in “IDM mode”.

GET /rest/v11_4/metadata/public

The response will include:



   “config” : {


      “idmModeEnabled”: true | false





This setting will be true if SugarIdentity is in use.

How to find the Tenant ID for a given Sugar instance?

In most cases, you will not need to know the specific Tenant ID for your Sugar instance in the Sugar cloud. However, it can be useful to know if you need to login to Cloud Settings console directly.

For example, it can be used with the tenant_hint URL parameter to allow more seamless logins to Cloud Settings.


The Tenant ID can be retrieved from a Sugar instance’s SugarConfig settings or from the public metadata API.

GET /rest/v11_4/metadata/public

The response will include:



   “config” : {


      “tenant”: “srn:cloud:iam:us-west-2:{TENANT_ID}:tenant”





The tenant config property above is an example of a Sugar Resource Name (SRN). SRNs are used to uniquely identify resources across the Sugar cloud ecosystem. You’ll see more SRNs as you adopt the new platform and we roll out more features.

How do I deploy a backup of a Sugar cloud instance that uses SugarIdentity?

If you have a backup of a Sugar cloud instance that was configured to use SugarIdentity then it will not likely work without some configuration changes. This is because your local system will not have permission to access the identity services running in the Sugar cloud.

Take the following steps to disable SugarIdentity before working with the backup.

Run the following SQL query on your local Sugar DB:

UPDATE config SET value = 0 WHERE category = 'idm_mode' AND name = 'enabled'

In a terminal, remove cache/ directory contents:

$ rm -rf [path to sugar]/cache/*

How does Users module change with SugarIdentity?

User information is now federated across SugarIdentity services and the Sugar instance Users module. When a Sugar instance is connected to SugarIdentity, there will be specific User fields that are no longer owned by the Sugar instance. For example, the user name or e-mail address will be modifiable by a new Cloud Settings user interface and not within Sugar.

Updates that are made in Cloud Settings are pushed to Sugar user records automatically via REST APIs and also at the time of each user's login. If you have customizations that write to Users module, these changes could be overwritten by SugarIdentity services.

At this time, the following Users module fields are owned by SugarIdentity services and should only be updated via new Cloud Settings user interface.

  • first_name
  • last_name
  • address_street
  • address_city
  • address_state
  • address_postalcode
  • address_country
  • email_addresses
  • phone_work
  • title
  • department
  • status
  • is_admin
  • preferred_language
  • user_name

Custom fields on the Users module are not overwritten.

What are changes when authenticating via SugarIdentity?

Ultimately, SugarIdentity will provide more options for authentication and authorization. This will be the area of biggest impact for Sugar integrations.

Web Users

When an end user navigates to a Sugar URL and they are not yet logged in they will be redirected to a login service. This login service will have a different URL than their Sugar instance. However, once logged in they will be redirected back to their Sugar instance.

REST API integrations

If authenticating using REST API, the endpoint behavior is essentially unchanged. What has changed is the format for OAuth access and refresh tokens. Instead of using UUIDs, SugarIdentity uses encrypted tokens that are base64 encoded. If you are storing access or refresh tokens, they can now be up to 255 characters long. However, there is no hard limit on their size and they may get longer over time.



What functionality or customizations are not supported when using SugarIdentity?

Much of the responsibility for handling authentication is now delegated to SugarIdentity services. This means that many customizations to Sugar’s authentication mechanisms are no longer supported.

In particular, if you have created any custom SugarOAuth2Storage* classes then these will not work when SugarIdentity is used. The responsibility for generating and managing authentication tokens is now the responsibility of our Sugar cloud service instead of the Sugar instance.

If you feel like an essential authentication feature is missing in SugarIdentity services, then please let us know by filing an enhancement request via the Support Portal.

When using SAML Web SSO, should I move my integration users to my external identity provider?

Some customers that have wanted to use SAML with Sugar have held off until the SugarCRM Outlook Plug-In supported it. For Sugar customers using the new SugarIdentity service, the Outlook Plug-In will now support SAML Web SSO for the first time.

If you’re using integration users, we recommend leaving them as local user accounts instead of moving them to your SAML identity provider. The same advice applies when using LDAP an external identity provider too. SAML Web SSO isn’t well suited for REST API integrations since it requires credentials to be entered into a browser which makes automated authentication challenging. Your SAML or LDAP identity provider should only be responsible for managing employee access to Sugar.

This is also a use case where Service Accounts will come into play. Service Accounts will allow for the separation of responsibility between regular user accounts and services accessing Sugar data for integration purposes. This is a feature we are planning to implement in the future.

  • Matt Marum

    How do you request an OAUTH token for an Integration for a particular user?

    In most apps, the user is taken to a page that says something like let my app use your account. You’ll be sharing xyz. You can revoke access anytime.

    How do we perform this?

    the authorization process looks like this

  • This is typically accomplished using 3-legged OAuth. This flow allows a user to delegate access to their data to a 3rd party application or service. SugarIdentity implements 3-legged OAuth which is actually the mechanism that's used to allow OPI to work with SAML single sign on.

    In the past, OPI would store the user's Sugar username and password for doing a login with a 2 legged (client/server) OAuth. This is fine when you want to login to Sugar directly but fails when you need to login via a SAML browser window. This is why OPI could not support SAML SSO.

    With SugarIdentity, when a login is first initiated a window pops up that points to the Sugar login service. When SAML is configured, then this login screen will be the external identity provider (ex. ADFS or Okta). The user enters their credentials directly with the IdP and then they see a SugarIdentity consent screen to authorize the Sugar Outlook Plug-In (OPI) to access their CRM data on the user's behalf. Once that consent is collected the window closes and OPI is passed access and refresh tokens for the user. This new 3-legged OAuth flow is what allows for SAML to work with OPI.

  • Hello,

    May be you can explain for all people how you solve that in mobile app with SugarIdentity and why this same approach is not possible in OPI ?

Comment Children
  • Hi Cedric,

    I believe the mobile team had implemented a work around to get SSO working.

    One of the benefits of SugarIdentity was to centralize authentication logic. Instead of having every individual client implement SSO in their own way, we now have one implementation of SSO which will be used by any app or service that integrates with SugarIdentity. We knew we needed SugarIdentity for other reasons so we decided to focus on that instead of work arounds.