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: idP, SAML, 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”.

 

 

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.

 

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.

 

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.

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.

 

 

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.