Differences

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

--- devel:authentication_backends [2011-08-11 12:56] – [Notes] 92.75.19.79
+++ devel:authentication_backends [2023-09-20 23:10] (current) – cleanup docs about the former authentication backends Klap-in
@@ Line 1: / Line 1: @@
-====== How to write an Authentication Backend ?======
-[[:DokuWiki]]'s authentication system is highly modular and can, generally speaking, authenticate using anything that is accessible from PHP.
-If none of the provided [[:auth]] does what you want, you can simply create your own. Backends are stored in the ''inc/auth/'' folder and need to be named ''<backend>.class.php'' where <backend> is the name of your authentication backend. In this file you need to specify a class named ''auth_<backend>''. Your class should either extend one of the existing backends or the ''auth_basic'' class defined in ''inc/auth/basic.class.php''.
-In your class you need to override a few methods and set some public fields from the [[http://github.com/splitbrain/dokuwiki/blob/master/inc/auth/basic.class.php|base class]]. Some descriptions follow, but for the doing the implementation you need to have a look at base class' comments!
-If you write a new backend be sure to share your code with the community!
-===== Fields to set =====
-==== $success  ====
-This simple boolean needs to be set to //true// in your constructor if your auth module was correctly initialized. Use this to notify the frontend if anything went wrong by setting it to //false//.
-==== $cando ====
-The $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? |
-| logoff      | has the module some special logoff method? |
-===== Required Methods  =====
-Only two functions need to be implemented. But the more you do the more the frontend will be able to do.
-See basic.class.php for the methods' arguments and return values.
-==== Constructor ====
-Well your class should have a constructor of course :-) Set the fields mentioned above here.
-==== checkPass($user, $pass) ====
-This function need to check if the given user ($user) exists and the given plaintext password ($pass) is correct.
-==== getUserData($user) ====
-Used to return user information like email address and real name.
-Return false or an array with the keys 'name' => string, 'mail' => string, 'grps' => array
-===== Optional Methods =====
-All these methods are optional and will only be called if the appropriate [[#cando]] fields are set
-==== trustExternal() ====
-If $cando['external'] is true, this function 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 ''auth_login()'' function from ''inc/auth.php''.
-Have a look at the [[auth:punbb]] backend for an example usage of this function.
-If this function is implemented you may omit all other functions from your module (even the required ones above - except for the constructor of course).
-According to the [[auth:punbb]] example the trustExternal() function has to set the following global variables:\\
-$USERINFO['name']\\
-$USERINFO['mail']\\
-$USERINFO['grps']\\
-$_SERVER['REMOTE_USER']\\
-$_SESSION[DOKU_COOKIE]['auth']['user']\\
-$_SESSION[DOKU_COOKIE]['auth']['info'] = $USERINFO;\\
-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 to keep in mind if you're implementing Single Sing 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.
-==== logOff() ====
-If $cando['logoff'] is set to true this function will be called on a logoff event. Use it to clear cookies or similar actions. Probably only useful with [[#trustExternal]]
-==== createUser() ====
-Creates a user with the provided data.
-==== modifyUser() ====
-Modifies a user's data.
-==== deleteUser() ====
-Deletes one or more users.
-==== getUserCount() ====
-Returns the number of users matching certain filter criteria.
-==== retrieveUsers() ====
-Fetches userdata for multiple users matching a certain filter criteria.
-==== addGroup() ====
-Creates a new Group
-==== retrieveGroups()    ====
-List all available groups
-===== Notes =====
-  * The authentication backend does currently not use method visibility (available since PHP 5), therefore all methods are expected to be public
-  * doku.php throws E_NOTICE errors due to undefined $_REQUEST-variables. Avoid setting the error reporting to E_ALL in the authenticiation backend or the classes used by the backend.
-  * Dokuwiki starts a session prior to using the authentication backend. Therefore starting a session with modified settings (e.g. another session path) is not easily possible in the backend.
-  * Your backend (or its framework) cannot use __autoload to include further classes, those classes must be loaded manually via require()