[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

/inc/Extension/ -> AuthPlugin.php (summary)

Auth Plugin Prototype allows to authenticate users in a plugin

Author: Chris Smith
Author: Jan Schumann
License: GPL 2 (http://www.gnu.org/licenses/gpl.html)
File Size: 461 lines (16 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 19 functions

  __construct()
  getCapabilities()
  canDo()
  triggerUserMod()
  logOff()
  trustExternal()
  checkPass()
  getUserData()
  createUser()
  modifyUser()
  deleteUsers()
  getUserCount()
  retrieveUsers()
  addGroup()
  retrieveGroups()
  isCaseSensitive()
  cleanUser()
  cleanGroup()
  useSessionCache()

Functions
Functions that are not part of a class:

__construct()   X-Ref
Constructor.

Carry out sanity checks to ensure the object is
able to operate. Set capabilities in $this->cando
array here

For future compatibility, sub classes should always include a call
to parent::__constructor() in their constructors!

Set $this->success to false if checks fail

author: Christopher Smith <chris@jalakai.co.uk>

getCapabilities()   X-Ref
Available Capabilities. [ DO NOT OVERRIDE ]

For introspection/debugging

author: Christopher Smith <chris@jalakai.co.uk>
return: array

canDo($cap)   X-Ref
Capability check. [ DO NOT OVERRIDE ]

Checks the capabilities set in the $this->cando array and
some pseudo capabilities (shortcutting access to multiple
ones)

ususal capabilities start with lowercase letter
shortcut capabilities start with uppercase letter

param: string $cap the capability to check
author: Andreas Gohr <andi@splitbrain.org>
return: bool

triggerUserMod($type, $params)   X-Ref
Trigger the AUTH_USERDATA_CHANGE event and call the modification function. [ DO NOT OVERRIDE ]

You should use this function instead of calling createUser, modifyUser or
deleteUsers directly. The event handlers can prevent the modification, for
example for enforcing a user name schema.

param: string $type Modification type ('create', 'modify', 'delete')
param: array $params Parameters for the createUser, modifyUser or deleteUsers method.
author: Gabriel Birke <birke@d-scribe.de>
return: bool|null|int Result from the modification function or false if an event handler has canceled the action

logOff()   X-Ref
Log off the current user [ OPTIONAL ]

Is run in addition to the ususal logoff method. Should
only be needed when trustExternal is implemented.

author: Andreas Gohr <andi@splitbrain.org>
see: auth_logoff()

trustExternal($user, $pass, $sticky = false)   X-Ref
Do all authentication [ OPTIONAL ]

Set $this->cando['external'] = true when implemented

If this function is implemented it will be used to
authenticate a user - all other DokuWiki internals
will not be used for authenticating (except this
function returns null, in which case, DokuWiki will
still run auth_login as a fallback, which may call
checkPass()). If this function is not returning null,
implementing checkPass() is not needed here anymore.

The function can be used to authenticate against third
party cookies or Apache auth mechanisms and replaces
the auth_login() function

The function will be called with or without a set
username. If the Username is given it was called
from the login form and the given credentials might
need to be checked. If no username was given it
the function needs to check if the user is logged in
by other means (cookie, environment).

The function needs to set some globals needed by
DokuWiki like auth_login() does.

param: string $user Username
param: string $pass Cleartext Password
param: bool $sticky Cookie should not expire
author: Andreas Gohr <andi@splitbrain.org>
see: auth_login()
return: bool         true on successful auth,

checkPass($user, $pass)   X-Ref
Check user+password [ MUST BE OVERRIDDEN ]

Checks if the given user exists and the given
plaintext password is correct

May be ommited if trustExternal is used.

param: string $user the user name
param: string $pass the clear text password
author: Andreas Gohr <andi@splitbrain.org>
return: bool

getUserData($user, $requireGroups = true)   X-Ref
Return user info [ MUST BE OVERRIDDEN ]

Returns info about the given user needs to contain
at least these fields:

name string  full name of the user
mail string  email address of the user
grps array   list of groups the user is in

param: string $user the user name
param: bool $requireGroups whether or not the returned data must include groups
author: Andreas Gohr <andi@splitbrain.org>
return: false|array containing user data or false

createUser($user, $pass, $name, $mail, $grps = null)   X-Ref
Create a new User [implement only where required/possible]

Returns false if the user already exists, null when an error
occurred and true if everything went well.

The new user HAS TO be added to the default group by this
function!

Set addUser capability when implemented

param: string $user
param: string $pass
param: string $name
param: string $mail
param: null|array $grps
author: Andreas Gohr <andi@splitbrain.org>
return: bool|null

modifyUser($user, $changes)   X-Ref
Modify user data [implement only where required/possible]

Set the mod* capabilities according to the implemented features

param: string $user nick of the user to be changed
param: array $changes array of field/value pairs to be changed (password will be clear text)
author: Chris Smith <chris@jalakai.co.uk>
return: bool

deleteUsers($users)   X-Ref
Delete one or more users [implement only where required/possible]

Set delUser capability when implemented

param: array $users
author: Chris Smith <chris@jalakai.co.uk>
return: int    number of users deleted

getUserCount($filter = array()   X-Ref
Return a count of the number of user which meet $filter criteria
[should be implemented whenever retrieveUsers is implemented]

Set getUserCount capability when implemented

param: array $filter array of field/pattern pairs, empty array for no filter
author: Chris Smith <chris@jalakai.co.uk>
return: int

retrieveUsers($start = 0, $limit = 0, $filter = null)   X-Ref
Bulk retrieval of user data [implement only where required/possible]

Set getUsers capability when implemented

param: int $start index of first user to be returned
param: int $limit max number of users to be returned, 0 for unlimited
param: array $filter array of field/pattern pairs, null for no filter
author: Chris Smith <chris@jalakai.co.uk>
return: array list of userinfo (refer getUserData for internal userinfo details)

addGroup($group)   X-Ref
Define a group [implement only where required/possible]

Set addGroup capability when implemented

param: string $group
author: Chris Smith <chris@jalakai.co.uk>
return: bool

retrieveGroups($start = 0, $limit = 0)   X-Ref
Retrieve groups [implement only where required/possible]

Set getGroups capability when implemented

param: int $start
param: int $limit
author: Chris Smith <chris@jalakai.co.uk>
return: array

isCaseSensitive()   X-Ref
Return case sensitivity of the backend [OPTIONAL]

When your backend is caseinsensitive (eg. you can login with USER and
user) then you need to overwrite this method and return false

return: bool

cleanUser($user)   X-Ref
Sanitize a given username [OPTIONAL]

This function is applied to any user name that is given to
the backend and should also be applied to any user name within
the backend before returning it somewhere.

This should be used to enforce username restrictions.

param: string $user username
author: Andreas Gohr <andi@splitbrain.org>
return: string the cleaned username

cleanGroup($group)   X-Ref
Sanitize a given groupname [OPTIONAL]

This function is applied to any groupname that is given to
the backend and should also be applied to any groupname within
the backend before returning it somewhere.

This should be used to enforce groupname restrictions.

Groupnames are to be passed without a leading '@' here.

param: string $group groupname
author: Andreas Gohr <andi@splitbrain.org>
return: string the cleaned groupname

useSessionCache($user)   X-Ref
Check Session Cache validity [implement only where required/possible]

DokuWiki caches user info in the user's session for the timespan defined
in $conf['auth_security_timeout'].

This makes sure slow authentication backends do not slow down DokuWiki.
This also means that changes to the user database will not be reflected
on currently logged in users.

To accommodate for this, the user manager plugin will touch a reference
file whenever a change is submitted. This function compares the filetime
of this reference file with the time stored in the session.

This reference file mechanism does not reflect changes done directly in
the backend's database through other means than the user manager plugin.

Fast backends might want to return always false, to force rechecks on
each page load. Others might want to use their own checking here. If
unsure, do not override.

param: string $user - The username
author: Andreas Gohr <andi@splitbrain.org>
return: bool