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 [2013-05-10 16:22] – removed develonly tag Klap-in | 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' |
- | DokuWiki' | + | 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 | ||
- | 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: |
- | * class name '' | + | |
- | * which extends | + | |
- | * to be stored in a file '' | + | |
- | Moreover, a [[plugin_info|plugin.info.txt]] file is needed. For full details of plugins and their files and how to create more auth components refer to [[plugin | + | |
+ | Your new class needs to follow the general naming scheme for plugins and inherit from [[xref> | ||
- | ====Required implementation==== | + | Eg. for a plugin '' |
- | You need to implement at least two fields and three methods. | + | |
- | //Fields:// | + | 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 |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | // | + | Your plugin needs to signal that it is ready to use to DokuWiki' |
- | Only a few functions | + | This is done in the plugin' |
- | * **'' | + | 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 |
+ | |||
+ | <code php> | ||
+ | public function __construct() | ||
+ | { | ||
+ | parent:: | ||
- | * **'' | + | $this-> |
+ | | ||
- | * **'' | + | |
- | array( | + | } |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ) | + | |
</ | </ | ||
+ | Here is a list of keys in '' | ||
- | ====Optional implementation==== | + | * '' |
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
- | All these methods are optional and will **only** be called **if** the appropriate **[[# | + | ===== Authentication ===== |
+ | There are two distinct ways of how your authentication plugin can authenticate the current user: | ||
- | | + | |
+ | - 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 | ||
+ | { | ||
+ | // obviously implement a real check here | ||
+ | if($user == 'andi' | ||
+ | return true; | ||
+ | } | ||
+ | return false; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ==== trustExternal ==== | ||
+ | |||
+ | |||
+ | The second option is to implement | ||
+ | |||
+ | The trustExternal() method | ||
+ | |||
+ | The method needs to set a few DokuWiki internal | ||
+ | |||
+ | |||
+ | 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 | ||
if(!empty($user)){ | if(!empty($user)){ | ||
// | // | ||
- | if( ...try to authenticate | + | if( ...try to authenticate |
| | ||
// here you can handle additional post login actions | // here you can handle additional post login actions | ||
Line 100: | 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=== | + | ===== User Management ===== |
- | Dokuwiki starts a session prior to using the authentication backend. If your framework uses specific session settings (e.g. another session path) use '' | + | |
- | SUGGESTION: Do it require an own event or auth function to replace default sessionstart? | + | ==== createUser ==== |
- | ===About autoloading=== | + | optional, set '' |
- | 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 ===== | + | The [[xref> |
- | When you update your wiki to the 2013-03-06 “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 | ||
+ | |||
+ | The [[xref> | ||
+ | |||
+ | ==== cleanGroup ==== | ||
+ | |||
+ | optional | ||
+ | |||
+ | The [[xref> | ||
+ | |||
+ | Groupnames are passed without a leading '' | ||
+ | |||
+ | ==== useSessionCache ==== | ||
+ | |||
+ | optional | ||
+ | |||
+ | DokuWiki caches user info for a timespan. The [[xref> | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Notes ===== | ||
+ | |||
+ | ====Start session customization==== | ||
+ | |||
+ | |||
+ | Dokuwiki starts (in [[xref> | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | 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); | ||
+ | </ | ||
- | ===== Howto update your old backend ===== | ||
- | Some tips on updating your backend from '' | ||
- | Simple approach: | + | ===== Further reading ===== |
- | - Create a plugin skelet corresponding to [[devel: | + | |
- | * Please prefix the plugin name of your Auth plugin by '' | + | |
- | - You can reuse the code from '' | + | |
- | * Be aware you can load other plugins or helper plugins | + | |
- | * There are some inherited functions for localisation, | + | |
- | FIXME more relevant directions?? | + | * [[Plugin programming tips]] |
+ | * [[: | ||
+ | * [[plugins|Plugin Development]] | ||
+ | * [[plugintype> |
devel/auth_plugins.1368195762.txt.gz · Last modified: 2013-05-10 16:22 by Klap-in