====== How to write an Authentication Backend ?======

[[wiki:DokuWiki]]'s authentication system is highly modular and can, generally speaking, use everything to authenticate that is accessible from PHP.

If none of the provided [[backends]] do 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://dev.splitbrain.org/view/darcs/dokuwiki/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.

==== Constructor ====

Well your class should have a constructor of course :-) Set the fields mentioned above here.

==== checkPass() ====

This function need to check if the given user exists and the given plaintext password is correct.

==== getUserData() ====

Used to return user information like email address and real name.

===== 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 [[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 [[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 accessable.

==== 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