Differences

This shows you the differences between two versions of the page.

--- devel:auth_plugins [2016-08-08 23:49] – Klap-in
+++ devel:auth_plugins [2018-06-06 00:48] – Klap-in
@@ Line 1: / Line 1: @@
 ====== Authentication Plugins ======
-| **Info on this page is for 2013-05-10 "Weatherwax" and later**\\ \\ See for info for releases 2012-10-13 "Adora Belle" and older on:\\ - development of  old [[devel:authentication backends]] \\ -  old authentication modules [[:auth]] \\ \\ Below first version of docs for new auth plugins. It may contain errors! Please report them, all feedback is welcome.|
+| **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 [[devel:authentication backends|development docs]] and the old  [[:auth|authentication modules]] itself//)
 DokuWiki's authentication system is highly modular and can, generally speaking, authenticate using anything that is accessible from PHP. Available [[plugintype>128#extension__table|Auth Plugins]] are listed.
@@ Line 10: / Line 12: @@
 An Authentication Plugin //Example// needs:
-  * class name  ''auth_plugin_authexample''
+  * class name  ''auth_plugin_example''
   * which extends [[xref>DokuWiki_Auth_Plugin]]((defined in ''lib/plugins/auth.php'')).
-  * to be stored in a file ''lib/plugins/authexample/auth.php''.
+  * to be stored in a file ''lib/plugins/example/auth.php''.
 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 file structure]].
@@ Line 60: / Line 64: @@
-  * **''[[xref>trustExternal|trustExternal()]]''** (replaces DokuWiki authentication functions)\\ If ''$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''. \\ \\ If this method is implemented you may omit the implementation of all the other methods from your module. You only really needs a constructor and this trustExternal() function, 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. 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. \\ \\ Have a look at the [[auth:punbb]] backend for an example usage of this method. According to the example method in the parent ''auth_basic'' class the trustExternal() method has to set the global variables: $USERINFO, $SERVER and _SESSION[DOKU_COOKIE] for the indicated fields. \\ \\ 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>
+  * **''[[xref>trustExternal|trustExternal()]]''** (replaces DokuWiki authentication functions)\\ If ''$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''. \\ \\ If this method is implemented you may omit the implementation of all the other methods from your module. You only really needs a constructor and this trustExternal() function, 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. 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. \\ \\ Have a look at the old [[auth:punbb]] backend for an example usage of this method. (TODO: update with example usage of Auth Plugin) According to the example method in the parent ''auth_basic'' class the trustExternal() method has to set the global variables: $USERINFO, $SERVER and _SESSION[DOKU_COOKIE] for the indicated fields. \\ \\ 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;
@@ Line 100: / Line 104: @@
         //when needed, logoff explicitly.
     }
-</code> 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 [[auth:punbb]] this is done with ''pun_setcookie()'' function call. \\ \\ Dokuwiki will not show any message if the login failed, therefore this method shall show some information using msg(). \\ \\ **Examples** \\ See also this [[working example of trustExternal()|example of trustExternal()]]. \\ \\ Some auth plugins using this function are: [[plugin:authplaincas]] plugin.\\ \\ Some (very old) backends using this function are: [[auth:punbb]], [[auth:cas]], [[auth:cosign]], [[auth:plaincas]], [[auth:django]], [[https://github.com/cato-/django-external-auth|extdjango]], [[http://docs.blackfin.uclinux.org/inc/auth/gforge.class.phps|gforge]], [[auth:ggauth#http|http]] version of ggauth, [[http://keeyai.com/projects-and-releases/dokuwiki-tools/dokuwiki-and-wordpress-integration/|keeyaiwp]], [[auth:mod_auth_tkt]], [[auth:ssp]] \\ \\
+</code> 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 [[auth: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 [[working example of trustExternal()|example of trustExternal()]]. \\ \\ Some auth plugins using this function are: [[plugin:authplaincas]] plugin.\\ \\ Some (very old) backends using this function are: [[auth:punbb]], [[auth:cas]], [[auth:cosign]], [[auth:plaincas]], [[auth:django]], [[https://github.com/cato-/django-external-auth|extdjango]], [[http://docs.blackfin.uclinux.org/inc/auth/gforge.class.phps|gforge]], [[auth:ggauth#http|http]] version of ggauth, [[http://keeyai.com/projects-and-releases/dokuwiki-tools/dokuwiki-and-wordpress-integration/|keeyaiwp]], [[auth:mod_auth_tkt]], [[auth:ssp]] (Please find here instruction how-to reuse parts of these old backends for a modern Auth Plugin: [[https://www.dokuwiki.org/devel:auth_plugins#handling_of_old_auth_backends|Handling of old auth backends]]\\ \\
@@ Line 190: / Line 194: @@
 </code>
-====Howto install an auth plugin via plugin manager without working backend?====
+====Howto install an auth plugin via extension manager without working backend?====
-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 ''conf/local.php'' on you server. Open it in an editor and remove the line from ''conf/local.php'' or ''conf/local.protected.php'':
+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'':
 <code php>
@@ Line 203: / Line 207: @@
 </code>
-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.
+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 [[config: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.