devel:auth_plugins
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
devel:auth_plugins [2018-04-05 11:04] – [Synopsis] andi | devel:auth_plugins [2023-09-19 10:50] (current) – [addGroup] andi | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Authentication Plugins ====== | ====== Authentication Plugins ====== | ||
- | | **Info on this page is for 2013-05-10 " | + | DokuWiki' |
- | (//For reference the old documentation can be found at the old [[devel:authentication backends|development docs]] and the old [[: | + | Authentication plugins provide multiple tasks: |
- | DokuWiki' | + | - 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 | ||
- | In summary, there are two distinct ways of building your authentication plugin. Firstly, you can create a plugin that implements all DokuWiki' | ||
===== Synopsis ===== | ===== Synopsis ===== | ||
- | An Authentication Plugin //Example// needs: | + | Please refer to [[devel:plugins]] and [[plugin file structure]] for general info for plugin development. Best use the [[plugin: |
- | * class name '' | + | Your new class needs to follow the general naming scheme for plugins and inherit from [[xref>dokuwiki\Extension\AuthPlugin]]. |
- | * which extends | + | |
- | * to be stored in a file '' | + | |
- | Moreover, | + | Eg. for a plugin |
+ | Below, the most important methods when writing an auth plugin are described. Refer to [[devel: | ||
- | ====Required implementation==== | ||
- | You need to implement at least two fields and three methods. | ||
- | //Fields:// | + | ===== Initialization and Capabilities ===== |
- | * **'' | + | Your plugin |
- | * **'' | + | 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:: |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | //Methods:// | + | 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> |
- | Only a few functions need to be implemented. But the more you do the more the frontend will be able to do. See [[xref> | + | < |
+ | public function __construct() | ||
+ | { | ||
+ | parent:: | ||
- | * **'' | + | $this-> |
+ | $this->cando['modMail'] = true; | ||
- | * **'' | + | $this-> |
+ | } | ||
+ | </code> | ||
- | * **'' | + | |
- | array( | + | Here is a list of keys in '' |
- | | + | |
- | 'mail' => string, | + | * '' |
- | | + | * '' |
- | ) | + | * '' |
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | | ||
+ | | ||
+ | | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | ===== 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:: | ||
+ | |||
+ | <code php> | ||
+ | public function checkPass($user, $pass) | ||
+ | { | ||
+ | | ||
+ | | ||
+ | | ||
+ | } | ||
+ | return false; | ||
+ | } | ||
</ | </ | ||
+ | ==== trustExternal ==== | ||
- | ====Optional implementation==== | + | The second option is to implement the [[xref> |
- | All these methods are optional and will **only** be called **if** | + | The trustExternal() method completely replaces |
+ | The method needs to set a few DokuWiki internal variables to create a logged in state. Namely '' | ||
- | * **'' | + | |
+ | The implementation depends very much on your backend, here are some often used parts indicated as example. Look also for other implementations, | ||
+ | |||
+ | <code php> | ||
function trustExternal($user, | function trustExternal($user, | ||
global $USERINFO; | global $USERINFO; | ||
+ | global $lang; | ||
| | ||
// someone used the login form | // someone used the login form | ||
Line 104: | Line 132: | ||
//when needed, logoff explicitly. | //when needed, logoff explicitly. | ||
} | } | ||
- | </ | + | </ |
+ | In theory you can create an auth plugin that only implements '' | ||
- | * **'' | ||
+ | ===== Get User Information ===== | ||
- | * **'' | + | ==== getUserData ==== |
- | * **'' | + | DokuWiki will need to query user information for the currently logged in user (if not supplied in '' |
- | * **'' | + | User information is requested from your plugin via the [[xref>AuthPlugin:: |
+ | The method should return an array with at least the full name and email address for the given '' | ||
- | * **'' | + | <code php> |
+ | public function getUserData($user, $requireGroups = true) | ||
+ | { | ||
+ | // obviously implement real user data retrieval here | ||
+ | if ($user == 'andi' | ||
+ | return [ | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ]; | ||
+ | } | ||
+ | return false; | ||
+ | } | ||
+ | </ | ||
- | * **'' | + | ==== retrieveUsers ==== |
+ | optional, set '' | ||
- | * **'' | + | The [[xref>AuthPlugin:: |
- | * **'' | + | FIXME explain filter syntax |
- | * **'' | + | ==== getUserCount ==== |
- | * **'' | + | optional, set '' |
- | * **'' | + | The [[xref>AuthPlugin:: |
- | * **'' | ||
+ | ==== retrieveGroups ==== | ||
- | ==== Inherited methods ==== | + | optional, set '' |
- | * All the optional | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * See [[devel:common plugin functions]] for inherited function available to all plugins. e.g. localisation, | + | The [[xref> |
- | ===== Notes ===== | ||
- | ====Config loading sequence==== | ||
- | At the moment, temporary, also the config of old style auth modules are loaded.\\ The loading order is: | ||
- | - Default config settings | ||
- | - Old style auth module config settings (i.e. '' | ||
- | - The current auth plugin settings (i.e. '' | ||
- | ====Start session customization==== | + | ===== User Management ===== |
- | (Available since release 2014-05-05 " | + | |
- | Dokuwiki starts (in [[xref> | + | ==== createUser ==== |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | The defines correspond to the arguments of [[phpfn> | + | |
- | ==Example== | + | optional, set '' |
- | <code php conf/ | + | |
- | //settings specific for use of the ... authentication plugin | + | |
- | define ('DOKU_SESSION_NAME', " | + | |
- | define ('DOKU_SESSION_LIFETIME', 0); | + | |
- | //etc... | + | |
- | //a custom session path | + | The [[xref> |
- | $sessiepath = fullpath(dirname(__FILE__) . '/../ | + | |
- | session_save_path($sessiepath); | + | |
- | </ | + | |
- | ====About autoloading==== | + | |
- | Your backend (or its framework) cannot use %%__autoload%% to include further classes, those classes must be loaded manually via require() | + | |
- | ===== Handling of old auth backends ===== | + | |
- | When you update your wiki to the 2013-05-10 “Weatherwax” release, you need an auth plugin for the authentication, | + | ==== modifyUser ==== |
- | 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 [[plugintype> | + | optional, set '' |
+ | The [[xref> | ||
- | ====Update wiki to new backend==== | + | ==== deleteUsers |
- | When you used the '' | + | |
- | When your desired auth plugin is installed you can modify your the [[config: | + | optional, set '' |
- | <code php conf/ | + | The [[xref> |
- | ... | + | |
- | // $conf[' | + | |
- | $conf[' | + | |
- | ... | + | |
- | </ | + | |
- | ====Howto install an auth plugin via plugin manager without working backend?==== | + | ==== addGroup |
- | When you prefer to install an auth plugin by the DokuWiki plugin manager, you need to switch to the plain authentication backend. You need access to the configuration file '' | + | |
- | <code php> | + | optional |
- | // $conf[' | + | |
- | </ | + | |
- | or change that line to: | + | The [[xref> |
- | <code php> | ||
- | $conf[' | ||
- | </ | ||
- | 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 plugin manager as usually. | + | ===== Utility Methods ===== |
- | Next you can configure the plugin settings via the configuration manager (these settings are stored in '' | + | ==== logOff ==== |
- | See farther for more info about the [[plugin: | + | optional, set '' |
- | ====Old configurations==== | + | The [[xref> |
- | 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. | + | ==== isCaseSensitive ==== |
- | Complete load sequence of plugin config settings: | + | When your backend is caseinsensitive, |
- | - settings from '' | + | |
- | - settings from '' | + | |
- | - first settings of '' | + | |
- | - and next settings of '' | + | |
- | Tip:\\ | + | ==== cleanUser ==== |
- | 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 '' | + | |
+ | optional | ||
- | ===== Howto update your old backend | + | The [[xref> |
- | Some tips on updating your backend from '' | + | |
- | Simple approach: | + | ==== cleanGroup ==== |
- | - Create a plugin skelet corresponding to [[devel:plugin file structure]] and the [[#synopsis]] at top of this page. (skelet generator: http://pluginwiz.dokuwiki.org/ | + | |
- | * Please prefix | + | optional |
- | | + | |
- | * Be aware you can load other plugins or helper plugins | + | The [[xref> |
- | * There are some inherited functions for localisation, configuration and more, see [[#inherited methods]] above. | + | |
+ | Groupnames are passed without a leading '' | ||
+ | |||
+ | ==== useSessionCache ==== | ||
+ | |||
+ | optional | ||
+ | |||
+ | DokuWiki caches user info for a timespan. The [[xref> | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Notes ===== | ||
+ | |||
+ | ====Start session customization==== | ||
+ | |||
+ | |||
+ | Dokuwiki starts | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | The defines correspond to the arguments of [[phpfn> | ||
+ | |||
+ | <code php conf/ | ||
+ | //settings specific for use of the ... authentication plugin | ||
+ | define (' | ||
+ | define (' | ||
+ | //etc... | ||
+ | |||
+ | //a custom session path | ||
+ | $sessiepath = fullpath(dirname(__FILE__) . '/ | ||
+ | session_save_path($sessiepath); | ||
+ | </ | ||
- | FIXME more relevant directions?? | ||
===== Further reading ===== | ===== Further reading ===== |
devel/auth_plugins.1522919076.txt.gz · Last modified: 2018-04-05 11:04 by andi