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:
- Centralise authentication. Less headaches when changing password and even when decommissioning users and no need to maintain local usernames and passwords
- 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: idP, SAML, SSO, X.509 to start with.
To proceed further you would need the followings:
- A public facing Sugar system (currently using version 220.127.116.11 of any flavour)
- An Okta account
- Sugar administration knowledge (eg: user creation, teams and roles management etc.)
To add the Sugar app in Okta, navigate to Applications -> Add Application and search for “Sugar”.
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.
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”.
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.
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.
On the Sugar “Password Management”, enter the information provided by Okta within the “View Setup Instructions” when logged in as the Okta administrator.
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”.
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.
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.
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.
- 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 18.104.22.168.
6 thoughts on “SSO authentication on SugarCRM with SAML”
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,
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)
Thanks Enrico and happy new year :)
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?
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
I just completed a sample customisation where SSO/SAML from the UI is paired with LDAP authentication for Outlook plugin.
You can find the code on this public github repository: https://github.com/esimonetti/SugarSAMLOpiLDAP