Single Sign-On for SugarCRM Through a SAML-Based Integration of OpenSSO and simpleSAMLphp

Print-friendly Version

OpenSSO, Sun's open-source Web access management project, offers capabilities for access management, secure Web services, and federation in a single Java distribution. simpleSAMLphp is a native PHP application for federation that works with several federation protocols and authentication mechanisms. It can act as a service provider (SP) or an identity provider (IdP).

This article describes the process for a Security Assertion Markup Language (SAML)-based single sign-on (SSO) integration between a Java language-based IdP and a PHP-based SP, that is, OpenSSO and simpleSAMLphp, respectively. The latter serves as the front end for the target, SugarCRM, a popular, free and open-source, PHP-based application for customer relationship management (CRM).

In the past year, the popularity of software-as-a-service (SaaS) products has led to ever-increasing demands for CRM software such as SugarCRM. However, since SaaS applications are hosted outside the firewall, the absence of SSO results in a time-consuming chore for Web access, what with multiple login IDs and passwords.

Consider this scenario: SmallComputerBiz, a company of 30 employees, sells computer-related products, service, and customer support to small or home offices and small- to medium-sized businesses. On the company's intranet is a set of Web applications for case management, service contract management, corporate calendaring, corporate directory, and such. They are all integrated into the corporate portal and are SSO-enabled and access-protected through OpenSSO.

In its quest to explore new business opportunities, to become better acquainted with its customers, and to more closely track its sales performance, SmallComputerBiz has purchased SugarCRM hosting licenses for several sales employees. The hosting option eliminates the need for employees to install, patch, and maintain the software themselves.

As an enhancement, SmallComputerBiz would like to extend SSO and access management to include the external SugarCRM resource. The sections that follow describe the related procedure.

The setup is on a single VirtualBox instance of Windows XP SP3 that runs on an OpenSolaris host. To simulate SAML-based cross-domain SSO on a single host, the C:\WINDOWS\system32\drivers\etc\hosts file contains this line:

127.0.0.1 localhost smallcomputerbiz.com bestsugarhosting.com

The line points to two domains (local loopback):

• smallcomputerbiz.com, the IdP, for use by OpenSSO and GlassFish application server
• bestsugarhosting.com, the SP, for use by SugarCRM and simpleSAMLphp

The integration transmits SAML protocol messages with the SAML 2 HTTP Redirect binding. In a federated environment, a trust relationship is required between the SP, in this case, bestsugarhosting.com, the SugarCRM hosting provider; and the IdP, in this case, smallcomputerbiz.com. The latter takes advantage of the SugarCRM services for its corporate hosted applications. In essence, SAML technology enables SSO between the corporate network and the SugarCRM-hosted application.

Figure 1 illustrates the message exchanges among the user agent (the browser), the SP, and IdP.

Figure 1: Message Exchanges Among the User Agent, the SP, and the IdP

Here is the process flow:

1. From the browser, the user tries to access the SugarCRM site hosted on bestsugarhosting.com (the SP).
   
   
2. If the user has not yet been authenticated, the SP responds to the browser (user agent) with a SAML authentication request encoded in the HTTP response's Location header with the HTTP status set to 302. The browser then delivers the request by issuing an HTTP GET request to smallcomputerbiz.com (the IdP).
   
   If authentication has already occurred, the SP grants the user access to the SugarCRM default page.
   
   
3. The IdP authenticates the user on the login screen and validates the user's access privileges.
   
   
4. The IdP returns to the browser a SAML response as a form to be sent by HTTP POST to the SP.
   
   
5. The SP analyzes the assertion and grants the user access to the SugarCRM default page.

Be sure you've installed the following software for the integration:

Software	URL
GlassFish v2 UR2 Final Build	https://GlassFish.dev.java.net/downloads/v2ur2-b04.html
SugarCRM Community Edition	http://www.sugarcrm.com/crm/download/sugar-suite.html Click Download Wizard, select Sugar Community Edition, and click Next. Select New and click Next. Select Windows and click Next. Select No in response to the question "Do you have the following software installed on your platform?" and click Next. Click FastStack Windows Installer for 5.0.0g with MySQL to download.
OpenSSO Enterprise 8.0	https://opensso.dev.java.net/public/use/
simpleSAMLphp version 1.3	http://code.google.com/p/simplesamlphp/downloads/list
OpenSolaris 2008.05	http://opensolaris.org/os/downloads/
VirtualBox 2.0.4	http://www.virtualbox.org/wiki/Downloads

This section describes how to install OpenSSO on GlassFish application server, the SugarCRM open-source pack, and simpleSAMLphp.

Installing OpenSSO
To install OpenSSO, follow the steps in the article Deploying OpenSSO on GlassFish Application Server.

Installing SugarCRM Open-Source Pack
Follow the steps below. Note that the directory values and such serve as examples only. Change them, as appropriate, to match your environment settings and system landscape.

1. Run the installer. Figure 2 shows the welcome screen.
   
   
   

   Figure 2: SugarCRM Installer: Welcome Screen
    
   
   
2. Perform the appropriate steps on the screens that follow, as described in this table:
   
   

   Screen	Step
   License Agreement	Click Accept.
   Installation Directory	Type C:\sugarcrm-5.0.0g.
   Select Components	Select sugarcrm and phpmyadmin.
   Install Type	Select custom install.
   System Name	Type bestsugarhosting.com.
   Base URL	Type http://bestsugarhosting.com/sugarcrm.
   Admin Password	Type the administrator password of your choice.
   Demo Data	Select Yes.
   Statistics and Updates	Select No for 1) and Yes for 2).
   Application ID	Select No.
   Local Setting	Retain the default values.
   Install as a Service	Select Yes.
   Select Webserver Port	Type 8080.
   Select SSL Port	Type 4433.
   Web Server Domain	Type bestsugarhosting.com.
   MySQL Credentials	Type a root password of your choice for the database.
   phpMyAdmin Password	Type a new password.

    
   

   Afterwards, test the installation by going to the appropriate location and logging in with the admin password. Figure 3 shows the default home page that is displayed.

   

   Figure 3: SugarCRM Admin Home Page
    
   

Installing simpleSAMLphp
To install simpleSAMLphp:

1. Unzip the simplesamlphp_1_1.zip file to the C:\sugarcrm-5.0.0g\htdocs directory.
   
   
2. Create the local configuration files. Type:
   
   

   C:\>cd sugarcrm-5.0.0g\htdocs\simplesamlphp_1_3 C:\sugarcrm-5.0.0g\htdocs\simplesamlphp_1_3>copy config-templ\*.php config\ C:\sugarcrm-5.0.0g\htdocs\simplesamlphp_1_3>copy metadata-templates\*.php metadata\

    
   
3. Edit the Apache configuration file, httpd.conf, at C:\sugarcrm-5.0.0g\apache2\conf and add the following VirtualHost code at line 1067:
   
   

   # ServerName dummy-host.example.com # ErrorLog logs/dummy-host.example.com-error_log # CustomLog logs/dummy-host.example.com-access_log common #</VirtualHost> ###### Start here ###### <VirtualHost *> DocumentRoot "C:\sugarcrm-5.0.0g\htdocs" ServerName bestsugarhosting.com Alias /simplesaml "C:\sugarcrm-5.0.0g\htdocs\simplesamlphp_1_3\www" </VirtualHost> ###### End here #####

    
   
4. Restart the Apache server with the sugarctl.sh script. Type:
   
   C:\>cd "Program Files\sugarcrm-5.0.0g\bin"
C:\Program Files\sugarcrm-5.0.0g\bin>allctl.bat restart
   

Afterwards, verify that the installation is successful by going to http://bestsugarhosting.com:8080/simplesaml/. Figure 4 shows the installation page that's displayed.

Figure 4: simpleSAMLphp Installation Page

Next, configure OpenSSO and simpleSAMLphp.

Configuring OpenSSO
To configure OpenSSO as an IdP, create a hosted IdP and then a remote SP on the server.

Creating a Hosted IdP
To create a hosted IdP:

1. Go to http://smallcomputerbiz.com:8080/opensso and log in as admin.
   
   
2. Click the Common Tasks tab and then select Create Hosted Identity Provider.
   
   The page for creating a SAMLv2 IdP is displayed.
   
   
3. Define the settings as shown in Figure 5.
   
   
   

   Figure 5: Creation of a SAMLv2 IdP
    
   
   
4. Click Configure (top right-hand corner).
   

Creating a Remote SP
To create a remote SP:

1. Click the Common Tasks tab and then select Register Remote Service Provider.
   
   The page for creating a SAMLv2 remote SP is displayed.
   
   
2. Define the settings as shown in Figure 6. In the URL field, type http://bestsugarhosting.com:8080/simplesaml/saml2/sp/metadata.php.
   
   
   

   Figure 6: Creation of a SAMLv2 Remote SP
    
   
   
3. Click Configure.
   
   
4. Click Federation and then Entity Provider. Select the SP (http://bestsugarhosting.com:8080/simplesaml/saml2/sp/metadata.php) and, under NameID Format, define the value for Current Values: urn:oasis:names:tc:SAML:2.0:nameid-format:transient. See Figure 7.
   
   
   

   Figure 7: Definition of NameID Format
    
   

Configuring simpleSAMLphp
To configure simpleSAMLphp, set the SAML 2.0 IdP remote metadata and the default SAML 2.0 IdP.

Note: You need not configure the metadata for the SAML 2.0 SP. Simply retain the default values in the saml20-sp-hosted.php file.

Configuring the SAML 2.0 IdP Remote Metadata
To configure the SAML 2.0 IdP remote metadata:

1. Add the following metadata at the end of the configuration file, saml20-idp-remote.php:
   
   

   /* * Metadata for smallcomputerbiz.com(OpenSSO-based IdP). */ $metadata['http://smallcomputerbiz.com:8080/opensso'] = array( 'name' =>'idp', 'description' =>'OpenSSO based IdP on smallcomputerbiz.com', 'SingleSignOnService' =>'http://smallcomputerbiz.com:8080/opensso/SSORedirect/metaAlias/idp', 'SingleLogoutService' =>'http:/smallcomputerbiz.com:8080/opensso/IDPSloRedirect/metaAlias/idp', 'certFingerprint' =>'DE:F1:8D:BE:D5:47:CD:F3:D5:2B:62:7F:41:63:7C:44:30:45:FE:33', ); ?>

    
   The metadata in this file represents the SAML 2.0 IdPs that the SP trusts to authenticate users of the service.
   
   
2. Collect the SHA1 Fingerprint of the IdP signing key. Here are the commands on the IdP side and the output:
   
   

   C:\Documents and Settings\office\opensso\opensso>>eytool -list -keystore keystore.jks -v Enter keystore password: changeit Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry Alias name: test Creation date: Jul 17, 2008 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=test, OU=OpenSSO, O=Sun, L=Santa Clara, ST=California, C=US Issuer: CN=test, OU=OpenSSO, O=Sun, L=Santa Clara, ST=California, C=US Serial number: 478d074b Valid from: Wed Jan 16 00:49:39 IST 2008 until: Sat Jan 13 00:49:39 IST 2018 Certificate fingerprints: MD5: 8D:89:26:BA:5C:04:D8:CC:D0:1B:85:50:2E:38:14:EF SHA1: DE:F1:8D:BE:D5:47:CD:F3:D5:2B:62:7F:41:63:7C:44:30:45:FE:33 Signature algorithm name: MD5withRSA Version: 1 ******************************************* *******************************************

    
   keystore.jks holds the self-signed certificate test (alias). The password for both keystore and key is changeit. In an earlier step, you selected the test self-signed certificate as the signing key for the assertions issued by the IdP.

Setting the Default SAML 2.0 IdP
The global configuration file, config.php, holds a parameter for the default IdP. Set the parameter as follows:

'default-saml20-idp' => 'http://smallcomputerbiz.com:8080/opensso',

Testing
Now test the configuration through the IdP:

1. Go to http://bestsugarhosting.com:8080/simplesaml.
   
   
2. Under Useful Links in your installation, click the SAML 2.0 SP example and test the login through the IdP link. Figure 8 shows the demo example.
   
   
   

   Figure 8: Demo Example of a SAML 2.0 SP
    
   
   This page automatically takes you to the IdP for authentication. After authentication, the protected simpleSAMLphp page is displayed along with the attributes passed by the IdP, in this case, the logged-in user name.

Making SugarCRM SSO-Aware
To ensure that SugarCRM is aware of the SSO implementation, update three SugarCRM PHP files: index.php, Login.php, and Logout.php.

1. Update index.php at C:\sugarcrm-5.0.0g\htdocs\sugarcrm. Below these comments—
   
   

   * technical reasons, the Appropriate Legal Notices must display the words * "Powered by SugarCRM". ********************************************************************************/

    
   —insert the following code to add the simpleSAMLphp classes to the classpath:
   
   

   /* Add the SimpleSAMLphp classes to the classpath*/ require_once('C:\sugarcrm-5.0.0g\htdocs\simplesamlphp_1_3\www\_include.php'); require_once('SimpleSAML/Utilities.php'); require_once('SimpleSAML/Session.php'); require_once('SimpleSAML/XHTML/Template.php');

    
   
2. Update Login.php at C:\sugarcrm-5.0.0g\htdocs\sugarcrm\modules\Users. Below these comments—
   
   

   * Portions created by SugarCRM are Copyright (C) SugarCRM, Inc. * All Rights Reserved. * Contributor(s): ______________________________________ ******************************************************************************* */

    
   —replace all the existing lines with the following PHP code:
   
   

   /*This snippet initiates the SAML2 SSO process and, when successful, it logs in to SugarCRM with the authenticated user */ $config = SimpleSAML_Configuration::getInstance(); $session = SimpleSAML_Session::getInstance(); /* Check if valid local session exists. */ if (!isset($session) || !$session->isValid('saml2') ) { SimpleSAML_Utilities::redirect( '/' . $config->getBaseURL() . 'saml2/sp/initSSO.php', array('RelayState' => SimpleSAML_Utilities::selfURLhost().'/sugarcrm/ index.php?action=Authenticate&module=Users') ); } $user_name = $session->getAttribute('UserName'); $authenticated = $session->isAuthenticated(); if($authenticated) { $query = "SELECT * from users where user_name='$user_name[0]' and deleted=0"; $result =$GLOBALS['db']->limitQuery($query,0,1,false); $row = $GLOBALS['db']->fetchByAssoc($result); if (!empty ($row)) { $_SESSION['authenticated_user_id'] = $row['id']; $_SESSION['login_user_name'] = $user_name[0]; $_REQUEST['user_password'] = $user_hash = strtolower(md5($user_name[0]));; } $action = 'Authenticate'; $module = 'Users'; $_REQUEST['action'] = 'Authenticate'; $_REQUEST['module'] = 'Users'; $_REQUEST['return_module'] = 'Users'; $_REQUEST['action_module'] = 'Login'; session_register(); header('Location: index.php?action=Authenticate&module=Users'); exit; } ?>

    
   
3. Update Logout.php at C:\sugarcrm-5.0.0g\htdocs\sugarcrm\modules\Users. Below the comments, add the following code:
   
   

   /* This snippet initiates the SAML2 SLO process */ $config = SimpleSAML_Configuration::getInstance(); $session = SimpleSAML_Session::getInstance(); $isValid = $session->isValid(); if ($isValid) { SimpleSAML_Utilities::redirect( '/' . $config->getBaseURL() . 'saml2/sp/initSLO.php', array('RelayState' =>>SimpleSAML_Utilities::selfURL()) ); }

    
   

Finally, test with a user case:

1. Create a user in OpenSSO with a user name that matches one on the SugarCRM side (for example, admin). See Figure 9.
   
   
   

   Figure 9: Creation of admin User on OpenSSO
    
   
   
2. Log out of OpenSSO, restart the browser, and go to the SugarCRM deployment site.
   
   Instead of the SugarCRM default login screen, you're redirected to the OpenSSO login screen.
   
   
3. Type the name of the user you created in step 1, for example, admin, along with the password.
   
   
4. If login is successful, the user's SugarCRM default home page is displayed.
   
   
5. Log out.
   
   The sessions that are active on SugarCRM and on OpenSSO are invalidated.

This simpleSAMLphp-OpenSSO integration achieves seamless SAML-based SSO for SugarCRM. On a high level, it also demonstrates SAML-based SSO through OpenSSO and the Linux, Apache, MySQL, and PHP (LAMP) stack.

As a next step, you can create an authentication module of SugarCRM that incorporates SAML's Internet SSO logic. Give it a try!

Special thanks to Sun's Pat Patterson, federation architect, and Sidharth Mishra, technical product manager for identity management, for their prompt reviews of the draft and excellent comments. And much appreciation to the vibrant communities of SugarCRM, simpleSAMLphp, and OpenSSO for their responses to various technical queries.

• OpenSSO
  • Main page
  • Resource Center
  • Support: Sun OpenSSO Express
  
  
• simpleSAMLphp
  • Main page
  • Mailing list
  
  
• SugarCRM
  • Main page
  • Downloads
  • Forums
  
  
• SAML online community
  
  
• VirtualBox
  
  
• Sun developer services
  • Support
  • Training and certification