includes/ExternalUser.php

   1 <?php
   2
   3 # Copyright (C) 2009 Aryeh Gregor
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License along
  16 # with this program; if not, write to the Free Software Foundation, Inc.,
  17 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18 # http://www.gnu.org/copyleft/gpl.html
  19
  20 /**
  21  * A class intended to supplement, and perhaps eventually replace, AuthPlugin.
  22  * See: http://www.mediawiki.org/wiki/ExternalAuth
  23  *
  24  * The class represents a user whose data is in a foreign database.  The
  25  * database may have entirely different conventions from MediaWiki, but it's
  26  * assumed to at least support the concept of a user id (possibly not an
  27  * integer), a user name (possibly not meeting MediaWiki's username
  28  * requirements), and a password.
  29  */
  30 abstract class ExternalUser {
  31         protected function __construct() {}
  32
  33         /**
  34          * Wrappers around initFrom*().
  35          */
  36
  37         /**
  38          * @param $name string
  39          * @return mixed ExternalUser, or false on failure
  40          */
  41         public static function newFromName( $name ) {
  42                 global $wgExternalAuthType;
  43                 if ( is_null( $wgExternalAuthType ) ) {
  44                         return false;
  45                 }
  46                 $obj = new $wgExternalAuthType;
  47                 if ( !$obj->initFromName( $name ) ) {
  48                         return false;
  49                 }
  50                 return $obj;
  51         }
  52
  53         /**
  54          * @param $id string
  55          * @return mixed ExternalUser, or false on failure
  56          */
  57         public static function newFromId( $id ) {
  58                 global $wgExternalAuthType;
  59                 if ( is_null( $wgExternalAuthType ) ) {
  60                         return false;
  61                 }
  62                 $obj = new $wgExternalAuthType;
  63                 if ( !$obj->initFromId( $id ) ) {
  64                         return false;
  65                 }
  66                 return $obj;
  67         }
  68
  69         /**
  70          * @param $cookie string
  71          * @return mixed ExternalUser, or false on failure
  72          */
  73         public static function newFromCookie() {
  74                 global $wgExternalAuthType;
  75                 if ( is_null( $wgExternalAuthType ) ) {
  76                         return false;
  77                 }
  78                 $obj = new $wgExternalAuthType;
  79                 if ( !$obj->initFromCookie() ) {
  80                         return false;
  81                 }
  82                 return $obj;
  83         }
  84
  85         /**
  86          * Creates the object corresponding to the given User object, assuming the
  87          * user exists on the wiki and is linked to an external account.  If either
  88          * of these is false, this will return false.
  89          *
  90          * This is a wrapper around newFromId().
  91          *
  92          * @param $user User
  93          * @return mixed ExternalUser or false
  94          */
  95         public static function newFromUser( $user ) {
  96                 global $wgExternalAuthType;
  97                 if ( is_null( $wgExternalAuthType ) ) {
  98                         # Short-circuit to avoid database query in common case so no one
  99                         # kills me
 100                         return false;
 101                 }
 102
 103                 $dbr = wfGetDB( DB_SLAVE );
 104                 $id = $dbr->selectField( 'external_user', 'eu_external_id',
 105                         array( 'eu_local_id' => $user->getId() ), __METHOD__ );
 106                 if ( $id === false ) {
 107                         return false;
 108                 }
 109                 return self::newFromId( $id );
 110         }
 111
 112         /**
 113          * Given a name, which is a string exactly as input by the user in the
 114          * login form but with whitespace stripped, initialize this object to be
 115          * the corresponding ExternalUser.  Return true if successful, otherwise
 116          * false.
 117          *
 118          * @param $name string
 119          * @return bool Success?
 120          */
 121         protected abstract function initFromName( $name );
 122
 123         /**
 124          * Given an id, which was at some previous point in history returned by
 125          * getId(), initialize this object to be the corresponding ExternalUser.
 126          * Return true if successful, false otherwise.
 127          *
 128          * @param $id string
 129          * @return bool Success?
 130          */
 131         protected abstract function initFromId( $id );
 132
 133         /**
 134          * Try to magically initialize the user from cookies or similar information
 135          * so he or she can be logged in on just viewing the wiki.  If this is
 136          * impossible to do, just return false.
 137          *
 138          * TODO: Actually use this.
 139          *
 140          * @return bool Success?
 141          */
 142         protected function initFromCookie() {
 143                 return false;
 144         }
 145
 146         /**
 147          * This must return some identifier that stably, uniquely identifies the
 148          * user.  In a typical web application, this could be an integer
 149          * representing the "user id".  In other cases, it might be a string.  In
 150          * any event, the return value should be a string between 1 and 255
 151          * characters in length; must uniquely identify the user in the foreign
 152          * database; and, if at all possible, should be permanent.
 153          *
 154          * This will only ever be used to reconstruct this ExternalUser object via
 155          * newFromId().  The resulting object in that case should correspond to the
 156          * same user, even if details have changed in the interim (e.g., renames or
 157          * preference changes).
 158          *
 159          * @return string
 160          */
 161         abstract public function getId();
 162
 163         /**
 164          * This must return the name that the user would normally use for login to
 165          * the external database.  It is subject to no particular restrictions
 166          * beyond rudimentary sanity, and in particular may be invalid as a
 167          * MediaWiki username.  It's used to auto-generate an account name that
 168          * *is* valid for MediaWiki, either with or without user input, but
 169          * basically is only a hint.
 170          *
 171          * @return string
 172          */
 173         abstract public function getName();
 174
 175         /**
 176          * Is the given password valid for the external user?  The password is
 177          * provided in plaintext.
 178          *
 179          * @param $password string
 180          * @return bool
 181          */
 182         abstract public function authenticate( $password );
 183
 184         /**
 185          * Retrieve the value corresponding to the given preference key.  The most
 186          * important values are:
 187          *
 188          * - emailaddress
 189          * - language
 190          *
 191          * The value must meet MediaWiki's requirements for values of this type,
 192          * and will be checked for validity before use.  If the preference makes no
 193          * sense for the backend, or it makes sense but is unset for this user, or
 194          * is unrecognized, return null.
 195          *
 196          * $pref will never equal 'password', since passwords are usually hashed
 197          * and cannot be directly retrieved.  authenticate() is used for this
 198          * instead.
 199          *
 200          * TODO: Currently this is only called for 'emailaddress'; generalize!  Add
 201          * some config option to decide which values are grabbed on user
 202          * initialization.
 203          *
 204          * @param $pref string
 205          * @return mixed
 206          */
 207         public function getPref( $pref ) {
 208                 return null;
 209         }
 210
 211         /**
 212          * Return an array of identifiers for all the foreign groups that this user
 213          * has.  The identifiers are opaque objects that only need to be
 214          * specifiable by the administrator in LocalSettings.php when configuring
 215          * $wgAutopromote.  They may be, for instance, strings or integers.
 216          *
 217          * TODO: Support this in $wgAutopromote.
 218          *
 219          * @return array
 220          */
 221         public function getGroups() {
 222                 return array();
 223         }
 224
 225         /**
 226          * Given a preference key (e.g., 'emailaddress'), provide an HTML message
 227          * telling the user how to change it in the external database.  The
 228          * administrator has specified that this preference cannot be changed on
 229          * the wiki, and may only be changed in the foreign database.  If no
 230          * message is available, such as for an unrecognized preference, return
 231          * false.
 232          *
 233          * TODO: Use this somewhere.
 234          *
 235          * @param $pref string
 236          * @return mixed String or false
 237          */
 238         public static function getPrefMessage( $pref ) {
 239                 return false;
 240         }
 241
 242         /**
 243          * Set the given preference key to the given value.  Two important
 244          * preference keys that you might want to implement are 'password' and
 245          * 'emailaddress'.  If the set fails, such as because the preference is
 246          * unrecognized or because the external database can't be changed right
 247          * now, return false.  If it succeeds, return true.
 248          *
 249          * If applicable, you should make sure to validate the new value against
 250          * any constraints the external database may have, since MediaWiki may have
 251          * more limited constraints (e.g., on password strength).
 252          *
 253          * TODO: Untested.
 254          *
 255          * @param $key string
 256          * @param $value string
 257          * @return bool Success?
 258          */
 259         public static function setPref( $key, $value ) {
 260                 return false;
 261         }
 262
 263         /**
 264          * Create a link for future reference between this object and the provided
 265          * user_id.  If the user was already linked, the old link will be
 266          * overwritten.
 267          *
 268          * This is part of the core code and is not overridable by specific
 269          * plugins.  It's in this class only for convenience.
 270          *
 271          * @param $id int user_id
 272          */
 273         public final function linkToLocal( $id ) {
 274                 $dbw = wfGetDB( DB_MASTER );
 275                 $dbw->replace( 'external_user',
 276                         array( 'eu_local_id', 'eu_external_id' ),
 277                         array( 'eu_local_id' => $id,
 278                                    'eu_external_id' => $this->getId() ),
 279                         __METHOD__ );
 280         }
 281
 282         /**
 283          * Check whether this external user id is already linked with
 284          * a local user.
 285          * @return Mixed User if the account is linked, Null otherwise.
 286          */
 287         public final function getLocalUser(){
 288                 $dbr = wfGetDb( DB_SLAVE );
 289                 $row = $dbr->selectRow(
 290                         'external_user',
 291                         '*',
 292                         array( 'eu_external_id' => $this->getId() )
 293                 );
 294                 return $row
 295                         ? User::newFromId( $row->eu_local_id )
 296                         : null;
 297         }
 298
 299 }