====== Authentication Plugins ======

DokuWiki's authentication system is highly modular and can, generally speaking, authenticate using anything that is accessible from PHP. Check the [[plugintype>128#extension__table|list of Auth Plugins]] to see what is already available. Auth Plugins can be installed via the [[plugin:Extension|Extension Manager]].

Authentication plugins provide multiple tasks:

  - authenticate the current user, eg. check some password, trust a cookie or similar
  - provide user information on any user, eg. get the name, email address, and group memberships
  - provide mechanisms to manage users, eg. create new users, change profile data


===== Synopsis =====

Please refer to [[devel:plugins]] and [[plugin file structure]] for general info for plugin development. Best use the [[plugin:dev|dev plugin]] to get started.

Your new class needs to follow the general naming scheme for plugins and inherit from [[xref>dokuwiki\Extension\AuthPlugin]].

Eg. for a plugin ''example'', the class name would be ''auth_plugin_example'' defined in ''lib/plugins/example/auth.php''.

Below, the most important methods when writing an auth plugin are described. Refer to [[devel:common plugin functions]] for inherited functions available to all plugins and check your IDE for additional possible overrides.


===== Initialization and Capabilities =====

Your plugin needs to signal that it is ready to use to DokuWiki's authentication sub system.

This is done in the plugin's constructor. You can use it check that configuration is complete, database connections work, etc. If everything is okay, you need to set the [[xref>AuthPlugin::$success|$success]] property to ''true''.

You also need to signal what functionality your plugin provides. For example with some backends it might not be possible to change user names while others have no way to log out after logging in. This is done by setting the different flags in the [[xref>AuthPlugin::$cando|$cando]] property. The more flags you enable here, the more methods you need to implement as described below.

<code php>
public function __construct()
{
    parent::__construct();

    $this->cando['modName'] = true;
    $this->cando['modMail'] = true;

    $this->success = true;
}
</code>


Here is a list of keys in ''$cando'' and their meaning:

  * ''addUser''     -- can Users be created? 
  * ''delUser''     -- can Users be deleted? 
  * ''modLogin''    -- can login names be changed? 
  * ''modPass''     -- can passwords be changed? 
  * ''modName''     -- can real names be changed? 
  * ''modMail''     -- can emails be changed? 
  * ''modGroups''   -- can groups be changed? 
  * ''getUsers''    -- can a (filtered) list of users be retrieved? 
  * ''getUserCount'' -- can the number of users be retrieved? 
  * ''getGroups''   -- can a list of available groups be retrieved?
  * ''external''    -- does the module do external auth checking?
  * ''logout''      -- can the user logout again? (eg. not possible with HTTP auth)

===== Authentication =====

There are two distinct ways of how your authentication plugin can authenticate the current user:

  - Let DokuWiki do most of the work and only do password checking in your plugin
  - Implement the authentication yourself, for example when trusting a 3rd party cookie

==== checkPass ====

The first method is the default. It requires you to implement the [[xref>AuthPlugin::checkPass()|checkPass()]] method. This function need to check if the given userid ''$user'' exists and the given plaintext password ''$pass'' is correct.

<code php>
public function checkPass($user, $pass)
{
    // obviously implement a real check here
    if($user == 'andi' && $pass='secret') {
        return true;
    }
    return false;
}
</code>

==== trustExternal ====


The second option is to implement the [[xref>AuthPlugin::trustExternal()|trustExternal()]] method. Be sure to also enable the ''trustExternal'' flag in the ''canDo'' array.

The trustExternal() method completely replaces the default [[xref>auth_login()]] function from ''inc/auth.php'', so might read a bit into its sources.

The method needs to set a few DokuWiki internal variables to create a logged in state. Namely ''$USERINFO'', ''$_SERVER['REMOTE_USER']'' and $_SESSION[DOKU_COOKIE]['auth'] infos.


The implementation depends very much on your backend, here are some often used parts indicated as example. Look also for other implementations, when it doesn't fit your requirements.

<code php>
function trustExternal($user, $pass, $sticky=false) {
    global $USERINFO;
    global $lang;
    
    // someone used the login form
    if(!empty($user)){
        //situation: there are user credentials, lets check them
        if( ...try to authenticate against your backend...)
            
            // here you can handle additional post login actions 
            // for your backend
            
        }else{
            //invalid credentials - log off
            msg($lang['badlogin'],-1);
            auth_logoff(); // needs implementation of logOff() method
            return false;
        }
    }

    //situation: no login form used or logged in successful 
    

    // check where if there is a logged in user e.g from session,
    // $_SERVER or what your auth backend supplies...

    if( ...check here if there is a logged in user...) {

        $USERINFO['name'] = string
        $USERINFO['mail'] = string
        $USERINFO['grps'] = array()
    
        $_SERVER['REMOTE_USER']                = $user; //userid
        $_SESSION[DOKU_COOKIE]['auth']['user'] = $user; //userid
        $_SESSION[DOKU_COOKIE]['auth']['info'] = $USERINFO;
        
        return true;
    }else{
        //when needed, logoff explicitly.
    }
</code>

In theory you can create an auth plugin that only implements ''trustExternal'' however, it is strongly recommended to have ''getUserData()'' so DokuWiki can display your users nicely and ''logoff()'' to permit DokuWiki to communicate the logoff to your backend.


===== Get User Information =====

==== getUserData ====

DokuWiki will need to query user information for the currently logged in user (if not supplied in ''trustExternal'') but also for other users. The latter happens for example when [[:subscription|Email Subscriptions]] are handled or full user names are to be displayed.

User information is requested from your plugin via the [[xref>AuthPlugin::getUserData()|getUserData()]] method. 


The method should return an array with at least the full name and email address for the given ''$user''. If ''$requireGroups'' is true, the user's groups should be returned as well. Return false if the given user can't be found.

<code php>
public function getUserData($user, $requireGroups = true)
{
    // obviously implement real user data retrieval here
    if ($user == 'andi') {
        return [
           'name' => 'Andreas Gohr',
           'mail' => 'andi@splitbrain.org',
           'grps' => ['user', 'admin']
        ];
    }

    return false;
}
</code>

==== retrieveUsers ====

optional, set ''getUsers'' capability

The [[xref>AuthPlugin::retrieveUsers()|retrieveUsers()]] method is used to retrieve a list of users matching a given criteria. It is used for example in the [[plugin:usermanager]] Plugin.

FIXME explain filter syntax 

==== getUserCount ====

optional, set ''getUserCount'' capability

The [[xref>AuthPlugin::getUserCount()|getUserCount]] method returns the number of users matching certain filter criteria. Used for pagination in the [[plugin:usermanager]] Plugin. (Needed when retrieveUsers() is implemented)


==== retrieveGroups ====

optional, set ''getGroups'' capability

The [[xref>AuthPlugin::retrieveGroups|retrieveGroups]] method returns a list of all available groups.



===== User Management =====

==== createUser ====

optional, set ''addUSer'' capability

The [[xref>AuthPlugin::createUser()|createUser()]] method creates a user with the provided data. Returns false, when user already exists, null on error and true when successful.

==== modifyUser ====

optional, set ''modLogin'', ''modPass'', ''modName'', ''modMail'', ''modGroups'' capabilities

The [[xref>AuthPlugin::modifyUser()|modifyUser()]] method modifies a user's data. You can expect to only receive data as per set capabilities.

==== deleteUsers ====

optional, set ''delUser'' capability

The [[xref>AuthPlugin::deleteUsers()|deleteUsers()]] method deletes one or more users.

==== addGroup ====

optional

The [[xref>AuthPlugin::addGroup()|addGroup()]] method creates a new group. This only needs to be implemented if a group needs to be created before users can be assigned to it.


===== Utility Methods =====

==== logOff ====

optional, set ''logout'' capability

The [[xref>AuthPlugin::logOff|logOff()]] method is run in addition to the usual logoff. It is useful with [[#trustExternal|trustExternal()]] to initiate actions for the external backend e.g. use it to clear cookies or similar actions. 

==== isCaseSensitive ====

When your backend is caseinsensitive, implement [[xref>AuthPlugin::isCaseSensitive()|isCaseSensitive()]] and return false.

==== cleanUser ====

optional

The [[xref>AuthPlugin::cleanUser()|cleanUser()]] method is applied when a username is given to and returned from the backend. Can be used to enforce username restrictions.

==== cleanGroup ====

optional

The [[xref>AuthPlugin::cleanGroup()|cleanGroup()]] method is applied when a group name is given to and returned from the backend. Can be used to enforce group name restrictions. 

Groupnames are passed without a leading ''@'' here.

==== useSessionCache ====

optional

DokuWiki caches user info for a timespan. The [[xref>AuthPlugin::useSessionCache()|useSessionCache()]] method can be used to influence the expiration of this caching.




===== Notes =====

====Start session customization====


Dokuwiki starts (in [[xref>inc/init.php]]) a session prior to using the authentication plugin. If your framework uses specific session settings, you can define before your own settings in the file ''conf/local.protected.php''. You need to create it when non-existing. In this ''conf/local.protected.php'' you can supply one or more of these defines:
  * ''DOKU_SESSION_NAME'' 
  * ''DOKU_SESSION_LIFETIME'' 
  * ''DOKU_SESSION_PATH''
  * ''DOKU_SESSION_DOMAIN''
The defines correspond to the arguments of [[phpfn>session_set_cookie_params|session_set_cookie_params()]], please refer to its docs for more details. To use SSL for your cookies, you enable the [[config:securecookie]] configuration setting.

<code php conf/local.protected.php>
//settings specific for use of the ... authentication plugin
define ('DOKU_SESSION_NAME', "YOURSESSIONNAME");
define ('DOKU_SESSION_LIFETIME', 0);
//etc...

//a custom session path
$sessiepath = fullpath(dirname(__FILE__) . '/../../') . '/session';
session_save_path($sessiepath);
</code>


===== Further reading =====

  * [[Plugin programming tips]]
  * [[:auth|Authentication Backends & Plugins]]
  * [[plugins|Plugin Development]]
  * [[plugintype>128#extension__table|Available authentication plugins]]