SSO authentication on SugarCRM with SAML

Okta Login Screen
Okta login screen

Today I am going to guide you through the steps to get Sugar up and running in the easiest way possible with Okta, the SAML identity provider of choice for this article.

The business goals are:

  1. Centralise authentication. Less headaches when changing password and even when decommissioning users and no need to maintain local usernames and passwords
  2. Better user experience for application access, with Single Sign On between applications within the organisation

I will dig straight into the steps required to get the solution up and running. For more details on terminology and standards around SAML, feel free to have a look at the following articles in wikipedia: idPSAML, SSO, X.509 to start with.

 

To proceed further you would need the followings:

  1. A public facing Sugar system (currently using version 7.7.2.0 of any flavour)
  2. An Okta account
  3. Sugar administration knowledge (eg: user creation, teams and roles management etc.)

Okta

Sugar app

To add the Sugar app in Okta, navigate to Applications -> Add Application and search for “Sugar”.

 

Okta Sugar App
Okta add Sugar app

 

Once the Sugar app is added to Okta, follow the prompts to select the Sugar system’s url and the remaining settings on Okta’s side. For the Application username format use “Email”. Sugar currently matches on email addresses only, from Okta to Sugar.

 

Okta Sugar App Settings
Okta Sugar app settings

 

Click on “View Setup Instructions” to get to your system’s settings help page that would give you the correct information to setup Sugar with, such as “Login URL”, “SLO URL” and  the “X.509 Certificate”.

 

Okta Sample Sugar Settings
Okta’s sample Sugar settings setup page from a developer account

 

Provision sample user

You will need to create the users and set the unique email addresses and passwords into Okta. Once completed, open the users and assign the Sugar app to grant login permissions.

 

Sugar App Permissions to User
Add the Sugar app to a user’s profile

Sugar

Configure system for SSO

On the Sugar side you will have to set the Okta idP SAML parameters into the “Password Management” section on the “Admin” area.

Password Management in Sugar
Password management in Sugar

 

On the Sugar “Password Management”, enter the information provided by Okta within the “View Setup Instructions” when logged in as the Okta administrator.

 

Configure SSO in Sugar
Configure SAML in Sugar

 

I recommend to disable the automated user provisioning by adding on config_override.php the following configuration option:

$sugar_config['SAML_provisionUser'] = false;

The Sugar administrator(s) can decide which permissions and visibility are assigned to the user before he/she is allowed into the application, by enforcing manual user creation.

Provision sample user

When creating users that will access the system via SSO, you should make sure they are setup correctly to only be able to login to Sugar via SSO and not with locally stored credentials, by setting the option “SAMLAuthenticate Only”.

 

User Provisioning in Sugar
User provisioning in Sugar

 

Sugar SamlAuthenticate Only User
“SAMLAuthenticate Only” user option

 

After user creation, make sure to assign the correct Roles and Teams to the user, to grant the correct permissions to system’s functionality and visibility to the relevant records.

Testing

After setting up Okta’s Sugar app, adding Sugar’s Okta settings and provisioning the users on both sides, it is time to verify that everything is working as expected.

On the Sugar side when the SAML authentication is enabled, the login screen looks different. It provides either the functionality to “Log In” via SSO, or the standard login form by clicking on “Show log in form”. The form can be used if some users have local credentials provisioned and do not have the “SAMLAuthenticate Only” option enabled.

 

SSO Sugar Login Screen
SAML SSO Sugar login screen

 

When the button “Log In” is pressed, Okta will either provide us with the Okta login screen, or authenticate us to Sugar if we have a SAML SSO session already active.

Additional notes

  • It is important to note that the only matching that happens between Okta and Sugar is via the user’s email address on both systems. That’s how a user is identified on this article
  • If you do need to quickly make sure that all Sugar users can only login via SAML, you can run a SQL query to set the flag external_auth_only to 1 on the Users module (users SQL table) for the relevant records
  • It is possible to tweak SAML configuration variables in Sugar by copying the core file located in modules/Users/authentication/SAMLAuthenticate/settings.php to the custom file custom/modules/Users/authentication/SAMLAuthenticate/settings.php and complete the required changes

Sugar Pro Tip

It is possible that a Sugar Administrator incorrectly setup a regular user, by forgetting to assign it to at least one Role. By default in Sugar, users who are not assigned to a Role can access and perform actions in any enabled module. To make sure there is a fallback process within your organisation, in case of Sugar Administrator provisioning error, I highly encourage you to implement ways to prevent standard unrestricted users from accessing your system.

I’ve prepared some sample code that you can take some hints from, and adapt it to your unique scenarios. The code implements an after_login logic hook that invalidates the login for any standard user without at least a Role. The sample code purposely does not apply to Administrators as Roles do not apply to them in any case. The code below works on the current version 7.7.2.0.

 

6 thoughts on “SSO authentication on SugarCRM with SAML

  1. Hi Enrico.
    I´m looking for a way to assign a default role with a after_save logic hook. Is there any way you could show such a code?
    Thanks so much,
    KGM

  2. Hi Kristján,

    I will give you some hints that can help below.

    I have completed that in the past, by extending the authentication class and pointing the Sugar config_override.php relevant parameter to the custom class ($sugar_config[‘authenticationClass’]).
    That would give you the additional flexibility you might need so that you can programmatically assign the correct role based on your business’ logic

    Alternatively you should be able to leverage the before_login logic hook to assign a default role with limited privileges (but I have not tested it)

  3. Hi Enrico,

    This is a great article, thanks for all the time and effort you put into it.

    We are trying to get SSO working with Sugar, regardless of the provider, we have looked at SAASPASS, MiniOrange, and OKTA, but we are having a problem with Sugar Outlook plugin. There doesn’t seem to be a way, at least accoring to Sugar Support, to use anything other than a basic username and password with the plugin.

    Do you know if there is a way around this?

    Thanks
    Dan

  4. Hi Daniel,

    Thank you for your kind words!
    You are correct, right now it is not possible to use SSO with SugarCRM’s Outlook plugin.

    You could try to customise (as in extend) the authentication class and see if it is possible to determine when a user logs in from Outlook plugin.
    If that’s possible, you could then code a different authentication mechanism, for example leveraging credentials stored on an LDAP repository, so that you do not have to maintain locally stored credentials.

    Hope it helps

Leave a Comment