Single Sign-On (SSO)

Introduction

myDBR enables the use of an external server for user authentication. The Single Sign-On server must implement the Authentication protocol specified below, with no restrictions on its specific implementation. A secret token shared between the server and myDBR ensures the validity of requests originating from both entities. This secret token is defined in myDBR Environmental settings.

myDBR also offers SSO implementation for Google authentication.

Authentication Protocol

In this setup, SSO is selected as an authentication method in Environmental settings.

  1. A user visits the myDBR site for the first time
  2. A user is redirected to the SSO server URL (as specified in settings). In addition, myDBR adds the following three parameters to the URL:
    • url The URL to which the user should be redirected once login has been completed
    • token A random token which is used by the SSO server to calculate a verification hash
    • hash A hash value calculated as sha1(url + token + secret) so you can verify the call comes from myDBR. If the hash does not match, one can abort the process (other than myDBR made the call)
  3. The SSO server performs authentication of the user, e.g. by showing a login screen or determining the user information from an already logged in user
  4. The SSO server redirects the user to the URL provided by myDBR. In addition, the SSO server must add the following parameters to the URL:
    • user Login of the user
    • name Full name of the user
    • groups Optional list of groups the user belongs to separated by '|'
    • email Optional user's email address
    • telephone Optional user's telephone number
    • admin A flag 1 / 0 indicating if the user is an admin or not
    • extra1 Optional extra parameters (extra1, extra2, extra3...). Will be concatenated in hash calculation. extras = extra1+extra2+extra3.
    • hash A verification hash calculated as sha1( user + name + groups + email + telephone + admin + extras + token + secret )
  5. myDBR verifies the hash received from the SSO server and creates or updates the user information for the specified users
  6. The user is now logged in to myDBR

Extra Parameters

SSO authentication in myDBR allows you to pass on additional parameters. These extra parameters can include any information you want to include in the user's context via SSO, such as user organization or other relevant details from your application. These parameters will automatically become part of myDBR's context. To add an extra parameter:

  1. Add it to the SSO URL. The first extra parameter will be named as 'extra1'
  2. Add it to the SSO URL hash between admin and token
  3. Define the automatic parameter name that will be used in the parameter:
    $mydbr_defaults['automatic_parameters']['sso_extra1'] = 'in_SSO_OrganizationID';

if you have more than five extra parameters, increase the $mydbr_defaults['parameters']['max_sso_extra_parameters'] in

User's Groups

The authentication protocol contains optional parameter groups that can be used to define SSO user's groups separated by '|'. The parameter contains a list of groups the user belongs to. When logging in myDBR will do the following things:

  1. If a user's group does not exist in myDBR it will be added
  2. The user will be added to groups defined by the groups-parameter
  3. The user will be removed from any other group
  4. If the groups-parameter is empty, the user is removed from all groups

Example SSO Server

An example standalone SSO Server has been included in the user/sso/sso_example.php.

Debugging the SSO Protocol

If you have trouble implementing the SSO protocol, you can enable the debug option which will show more info when SSO authentication fails. To enable the debug add the following to : 

    $mydbr_defaults['single_sign_on']['debug_failed_login'] = true;

Local myDBR Login when SSO is Enabled

If SSO is set as a login method, you can still log in with myDBR login by adding &local=1 to the login URL. For example, if you have installed myDBR at localhost/mydbr you would log in locally using http://localhost/mydbr/index.php?a=login&local=1

To prevent users from logging in with the myDBR login when SSO is being used, remove unnecessary myDBR logins and secure the admin password.

Logout Process in SSO

When using SSO, both login and logout need to be done simultaneously from both the main application and in myDBR. You can make myDBR log out and redirect the user's browser to the desired location by defining the $mydbr_defaults['logout']['url'] variable in the .

If you need to define the redirect destination dynamically, you can use the 'url'-parameter in myDBR's logout-call (/mydbr/logout.php?url=https%3A%2F%2Fmyserver.com%2Fservice). In order to protect myDBR from open redirect vulnerability, the possible values of the 'url'-parameter needs to be defined in the $mydbr_defaults['logout']['allowed_redirect_urls_in_url_parameter'] array in the .

The third way of defining the redirect destination is to define an automatic parameter logout_url_redirect which will be used when the user logs out in case no url-parameter is passed to logout.php. This method can be used if the redirect destination depends varies.

To override myDBR logout link text and location in autologin and SSO, change the $mydbr_defaults['logout'] parameters.

Example for Integration With SugarCRM

The following example has been tested with SugarCRM CE 5.5 and makes the following assumptions:

  • myDBR is installed in /var/www/htdocs/mydbr and accessible from your web-browser via http://localhost/mydbr
  • SugarCRM is installed in /var/www/htdocs/sugar and accessible from your web-browser via http://localhost/sugar

Add the SSO Code to SugarCRM

  1. Create a new directory /var/www/htdocs/sugar/modules/mydbr
  2. Create a new file in that directory and name it controller.php
  3. Paste the following code to controller.php and save the file. 
    <?php
require_once('include/MVC/Controller/SugarController.php');

define( 'MYDBR_SECRET', 'secret-token-defined-in-mydbr-environmental-parameters');

class myDBRController extends SugarController 
{
        
    function action_login() 
    {
        global $current_user; 
        
        $role = new ACLRole();
        $roles = $role->getUserRoles( $current_user->id );
        
        $separator = '';
        $groups = '';
        foreach( $roles as $role ) {
            $groups .= $separator . $role;
            $separator = '|';
        }
        
        $user = $current_user->user_name;
        $name = $current_user->title;
        $token = $_REQUEST['token'];
        $url = $_REQUEST['mobile'];
        $hash = $_REQUEST['hash'];
        if ($hash!=sha1($url.$token.MYDBR_SECRET)) {
          die();
        }
        $hash = sha1( $user . $name . $groups . $token . MYDBR_SECRET );
        
        $url = $url . '?user=' . urlencode($user) . '&name=' . urlencode($name) . '&hash=' . $hash .'&groups=' . urlencode($groups);

        header('Location:' . $url);
        die();
    }
}

Configure myDBR for SugarCRM SSO

  1. Go to "Admin" -> "Environment Settings"
  2. In "Authentication" select "Single Sign-On"
  3. Add following line to mydbr/: 
    $mydbr_defaults['single_sign_on']['url_parameter'] = 'mobile'; // For SugarCRM 6.x which does not allow the default 'url' parameter
  4. In "Single Sign-On settings" add the following information
    • SSO secret token
    • SSO Server URLhttp://localhost/sugar/index.php?module=mydbr&action=login

myDBR is now accessible with-in SugarCRM. If you are logged in to SugarCRM and visit http://localhost/mydbr you will be automatically logged in to myDBR as well

Add myDBR Site to SugarCRM (optional)

  1. In SugarSRM go to "Admin"->"My Sites"
  2. Click "Add Site"
  3. Enter the following:
    • Name ... myDBR
    • Website ... http://localhost/mydbr
    • Type ... Global
  4. You can now access myDBR from the SugarCRM's "Others" tab

Google Authentication

The SSO's Google authentication allows authentication using Google login. Assuming your myDBR install location is https://yourserver/mydbr, to enable google login to do following:

  1. Choose Google login in myDBR → Admin Tools → Environment settings → Single Sign-On settings
  2. Create a Google API Console project and client ID https://developers.google.com/identity/sign-in/web/devconsole-project
  3. Copy the Client ID and Client secret to respective fields in myDBR → Admin Tools → Environment settings → Single Sign-On settings → Google
  4. Define an "Authorized redirect URIs" which will be a URL to https://yourserver/mydbr/lib/sso/google/
  5. In myDBR set the SSO Server URL to be: https://yourserver/mydbr/lib/sso/google/index.php
  6. By including the hosted domain of the users, you restrict sign-in to accounts at that domain. With an OEM license you can have multiple domains listed separated with comma.
  7. Wait for a moment to let Google setup to be effective and login using Google login

User Organization With SSO

myDBR has the ability, in the OEM version, to define user organization in SSO protocol. This allows report/folder privileges to be assigned per organization and use the same user groups among different organizations and to create an automatic parameter for user's organization ID.

The optional external organization ID is passed on in the SSO extra parameters. If the name for SSO's extra parameter (sso_extra*) matches the defined automatic parameter value for the $mydbr_defaults['organization']['external_id_automatic_parameter'], the passed value will be matched in SSO login against external_id-column in the mydbr_organizations-table and the matched organization id is updated to myDBR's user table.

The default name (defined in defaults.php) for organization ID parameter is in_SSO_OrganizationID. To make SSO to treat an extra parameter as organization ID define the extra parameter with same name in and pass the user's organization ID as extra paramerer in your SSO protocol implementation. 

$mydbr_defaults['automatic_parameters']['sso_extra1'] = 'in_SSO_OrganizationID';