Using a SSO in eZ Publish

This kind of tools is quite common on the web; Google or MSN use it (one authentication for all their applications). Of course, there are many ways to interface with a SSO, depending on the CMS or on the framework you use. eZ Publish, since version 3.8, allows to develop SSO Handlers in a form of a plugin to authentication system. With this article, I will try to show you how it works.

Developping a SSO Handler

The principle of this kind of handler is quite simple, as you just need to develop, in an extension, a PHP class implementing handleSSOLogin() method. Please note that I assume you know how to develop a basic eZ Publish extension. If it's not the case, you may refer to this excellent article.

Handler declaration

In the settings/ folder of your extension (I'll name it jvsso), make an override of site.ini for your siteaccess. You can also make this override directly under settings/, that will make your SSO handler available for very siteaccesses of your eZ Publish instance.

In your site.ini.append.php override, make the following declaration :

<?php /* #?ini charset="utf-8"?

[UserSettings]
ExtensionDirectory[]=jvsso
SingleSignOnHandlerArray[]=Lolart

*/
?>

Here we declare that jvsso extension must be taken into account by eZ Publish authentication system, and that this extension contains a SingleSignOnHandler, called Lolart. Please note that the SSO handler name is contained in an array, which means that it is possible to declare several ones, successively called until an authentication succeeds (if you are curious, take a look at eZUser class - kernel/classes/datatypes/ezuser/ezuser.php - around line 1150 if you want to see how eZ Publish make these calls).

PHP class development

In your extension folder, create a sso_handler/ folder. This folder is aimed to contain the PHP class we'll develop. The name of the PHP file and the name of the class must follow the following specifications :

• PHP file has to be named ez<handler_name_lowercase>ssohandler.php. It gives : ezlolartssohandler.php
• PHP class has to be named eZ<handler_name>SSOHandler, which gives eZLolartSSOHandler.

Our PHP class must at least implement handleSSOLogin() method. This method must return a valid eZ Publish user (eZUser object) or false if it fails.

<?php
    class eZLolartSSOHandler
    {
        public function __construct()
        {
         // Here you can make initialization stuffs for your handler
        }

        /**
         * Return a eZUser PHP object to be logged in eZ Publish
         * If authentication fails, just return false
         */
        public function handleSSOLogin()
        {
            $currentUser = false; // Default falue that we return if authentication fails.
            
            // Here you can do everything you need to identify your user (interface with SSO, search the SSO database...)
            // In all cases, you must return a valid eZ Publish user or false
            // User must be created if needed
            
            return $currentUser;
        }
    }

Et voilà ! Now we just have to activate our extension and clear our INI caches !

French translation of this article on the original author's blog.