[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Authentication plugin interface
   4   *
   5   * Copyright © 2004 Brion Vibber <[email protected]>
   6   * https://www.mediawiki.org/
   7   *
   8   * This program is free software; you can redistribute it and/or modify
   9   * it under the terms of the GNU General Public License as published by
  10   * the Free Software Foundation; either version 2 of the License, or
  11   * (at your option) any later version.
  12   *
  13   * This program is distributed in the hope that it will be useful,
  14   * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16   * GNU General Public License for more details.
  17   *
  18   * You should have received a copy of the GNU General Public License along
  19   * with this program; if not, write to the Free Software Foundation, Inc.,
  20   * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  21   * http://www.gnu.org/copyleft/gpl.html
  22   *
  23   * @file
  24   */
  25  
  26  /**
  27   * Authentication plugin interface. Instantiate a subclass of AuthPlugin
  28   * and set $wgAuth to it to authenticate against some external tool.
  29   *
  30   * The default behavior is not to do anything, and use the local user
  31   * database for all authentication. A subclass can require that all
  32   * accounts authenticate externally, or use it only as a fallback; also
  33   * you can transparently create internal wiki accounts the first time
  34   * someone logs in who can be authenticated externally.
  35   */
  36  class AuthPlugin {
  37      /**
  38       * @var string
  39       */
  40      protected $domain;
  41  
  42      /**
  43       * Check whether there exists a user account with the given name.
  44       * The name will be normalized to MediaWiki's requirements, so
  45       * you might need to munge it (for instance, for lowercase initial
  46       * letters).
  47       *
  48       * @param string $username Username.
  49       * @return bool
  50       */
  51  	public function userExists( $username ) {
  52          # Override this!
  53          return false;
  54      }
  55  
  56      /**
  57       * Check if a username+password pair is a valid login.
  58       * The name will be normalized to MediaWiki's requirements, so
  59       * you might need to munge it (for instance, for lowercase initial
  60       * letters).
  61       *
  62       * @param string $username Username.
  63       * @param string $password User password.
  64       * @return bool
  65       */
  66  	public function authenticate( $username, $password ) {
  67          # Override this!
  68          return false;
  69      }
  70  
  71      /**
  72       * Modify options in the login template.
  73       *
  74       * @param UserLoginTemplate $template
  75       * @param string $type 'signup' or 'login'. Added in 1.16.
  76       */
  77  	public function modifyUITemplate( &$template, &$type ) {
  78          # Override this!
  79          $template->set( 'usedomain', false );
  80      }
  81  
  82      /**
  83       * Set the domain this plugin is supposed to use when authenticating.
  84       *
  85       * @param string $domain Authentication domain.
  86       */
  87  	public function setDomain( $domain ) {
  88          $this->domain = $domain;
  89      }
  90  
  91      /**
  92       * Get the user's domain
  93       *
  94       * @return string
  95       */
  96  	public function getDomain() {
  97          if ( isset( $this->domain ) ) {
  98              return $this->domain;
  99          } else {
 100              return 'invaliddomain';
 101          }
 102      }
 103  
 104      /**
 105       * Check to see if the specific domain is a valid domain.
 106       *
 107       * @param string $domain Authentication domain.
 108       * @return bool
 109       */
 110  	public function validDomain( $domain ) {
 111          # Override this!
 112          return true;
 113      }
 114  
 115      /**
 116       * When a user logs in, optionally fill in preferences and such.
 117       * For instance, you might pull the email address or real name from the
 118       * external user database.
 119       *
 120       * The User object is passed by reference so it can be modified; don't
 121       * forget the & on your function declaration.
 122       *
 123       * @param User $user
 124       * @return bool
 125       */
 126  	public function updateUser( &$user ) {
 127          # Override this and do something
 128          return true;
 129      }
 130  
 131      /**
 132       * Return true if the wiki should create a new local account automatically
 133       * when asked to login a user who doesn't exist locally but does in the
 134       * external auth database.
 135       *
 136       * If you don't automatically create accounts, you must still create
 137       * accounts in some way. It's not possible to authenticate without
 138       * a local account.
 139       *
 140       * This is just a question, and shouldn't perform any actions.
 141       *
 142       * @return bool
 143       */
 144  	public function autoCreate() {
 145          return false;
 146      }
 147  
 148      /**
 149       * Allow a property change? Properties are the same as preferences
 150       * and use the same keys. 'Realname' 'Emailaddress' and 'Nickname'
 151       * all reference this.
 152       *
 153       * @param string $prop
 154       *
 155       * @return bool
 156       */
 157  	public function allowPropChange( $prop = '' ) {
 158          if ( $prop == 'realname' && is_callable( array( $this, 'allowRealNameChange' ) ) ) {
 159              return $this->allowRealNameChange();
 160          } elseif ( $prop == 'emailaddress' && is_callable( array( $this, 'allowEmailChange' ) ) ) {
 161              return $this->allowEmailChange();
 162          } elseif ( $prop == 'nickname' && is_callable( array( $this, 'allowNickChange' ) ) ) {
 163              return $this->allowNickChange();
 164          } else {
 165              return true;
 166          }
 167      }
 168  
 169      /**
 170       * Can users change their passwords?
 171       *
 172       * @return bool
 173       */
 174  	public function allowPasswordChange() {
 175          return true;
 176      }
 177  
 178      /**
 179       * Should MediaWiki store passwords in its local database?
 180       *
 181       * @return bool
 182       */
 183  	public function allowSetLocalPassword() {
 184          return true;
 185      }
 186  
 187      /**
 188       * Set the given password in the authentication database.
 189       * As a special case, the password may be set to null to request
 190       * locking the password to an unusable value, with the expectation
 191       * that it will be set later through a mail reset or other method.
 192       *
 193       * Return true if successful.
 194       *
 195       * @param User $user
 196       * @param string $password Password.
 197       * @return bool
 198       */
 199  	public function setPassword( $user, $password ) {
 200          return true;
 201      }
 202  
 203      /**
 204       * Update user information in the external authentication database.
 205       * Return true if successful.
 206       *
 207       * @param User $user
 208       * @return bool
 209       */
 210  	public function updateExternalDB( $user ) {
 211          return true;
 212      }
 213  
 214      /**
 215       * Update user groups in the external authentication database.
 216       * Return true if successful.
 217       *
 218       * @param User $user
 219       * @param array $addgroups Groups to add.
 220       * @param array $delgroups Groups to remove.
 221       * @return bool
 222       */
 223  	public function updateExternalDBGroups( $user, $addgroups, $delgroups = array() ) {
 224          return true;
 225      }
 226  
 227      /**
 228       * Check to see if external accounts can be created.
 229       * Return true if external accounts can be created.
 230       * @return bool
 231       */
 232  	public function canCreateAccounts() {
 233          return false;
 234      }
 235  
 236      /**
 237       * Add a user to the external authentication database.
 238       * Return true if successful.
 239       *
 240       * @param User $user Only the name should be assumed valid at this point
 241       * @param string $password
 242       * @param string $email
 243       * @param string $realname
 244       * @return bool
 245       */
 246  	public function addUser( $user, $password, $email = '', $realname = '' ) {
 247          return true;
 248      }
 249  
 250      /**
 251       * Return true to prevent logins that don't authenticate here from being
 252       * checked against the local database's password fields.
 253       *
 254       * This is just a question, and shouldn't perform any actions.
 255       *
 256       * @return bool
 257       */
 258  	public function strict() {
 259          return false;
 260      }
 261  
 262      /**
 263       * Check if a user should authenticate locally if the global authentication fails.
 264       * If either this or strict() returns true, local authentication is not used.
 265       *
 266       * @param string $username Username.
 267       * @return bool
 268       */
 269  	public function strictUserAuth( $username ) {
 270          return false;
 271      }
 272  
 273      /**
 274       * When creating a user account, optionally fill in preferences and such.
 275       * For instance, you might pull the email address or real name from the
 276       * external user database.
 277       *
 278       * The User object is passed by reference so it can be modified; don't
 279       * forget the & on your function declaration.
 280       *
 281       * @param User $user
 282       * @param bool $autocreate True if user is being autocreated on login
 283       */
 284  	public function initUser( &$user, $autocreate = false ) {
 285          # Override this to do something.
 286      }
 287  
 288      /**
 289       * If you want to munge the case of an account name before the final
 290       * check, now is your chance.
 291       * @param string $username
 292       * @return string
 293       */
 294  	public function getCanonicalName( $username ) {
 295          return $username;
 296      }
 297  
 298      /**
 299       * Get an instance of a User object
 300       *
 301       * @param User $user
 302       *
 303       * @return AuthPluginUser
 304       */
 305  	public function getUserInstance( User &$user ) {
 306          return new AuthPluginUser( $user );
 307      }
 308  
 309      /**
 310       * Get a list of domains (in HTMLForm options format) used.
 311       *
 312       * @return array
 313       */
 314  	public function domainList() {
 315          return array();
 316      }
 317  }
 318  
 319  class AuthPluginUser {
 320  	function __construct( $user ) {
 321          # Override this!
 322      }
 323  
 324  	public function getId() {
 325          # Override this!
 326          return -1;
 327      }
 328  
 329  	public function isLocked() {
 330          # Override this!
 331          return false;
 332      }
 333  
 334  	public function isHidden() {
 335          # Override this!
 336          return false;
 337      }
 338  
 339  	public function resetAuthToken() {
 340          # Override this!
 341          return true;
 342      }
 343  }