
                    CLAROLINE AUTHENTICATION SYSTEM
                    for Claroline 1.11

PRELIMINARY NOTES

    1. The external driver configuration is not the easiest feature of 
    Claroline. 
    If you need some more information or some help, don't hesitate to go to 
    http://forum.claroline.net and ask for it !

    2. This document doens't treat single-sign on authentication using CAS, 
    Shibboleth or any other Single-Sign On (SSO) system.

----

TABLE OF CONTENTS

    A. CLAROLINE AUTHENTICATION SYSTEM
        A.1. AUTHENTICATION SOURCES
        A.2. AUTHENTICATION DRIVERS
        A.3. AUTHENTICATION PROCESS
        A.4. ENABLING AUTHENTICATION DRIVERS
        A.5. DRIVER LOADING MECHANISMS
        A.6. WRITING A CUSTOM DRIVER
    B. AUTHENTICATION DRIVER CONFIGURATION

----

A. CLAROLINE AUTHENTICATION SYSTEM

    The Claroline authentication system allows Claroline to rely on external or 
    local systems concerning authentication and user profile management. It is 
    based on a collection of authentication drivers stored inside the 
    platform/conf/extauth folder.

    The authentication system is invoked by the Claroline authentication system 
    when a user try to connect to the platform.

    A.1. AUTHENTICATION SOURCES

    Each user accounts in Claroline has got an authentication source property in
    the user table (authSource fields). By default the authentication source is 
    'claroline' meaning that the platform will use the default authentication 
    driver based on the local database.

    Each authentication source correspond to an authentication driver, and each 
    driver must declare its authentication source in the its configuration file 
    (see below).

    The authentication source can be set in two ways :

    1. automatically when a user account is created by an authentication driver. 
        This is the normal behaviour.

    2. by manually changing the value of authSource in the database. This is 
        used for example to disable a user account by setting the authSource 
        field to 'disabled' or to change the authentication source of a user.

    A.2. AUTHENTICATION DRIVERS

    An authentication driver is represented by two elements :

    1. an authentication driver class which is written in PHP code and contains 
        the instruction needed to authenticate one user
    2. an authentication driver configuration file also in PHP code (see section 
        B below)

    One driver class can be used in several authentication driver configuration 
    files, but one driver configuration file uses to only one authentication 
    driver.

    The authentication source is linked to the driver configuration file (see 
    section B. below).

    Claroline provides two driver classes you can use directly : 
    
    - LdapAuthDriver for authentication using an external LDAP or OpenDirectory
        server
    - LocalDatabaseAuthDriver for authentication using the Claroline database 
        with another authentication source than the default 'claroline' source
    
    The PEAR-based PearAuthDriver authentication driver is not maintained 
    anymore by the claroline team and will disapear in a future release, which 
    means that a lot of old external authentication drivers will not work 
    anymore in Claroline. 

    The reason of this is an unsolvable security issue in the authentication 
    architecture itself which make it dangerous to use with multiple 
    authentication sources.
    
    If you are using PearAuthDriver for LDAP authentication, we provide a new 
    native LDAP driver since Claroline 1.9.5 which MUST be used instead of the 
    old one ! We strongly advise you to upgrade your LDAP driver to use the new 
    one given in example in inc/conf/extauth/ldap.conf.php

    A.3. AUTHENTICATION PROCESS

    The authentication sywtem will look at the database and search for a user 
    account matching the given username. 

    Two different subprocesses can happen :

    1. No record concerning this user are found into the Claroline system, so it 
    attempts to authenticate this user using the available authentication 
    drivers (see DRIVER LOADING MECHANISMS below). 
    If the user is found on the authentication source, Claroline creates the 
    user profile into its own user table and copy the user data provided by the 
    corresponding authentication source through the driver API and set the 
    authentication source name in the database to the authentication source 
    declared by the driver.

    2. A record record concerning this user is already stored into the Claroline 
    authentication system. Claroline will load the corresponding authentication 
    driver to check if this user account is still allowed to connect with this 
    password. 
    If the anthentication is successful, Claroline will also update the user 
    data stored into the database with the information provided by the 
    authentication source.

    NOTE: Both the account creation and the account information update from an 
    authentication source can be disbaled in the driver configuration 
    (see below).

    A.4. ENABLING AUTHENTICATION DRIVERS

    To use one an authentication driver

    1. Copy the driver configuration from claroline/inc/conf/extauth to 
        platform/conf/extauth directory.

    2. Open the driver configuration file into a text editor and adapt 
        the parameters to your  own context. Do not forget to enable it by 
        setting the 'enabled' option to TRUE (see section B. below).

    A.5. DRIVER LOADING MECHANISMS

    Since Claroline 1.11, the avalaible authentrication drivers can be loaded 
    in two different ways : 

    1. automatic drivers discovery based on the contents of the 
        platform/conf/extauth directory

    2. static loading using a driver list defined in the file 
        platform/conf/extauth/drivers.list that must contains one configuration 
        file by line. The authentication drivers will be loaded in the order 
        specified in the file. For example, a driver.list file containing

            ldap.conf.php
            joomla.conf.php

        will load first the ldap driver then the joomla driver
    
    In both case the driver configuration files must be located in the 
    platform/conf/extauth directory (see ENABLING AUTHENTIOCATION DRIVERS and
    section B. for details).

    A.6. WRITING A CUSTOM DRIVER
    
    To write your own authentication driver class, you can extend one of the 
    classes provided by Claroline (see claroline/inc/lid/auth) or implement the
    AuthDriver interface.

    Your custom authentication drivers can be put in the driver configuration 
    file itself. The claroline/inc/conf/extauth/alumni.conf.php shows an example 
    of a more advanced authentication driver definition and configuration.

    Another way is to put the file containing the driver in the 
    platform/conf/extauth/drivers folder of your platform. This driver file MUST
    be named after the name of the driver class in LOWERCASE and with the 
    '.drv.php' extension. 

    For example, if you have defined a new driver class 
    named MyCustomAuthDriver, the file must be named mycustomauthdriver.drv.php

B. AUTHENTICATION DRIVER CONFIGURATION

    The configuration options of an authentication driver are written in the 
    $driverConfig associative array, one option corresponding to one key of the 
    array.

    The available options are :

    1. $driverConfig['driver']: describes the properties of the driver. 
    This entry have several sub options :

        - 'enabled' : tell the kernel to use this driver or not
        - 'userRegistrationAllowed' : tell the kernel if the driver is allowed 
            to create a new user in Claroline
        - 'userUpdateAllowed' : tell the kernel if the driver is allowed to 
            update an existing user in Claroline
        - 'class' : the PHP class used for the driver. If you are only modifying 
            the parameters of an existing driver, do not edit this one. 
        - 'authSourceType' set the technical type of the of the external 
            authentication source (deprecated, only used for PEAR-based 
            authentication)
        - 'authSourceName' : set the authentication source corresponding to the 
            driver

    example:
        
        $driverConfig['driver'] = array(
            
            'enabled' => true,
            'userRegistrationAllowed' => true,
            'userUpdateAllowed' => true,
            'class' => 'LdapAuthDriver',
            'authSourceType' => 'LDAP',
            'authSourceName' => 'mycompanyldap'

        );

    2. $driverConfig['extAuthOptionList']: set the parameters needed to connect 
    to the external authentication source and the field to to retrieve in it.

    example :

        $driverConfig['extAuthOptionList'] = array(

            'url'      => 'ldap://server_address',
            'port'     => '636',
            'basedn'   => 'ou=personne,o=your organisation unit,c=domaine',
            'userattr' => 'uid',
            'useroc'   => 'person',
            'attributes' => array('sn', 'givenName', 'telephoneNumber','mail'),

        );

    3. $driverConfig['extAuthAttribNameList']: set how the data retrieved from 
    the external authentication source matches the Claroline data structure. The 
    keys are the Claroline attributes and the value are the authentication 
    external attributes.    

    example : 

        $driverConfig['extAuthAttribNameList'] = array (

            'lastname'     => 'sn',
            'firstname'    => 'givenName',
            'email'        => 'mail',
            'phoneNumber'  => 'telephoneNumber',
            'authSource'   => 'ldap'

        );

    4. $driverConfig['extAuthAttribTreatmentList']: set any optional 
    preliminary treatment to the data retrieved from the external authentication 
    source before committing it into Claroline. The keys are the concerned 
    Claroline attribute, and the values are the name of the function which make 
    the treatment. You can use standard PHP function or functions defined by 
    your own.

    example : 

        $driverConfig['extAuthAttribTreatmentList'] = array (

            'lastname'     => 'utf8_decode',
            'firstname'    => 'utf8_decode',
            'loginName'    => 'utf8_decode',
            'email'        => 'utf8_decode',
            'officialCode' => 'utf8_decode',
            'phoneNumber'  => 'utf8_decode',
            'status'       => 'treat_status_from_extauth_to_claroline'

        );

    5. $driverConfig['extAuthAttribToIgnore']: set the list of attributes from 
    the external authentication system to ignore when updating the data of a 
    user. This is mainly used to prevent an external authentication system to
    overwrite attributes set by the platform administrator.

    example : 

        $driverConfig['extAuthAttribToIgnore'] = array(
            'isCourseCreator'
        );

    6. $driverConfig['authProfileOptions']: define user profile options 
    specific for the user authenticated with this authentication source. 

    The available options are

    - 'courseRegistrationAllowed': true or false, if false the users cannot 
        enrol to courses by themselves
    - 'courseEnrolmentMode' : 'open', 'validation', 'close' (see course enrolment 
        options for details)
    - 'defaultCourseProfile' : the name of the profile to give the user when 
        registering to a course. The profile must exists in claroline (in 
        Administration > Right profile list)
    - 'editableProfileFields' : an array of profile fields that can be modified 
        by the users in their user account page

    Set the option to null to use the platform default behaviour.

    example : 

        $driverConfig['authProfileOptions'] = = array(
            'courseRegistrationAllowed' => true,
            'courseEnrolmentMode' => 'validation', 
            'defaultCourseProfile' => 'guest', 
            'editableProfileFields' => array('email') 
        );

    7. In addition, each driver can define a specific driver PHP class or one or 
    more specific functions to process the data retreived from the 
    authentication source.
