Learn about DokuWiki
Advanced Use
Corporate Use
Our Community
Follow us on Facebook, Twitter and other social networks.
Learn about DokuWiki
Advanced Use
Corporate Use
Our Community
Follow us on Facebook, Twitter and other social networks.
Info on this page is for 2013-05-10 “Weatherwax” and later Below are the docs for new auth plugins. It may contain errors! Please report them, all feedback is welcome. |
(For reference the old documentation can be found at the old development docs and the old authentication modules itself)
DokuWiki's authentication system is highly modular and can, generally speaking, authenticate using anything that is accessible from PHP. Available Auth Plugins are listed.
In summary, there are two distinct ways of building your authentication plugin. Firstly, you can create a plugin that implements all DokuWiki's methods needed to gather user info and verify users. Secondly, you can use the trustExternal()
method, which will replace the Dokuwiki authentication functions. You handle the authentication in this method by calling your own backend.
An Authentication Plugin Example needs:
auth_plugin_example
lib/plugins/example/auth.php
.Moreover, a plugin.info.txt file is needed. For full details of plugins and their files and how to create more auth components refer to plugin file structure.
You need to implement at least two fields and three methods.
Fields:
$success
$cando
$cando
field is an associative array of booleans. You need to set the array fields to true for all functions your backend provides. 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)Methods:
Only a few functions need to be implemented. But the more you do the more the frontend will be able to do. See lib/plugins/auth.php for the methods' arguments and return values and for an example implementation see lib/plugins/authplain/auth.php the plain authentication backend, DokuWikis default.
__construct()
$success
and $cando
mentioned above here.checkPass($user, $pass)
$user
exists and the given plaintext password $pass
is correct.getUserData($user, $requireGroups=true)
$user
$requireGroups
is True, the function should return the user's groups as well. array( 'name' => string, 'mail' => string, 'grps' => array() )
All these methods are optional and will only be called if the appropriate $cando fields are set
trustExternal()
(replaces DokuWiki authentication functions)$cando['external']
is true, this method is used to authenticate a user – all other DokuWiki internals will not be used for authenticating. The function can be used to authenticate against third party cookies or Apache auth mechanisms and replaces the default auth_login()
function from inc/auth.php
. getUserData()
so DokuWiki can display your users nicely and logoff()
to permit DokuWiki to communicate the logoff to your backend. The other methods are only needed when you like that some internals of DokuWiki interact with your backend. Search the source code or browse on http://xref.dokuwiki.org/ to check out the connections. auth_basic
class the trustExternal() method has to set the global variables: $USERINFO, $SERVER and _SESSION[DOKU_COOKIE] for the indicated fields. function trustExternal($user, $pass, $sticky=false) { global $USERINFO; // 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. }
For a description of the $USERINFO
variables see the documentation of the getUserData()
function. Do not forget to add global $USERINFO
to the start of this function, to make the variable accessible.
Another thing to keep in mind if you're implementing Single Sign On based on a cookie, is that if you want to be able to use DokuWiki's login form when SSO cookie is not present, you need to set that cookie once you verify the credentials, so on next page load you can authenticate based on that SSO cookie as $user and $pass variables will be empty since login form is not submitted. In punbb this is done with pun_setcookie()
function call. (TODO: update with example usage of Auth Plugin instead old Auth backend)
Dokuwiki will not show any message if the login failed, therefore this method shall show some information using msg().
Examples
See also this example of trustExternal().
Some auth plugins using this function are: authplaincas plugin.
Some (very old) backends using this function are: punbb, cas, cosign, plaincas, django, extdjango, gforge, http version of ggauth, keeyaiwp, mod_auth_tkt, ssp (Please find here instruction how-to reuse parts of these old backends for a modern Auth Plugin: Handling of old auth backends
logOff()
(only when required/possible)createUser($user,$pass,$name,$mail,$grps=null)
(only when required/possible)modifyUser($user, $changes)
(only when required/possible)deleteUsers($users)
(only when required/possible)getUserCount($filter=array()
(needed when retrieveUsers() is implemented)retrieveUsers($start=0,$limit=-1,$filter=null)
(only when required/possible)addGroup($group)
(only when required/possible)retrieveGroups($start=0,$limit=0)
(only when required/possible)isCaseSensitive()
(optional)cleanUser($user)
(optional)cleanGroup($group)
(optional)useSessionCache($user)
(only when required)canDo($cap)
Checks capabilities set in $cando
field, or the pseudo capabilities: Profile
and UserMod
.triggerUserMod($type, $params)
Triggers AUTH_USERDATA_CHANGE
, which calls the methods defined on the current authentication plugin for the $type
equal to: create
, modify
and delete
where $params
are type specific parameters.
At the moment, temporary, also the config of old style auth modules are loaded.
The loading order is:
$conf['auth']['yourauthbackend']
)) $conf['plugin']['yourauthplugin']
).(Available since release 2014-05-05 “Ponder Stibbons”)
Dokuwiki starts (in 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 session_set_cookie_params(), please refer to its docs for more details. To use SSL for your cookies, you enable the securecookie configuration setting.
//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);
Your backend (or its framework) cannot use __autoload to include further classes, those classes must be loaded manually via require()
When you update your wiki to the 2013-05-10 “Weatherwax” release, you need an auth plugin for the authentication, because the authentication backends aren't supported anymore. The previous bundled authentication backends are already converted to auth plugins: AuthPlain, AuthMySQL, AuthPgSQL, AuthAD and AuthLDAP.
When you use another plugin than the bundled one, you need to check if someone has already shared the auth plugin version in the plugin repository. You can filter the plugins by Auth plugintype. Or you should rewrite the authentication backend yourself. See Howto update your old backend below.
When you used the plain
authentication backend before, DokuWiki will pick up the new authplain
due to DokuWiki's defaults are updated too. For all other values of the authtype configuration, you get the warning User authentication is temporarily unavailable. If this situation persists, please inform your Wiki Admin.
and you cannot login anymore. This can be solved by updating the authtype configuration to the auth plugin version of your desired backend. When you use a not bundled auth plugin you should first install this one.
When your desired auth plugin is installed you can modify your the authtype configuration setting in conf/local.php
(or conf/local.protected.php
) by an editor on your server by prefixing your <authentication backend name>
with auth
to auth<authentication backend name>
:
... // $conf['authtype'] = 'example'; //auth backend $conf['authtype'] = 'authexample'; //auth plugin ...
When you prefer to install an auth plugin by the DokuWiki extension manager, you need to switch to the plain authentication backend. You need access to the configuration file conf/local.php
on you server. Open it in an editor and remove the line from conf/local.php
or conf/local.protected.php
:
// $conf['authtype'] = '...'; //disable your authtype config
or change that line to:
$conf['authtype'] = 'authplain';
and save the file. Now your wiki uses the AuthPlain plugin. Next you login as superuser. Hint: Probably you can login by the user you define on installation (the installer creates default that users as superuser). Now you can use the extension manager as usually.
Next you can configure the plugin settings via the configuration manager (these settings are stored in conf/local.php
) or you can save these protected against changes from the configuration manager by creating and editing the file conf/local.protected.php
. Lastly, you change the authtype configuration to your new auth plugin and save. When your wiki becomes inaccessible again, you can modify the configuration settings via an editor on your server again.
See farther for more info about the configuration files and the config manager.
When auth plugin is activated, and there is an old config available, then first the old auth backend is loaded, next the new auth plugin config is loaded. So when auth plugin configuration settings are set these overwrite the old auth backend values.
Complete load sequence of plugin config settings:
lib/plugins/<pluginname>/conf/default.php
conf/local.php
(or possibly overwritten by conf/local.protected.php
) where:$config['auth']['<authbackendname>']
are read$config['plugin']['auth<authbackendname>']
Tip:
When you start changing settings of auth plugin, especially when you reset a setting to its plugin default, it is recommended to remove the old $config['auth']['<authbackendname>']
settings from the local.php
and/or local.protected.php
.
Some tips on updating your backend from inc/auth/<authname>.class.php
to an Auth plugin.
Simple approach:
auth
e.g. authexample
.inc/auth/<authbackendname>.class.php
in your new lib/plugins/auth<authbackendname>/auth.php
.
more relevant directions??
lib/plugins/auth.php