DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:authentication_backends

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
devel:authentication_backends [2014-03-11 13:19] – [JOHN KOWSHIk] 182.74.99.169devel: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 ?====== 
- 
-^The authentication backends developed as described on this page would only work at DokuWiki releases 2012-10-13 “Adora Belle” and older.\\ \\ See for development documentation about the new authentications plugins on [[Auth Plugin]] ^ 
- 
-[[: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  
-  * need to be named ''<backend>.class.php'' where <backend> is the name of your authentication backend.  
-  * specify a class named ''auth_<backend>'' 
-  * Your class should either extend one of the existing backends or the ''auth_basic'' class defined in ''[[xref>inc/auth/basic.class.php]]''. 
- 
-In your class you need to override a few methods and set some public fields from the [[xref>auth_basic|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! 
- 
- 
- 
- 
- 
- 
-**JOHN KOWSHIK** 
- 
-===== Fields to set ===== 
- 
-  * **''[[xref>$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//. 
- 
-  * **''[[xref>$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 a few functions need to be implemented. But the more you do the more the frontend will be able to do. 
- 
-See [[xref>inc/auth/basic.class.php]] for the methods' arguments and return values. 
- 
-  * **''[[xref>__construct|__construct()]]''** \\ Well your class should have a constructor of course :-) Set the fields ''$success'' and ''$cando'' mentioned above here. 
- 
-  * **''[[xref>checkPass|checkPass($user, $pass)]]''** \\ This function need to check if the given userid ''$user'' exists and the given plaintext password ''$pass'' is correct. 
- 
-  * **''[[xref>getUserData|getUserData($user)]]''** \\ Used to return user information like email address and real name, for the requested userid ''$user'' \\ Return false or an array with at least the keys<code php> 
-array( 
-    'name' => string, 
-    'mail' => string, 
-    'grps' => array() 
-) 
-</code> 
- 
- 
-===== Optional Methods ===== 
- 
-All these methods are optional and will **only** be called if the appropriate [[#field to set|$cando]] fields are set 
- 
- 
-  * **''[[xref>trustExternal|trustExternal()]]''** (replaces DokuWiki authentication functions)\\ 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''. \\ \\ If this function is implemented you may omit all other functions from your module. You only really needs a constructor and this trustExternal() function, and it strong 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 functions 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 function. According to the example method in the parent ''auth_basic'' class the trustExternal() function 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; 
-     
-    // someone used the login form 
-    if(!empty($user)){ 
-        //situation: there are user credentials, lets check them 
-        if( ...try to authenticate again 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. 
-    } 
-</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()]]. \\ \\ Some 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]] \\ \\ 
- 
- 
-  * **''[[xref>logOff()]]''** (only when required/possible)\\ Run in addition to the usual logoff. Useful with [[#trustExternal|trustExternal()]] to initiate actions for the external backend e.g. use it to clear cookies or similar actions.  
- 
- 
-  * **''[[xref>createUser()|createUser($user,$pass,$name,$mail,$grps=null)]]''** (only when required/possible)\\ Creates a user with the provided data. Returns false, when user already exists, null when error and true when succeeded. 
- 
-  * **''[[xref>modifyUser()|modifyUser($user, $changes)]]''** (only when required/possible)\\ Modifies a user's data. 
- 
-  * **''[[xref>deleteUsers()|deleteUsers($users)]]''** (only when required/possible)\\ Deletes one or more users. 
- 
- 
- 
-  * **''[[xref>getUserCount()|getUserCount($filter=array()]]''** (needed when retrieveUsers() is implemented)\\ Returns the number of users matching certain filter criteria.  
- 
- 
-  * **''[[xref>retrieveUsers()|retrieveUsers($start=0,$limit=-1,$filter=null)]]''** (only when required/possible)\\ Fetches userdata for multiple users matching a certain filter criteria. 
- 
- 
-  * **''[[xref>addGroup()|addGroup($group) ]]''** (only when required/possible)\\ Creates a new Group 
- 
-  * **''[[xref>retrieveGroups()|retrieveGroups($start=0,$limit=0) ]]''** (only when required/possible)\\ List all available groups 
- 
-  * **''[[xref>isCaseSensitive()]]''** (optional)\\ When your backend is caseinsensitive, override it with a method that returns false. 
- 
-  * **''[[xref>cleanUser()|cleanUser($user)]]''** (optional)\\ Applied when username is given to and return from backend. Enforce here also username restrictions. 
- 
-  * **''[[xref>cleanGroup()|cleanGroup($group)]]''** (optional)\\ Applied when groupname is given to and return from backend. Enforce here also groupname restrictions. Groupnames are to be passed without a leading '@' here. 
- 
-  * **''[[xref>useSessionCache()|useSessionCache($user)]]''** (only when required)\\ DokuWiki caches user info for a timespan. This function check expiration of this caching. 
- 
-===== 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. 
-  * Your authentication backend may be called from different working directories (e.g. dokuwiki root or /inc/auth). Keep this in mind if your backend includes or loades other files. 
-  * Dokuwiki starts a session prior to using the authentication backend. If your framework uses specific session settings (e.g. another session path) use ''session_destroy()'' in the backend constructor and start your own session then (Note: not fully tested for side effects, yet!). 
-  * Your backend (or its framework) cannot use __autoload to include further classes, those classes must be loaded manually via require() 
devel/authentication_backends.1394540394.txt.gz · Last modified: 2014-03-11 13:19 by 182.74.99.169

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki