[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

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

   1  <?php
   2  
   3  namespace dokuwiki\Extension;
   4  
   5  /**
   6   * Auth Plugin Prototype
   7   *
   8   * allows to authenticate users in a plugin
   9   *
  10   * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
  11   * @author     Chris Smith <chris@jalakai.co.uk>
  12   * @author     Jan Schumann <js@jschumann-it.com>
  13   */
  14  abstract class AuthPlugin extends Plugin
  15  {
  16      public $success = true;
  17  
  18      /**
  19       * Possible things an auth backend module may be able to
  20       * do. The things a backend can do need to be set to true
  21       * in the constructor.
  22       */
  23      protected $cando = array(
  24          'addUser' => false, // can Users be created?
  25          'delUser' => false, // can Users be deleted?
  26          'modLogin' => false, // can login names be changed?
  27          'modPass' => false, // can passwords be changed?
  28          'modName' => false, // can real names be changed?
  29          'modMail' => false, // can emails be changed?
  30          'modGroups' => false, // can groups be changed?
  31          'getUsers' => false, // can a (filtered) list of users be retrieved?
  32          'getUserCount' => false, // can the number of users be retrieved?
  33          'getGroups' => false, // can a list of available groups be retrieved?
  34          'external' => false, // does the module do external auth checking?
  35          'logout' => true, // can the user logout again? (eg. not possible with HTTP auth)
  36      );
  37  
  38      /**
  39       * Constructor.
  40       *
  41       * Carry out sanity checks to ensure the object is
  42       * able to operate. Set capabilities in $this->cando
  43       * array here
  44       *
  45       * For future compatibility, sub classes should always include a call
  46       * to parent::__constructor() in their constructors!
  47       *
  48       * Set $this->success to false if checks fail
  49       *
  50       * @author  Christopher Smith <chris@jalakai.co.uk>
  51       */
  52      public function __construct()
  53      {
  54          // the base class constructor does nothing, derived class
  55          // constructors do the real work
  56      }
  57  
  58      /**
  59       * Available Capabilities. [ DO NOT OVERRIDE ]
  60       *
  61       * For introspection/debugging
  62       *
  63       * @author  Christopher Smith <chris@jalakai.co.uk>
  64       * @return  array
  65       */
  66      public function getCapabilities()
  67      {
  68          return array_keys($this->cando);
  69      }
  70  
  71      /**
  72       * Capability check. [ DO NOT OVERRIDE ]
  73       *
  74       * Checks the capabilities set in the $this->cando array and
  75       * some pseudo capabilities (shortcutting access to multiple
  76       * ones)
  77       *
  78       * ususal capabilities start with lowercase letter
  79       * shortcut capabilities start with uppercase letter
  80       *
  81       * @author  Andreas Gohr <andi@splitbrain.org>
  82       * @param   string $cap the capability to check
  83       * @return  bool
  84       */
  85      public function canDo($cap)
  86      {
  87          switch ($cap) {
  88              case 'Profile':
  89                  // can at least one of the user's properties be changed?
  90                  return ($this->cando['modPass'] ||
  91                      $this->cando['modName'] ||
  92                      $this->cando['modMail']);
  93                  break;
  94              case 'UserMod':
  95                  // can at least anything be changed?
  96                  return ($this->cando['modPass'] ||
  97                      $this->cando['modName'] ||
  98                      $this->cando['modMail'] ||
  99                      $this->cando['modLogin'] ||
 100                      $this->cando['modGroups'] ||
 101                      $this->cando['modMail']);
 102                  break;
 103              default:
 104                  // print a helping message for developers
 105                  if (!isset($this->cando[$cap])) {
 106                      msg("Check for unknown capability '$cap' - Do you use an outdated Plugin?", -1);
 107                  }
 108                  return $this->cando[$cap];
 109          }
 110      }
 111  
 112      /**
 113       * Trigger the AUTH_USERDATA_CHANGE event and call the modification function. [ DO NOT OVERRIDE ]
 114       *
 115       * You should use this function instead of calling createUser, modifyUser or
 116       * deleteUsers directly. The event handlers can prevent the modification, for
 117       * example for enforcing a user name schema.
 118       *
 119       * @author Gabriel Birke <birke@d-scribe.de>
 120       * @param string $type Modification type ('create', 'modify', 'delete')
 121       * @param array $params Parameters for the createUser, modifyUser or deleteUsers method.
 122       *                       The content of this array depends on the modification type
 123       * @return bool|null|int Result from the modification function or false if an event handler has canceled the action
 124       */
 125      public function triggerUserMod($type, $params)
 126      {
 127          $validTypes = array(
 128              'create' => 'createUser',
 129              'modify' => 'modifyUser',
 130              'delete' => 'deleteUsers',
 131          );
 132          if (empty($validTypes[$type])) {
 133              return false;
 134          }
 135  
 136          $result = false;
 137          $eventdata = array('type' => $type, 'params' => $params, 'modification_result' => null);
 138          $evt = new Event('AUTH_USER_CHANGE', $eventdata);
 139          if ($evt->advise_before(true)) {
 140              $result = call_user_func_array(array($this, $validTypes[$type]), $evt->data['params']);
 141              $evt->data['modification_result'] = $result;
 142          }
 143          $evt->advise_after();
 144          unset($evt);
 145          return $result;
 146      }
 147  
 148      /**
 149       * Log off the current user [ OPTIONAL ]
 150       *
 151       * Is run in addition to the ususal logoff method. Should
 152       * only be needed when trustExternal is implemented.
 153       *
 154       * @see     auth_logoff()
 155       * @author  Andreas Gohr <andi@splitbrain.org>
 156       */
 157      public function logOff()
 158      {
 159      }
 160  
 161      /**
 162       * Do all authentication [ OPTIONAL ]
 163       *
 164       * Set $this->cando['external'] = true when implemented
 165       *
 166       * If this function is implemented it will be used to
 167       * authenticate a user - all other DokuWiki internals
 168       * will not be used for authenticating, thus
 169       * implementing the checkPass() function is not needed
 170       * anymore.
 171       *
 172       * The function can be used to authenticate against third
 173       * party cookies or Apache auth mechanisms and replaces
 174       * the auth_login() function
 175       *
 176       * The function will be called with or without a set
 177       * username. If the Username is given it was called
 178       * from the login form and the given credentials might
 179       * need to be checked. If no username was given it
 180       * the function needs to check if the user is logged in
 181       * by other means (cookie, environment).
 182       *
 183       * The function needs to set some globals needed by
 184       * DokuWiki like auth_login() does.
 185       *
 186       * @see     auth_login()
 187       * @author  Andreas Gohr <andi@splitbrain.org>
 188       *
 189       * @param   string $user Username
 190       * @param   string $pass Cleartext Password
 191       * @param   bool $sticky Cookie should not expire
 192       * @return  bool             true on successful auth
 193       */
 194      public function trustExternal($user, $pass, $sticky = false)
 195      {
 196          /* some example:
 197  
 198          global $USERINFO;
 199          global $conf;
 200          $sticky ? $sticky = true : $sticky = false; //sanity check
 201  
 202          // do the checking here
 203  
 204          // set the globals if authed
 205          $USERINFO['name'] = 'FIXME';
 206          $USERINFO['mail'] = 'FIXME';
 207          $USERINFO['grps'] = array('FIXME');
 208          $_SERVER['REMOTE_USER'] = $user;
 209          $_SESSION[DOKU_COOKIE]['auth']['user'] = $user;
 210          $_SESSION[DOKU_COOKIE]['auth']['pass'] = $pass;
 211          $_SESSION[DOKU_COOKIE]['auth']['info'] = $USERINFO;
 212          return true;
 213  
 214          */
 215      }
 216  
 217      /**
 218       * Check user+password [ MUST BE OVERRIDDEN ]
 219       *
 220       * Checks if the given user exists and the given
 221       * plaintext password is correct
 222       *
 223       * May be ommited if trustExternal is used.
 224       *
 225       * @author  Andreas Gohr <andi@splitbrain.org>
 226       * @param   string $user the user name
 227       * @param   string $pass the clear text password
 228       * @return  bool
 229       */
 230      public function checkPass($user, $pass)
 231      {
 232          msg("no valid authorisation system in use", -1);
 233          return false;
 234      }
 235  
 236      /**
 237       * Return user info [ MUST BE OVERRIDDEN ]
 238       *
 239       * Returns info about the given user needs to contain
 240       * at least these fields:
 241       *
 242       * name string  full name of the user
 243       * mail string  email address of the user
 244       * grps array   list of groups the user is in
 245       *
 246       * @author  Andreas Gohr <andi@splitbrain.org>
 247       * @param   string $user the user name
 248       * @param   bool $requireGroups whether or not the returned data must include groups
 249       * @return  false|array containing user data or false
 250       */
 251      public function getUserData($user, $requireGroups = true)
 252      {
 253          if (!$this->cando['external']) msg("no valid authorisation system in use", -1);
 254          return false;
 255      }
 256  
 257      /**
 258       * Create a new User [implement only where required/possible]
 259       *
 260       * Returns false if the user already exists, null when an error
 261       * occurred and true if everything went well.
 262       *
 263       * The new user HAS TO be added to the default group by this
 264       * function!
 265       *
 266       * Set addUser capability when implemented
 267       *
 268       * @author  Andreas Gohr <andi@splitbrain.org>
 269       * @param  string $user
 270       * @param  string $pass
 271       * @param  string $name
 272       * @param  string $mail
 273       * @param  null|array $grps
 274       * @return bool|null
 275       */
 276      public function createUser($user, $pass, $name, $mail, $grps = null)
 277      {
 278          msg("authorisation method does not allow creation of new users", -1);
 279          return null;
 280      }
 281  
 282      /**
 283       * Modify user data [implement only where required/possible]
 284       *
 285       * Set the mod* capabilities according to the implemented features
 286       *
 287       * @author  Chris Smith <chris@jalakai.co.uk>
 288       * @param   string $user nick of the user to be changed
 289       * @param   array $changes array of field/value pairs to be changed (password will be clear text)
 290       * @return  bool
 291       */
 292      public function modifyUser($user, $changes)
 293      {
 294          msg("authorisation method does not allow modifying of user data", -1);
 295          return false;
 296      }
 297  
 298      /**
 299       * Delete one or more users [implement only where required/possible]
 300       *
 301       * Set delUser capability when implemented
 302       *
 303       * @author  Chris Smith <chris@jalakai.co.uk>
 304       * @param   array $users
 305       * @return  int    number of users deleted
 306       */
 307      public function deleteUsers($users)
 308      {
 309          msg("authorisation method does not allow deleting of users", -1);
 310          return 0;
 311      }
 312  
 313      /**
 314       * Return a count of the number of user which meet $filter criteria
 315       * [should be implemented whenever retrieveUsers is implemented]
 316       *
 317       * Set getUserCount capability when implemented
 318       *
 319       * @author Chris Smith <chris@jalakai.co.uk>
 320       * @param  array $filter array of field/pattern pairs, empty array for no filter
 321       * @return int
 322       */
 323      public function getUserCount($filter = array())
 324      {
 325          msg("authorisation method does not provide user counts", -1);
 326          return 0;
 327      }
 328  
 329      /**
 330       * Bulk retrieval of user data [implement only where required/possible]
 331       *
 332       * Set getUsers capability when implemented
 333       *
 334       * @author  Chris Smith <chris@jalakai.co.uk>
 335       * @param   int $start index of first user to be returned
 336       * @param   int $limit max number of users to be returned, 0 for unlimited
 337       * @param   array $filter array of field/pattern pairs, null for no filter
 338       * @return  array list of userinfo (refer getUserData for internal userinfo details)
 339       */
 340      public function retrieveUsers($start = 0, $limit = 0, $filter = null)
 341      {
 342          msg("authorisation method does not support mass retrieval of user data", -1);
 343          return array();
 344      }
 345  
 346      /**
 347       * Define a group [implement only where required/possible]
 348       *
 349       * Set addGroup capability when implemented
 350       *
 351       * @author  Chris Smith <chris@jalakai.co.uk>
 352       * @param   string $group
 353       * @return  bool
 354       */
 355      public function addGroup($group)
 356      {
 357          msg("authorisation method does not support independent group creation", -1);
 358          return false;
 359      }
 360  
 361      /**
 362       * Retrieve groups [implement only where required/possible]
 363       *
 364       * Set getGroups capability when implemented
 365       *
 366       * @author  Chris Smith <chris@jalakai.co.uk>
 367       * @param   int $start
 368       * @param   int $limit
 369       * @return  array
 370       */
 371      public function retrieveGroups($start = 0, $limit = 0)
 372      {
 373          msg("authorisation method does not support group list retrieval", -1);
 374          return array();
 375      }
 376  
 377      /**
 378       * Return case sensitivity of the backend [OPTIONAL]
 379       *
 380       * When your backend is caseinsensitive (eg. you can login with USER and
 381       * user) then you need to overwrite this method and return false
 382       *
 383       * @return bool
 384       */
 385      public function isCaseSensitive()
 386      {
 387          return true;
 388      }
 389  
 390      /**
 391       * Sanitize a given username [OPTIONAL]
 392       *
 393       * This function is applied to any user name that is given to
 394       * the backend and should also be applied to any user name within
 395       * the backend before returning it somewhere.
 396       *
 397       * This should be used to enforce username restrictions.
 398       *
 399       * @author Andreas Gohr <andi@splitbrain.org>
 400       * @param string $user username
 401       * @return string the cleaned username
 402       */
 403      public function cleanUser($user)
 404      {
 405          return $user;
 406      }
 407  
 408      /**
 409       * Sanitize a given groupname [OPTIONAL]
 410       *
 411       * This function is applied to any groupname that is given to
 412       * the backend and should also be applied to any groupname within
 413       * the backend before returning it somewhere.
 414       *
 415       * This should be used to enforce groupname restrictions.
 416       *
 417       * Groupnames are to be passed without a leading '@' here.
 418       *
 419       * @author Andreas Gohr <andi@splitbrain.org>
 420       * @param  string $group groupname
 421       * @return string the cleaned groupname
 422       */
 423      public function cleanGroup($group)
 424      {
 425          return $group;
 426      }
 427  
 428      /**
 429       * Check Session Cache validity [implement only where required/possible]
 430       *
 431       * DokuWiki caches user info in the user's session for the timespan defined
 432       * in $conf['auth_security_timeout'].
 433       *
 434       * This makes sure slow authentication backends do not slow down DokuWiki.
 435       * This also means that changes to the user database will not be reflected
 436       * on currently logged in users.
 437       *
 438       * To accommodate for this, the user manager plugin will touch a reference
 439       * file whenever a change is submitted. This function compares the filetime
 440       * of this reference file with the time stored in the session.
 441       *
 442       * This reference file mechanism does not reflect changes done directly in
 443       * the backend's database through other means than the user manager plugin.
 444       *
 445       * Fast backends might want to return always false, to force rechecks on
 446       * each page load. Others might want to use their own checking here. If
 447       * unsure, do not override.
 448       *
 449       * @param  string $user - The username
 450       * @author Andreas Gohr <andi@splitbrain.org>
 451       * @return bool
 452       */
 453      public function useSessionCache($user)
 454      {
 455          global $conf;
 456          return ($_SESSION[DOKU_COOKIE]['auth']['time'] >= @filemtime($conf['cachedir'] . '/sessionpurge'));
 457      }
 458  }