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                 $class = "ExternalUser_$wgExternalAuthType";
  47                 $obj = new $class;
  48                 if ( !$obj->initFromName( $name ) ) {
  49                         return false;
  50                 }
  51                 return $obj;
  52         }
  53
  54         /**
  55          * @param $id string
  56          * @return mixed ExternalUser, or false on failure
  57          */
  58         public static function newFromId( $id ) {
  59                 global $wgExternalAuthType;
  60                 if ( is_null( $wgExternalAuthType ) ) {
  61                         return false;
  62                 }
  63                 $class = "ExternalUser_$wgExternalAuthType";
  64                 $obj = new $class;
  65                 if ( !$obj->initFromId( $id ) ) {
  66                         return false;
  67                 }
  68                 return $obj;
  69         }
  70
  71         /**
  72          * @param $cookie string
  73          * @return mixed ExternalUser, or false on failure
  74          */
  75         public static function newFromCookie( $cookie ) {
  76                 global $wgExternalAuthType;
  77                 if ( is_null( $wgExternalAuthType ) ) {
  78                         return false;
  79                 }
  80                 $class = "ExternalUser_$wgExternalAuthType";
  81                 $obj = new $class;
  82                 if ( !$obj->initFromCookie( $cookie ) ) {
  83                         return false;
  84                 }
  85                 return $obj;
  86         }
  87
  88         /**
  89          * Creates the object corresponding to the given User object, assuming the
  90          * user exists on the wiki and is linked to an external account.  If either
  91          * of these is false, this will return false.
  92          *
  93          * This is a wrapper around newFromId().
  94          *
  95          * @param $user User
  96          * @return mixed ExternalUser or false
  97          */
  98         public static function newFromUser( $user ) {
  99                 global $wgExternalAuthType;
 100                 if ( is_null( $wgExternalAuthType ) ) {
 101                         # Short-circuit to avoid database query in common case so no one
 102                         # kills me
 103                         return false;
 104                 }
 105
 106                 $dbr = wfGetDB( DB_SLAVE );
 107                 $id = $dbr->selectField( 'external_user', 'eu_external_id',
 108                         array( 'eu_wiki_id' => $user->getId() ), __METHOD__ );
 109                 if ( $id === false ) {
 110                         return false;
 111                 }
 112                 return self::newFromId( $id );
 113         }
 114
 115         /**
 116          * Given a name, which is a string exactly as input by the user in the
 117          * login form but with whitespace stripped, initialize this object to be
 118          * the corresponding ExternalUser.  Return true if successful, otherwise
 119          * false.
 120          *
 121          * @param $name string
 122          * @return bool Success?
 123          */
 124         protected abstract function initFromName( $name );
 125
 126         /**
 127          * Given an id, which was at some previous point in history returned by
 128          * getId(), initialize this object to be the corresponding ExternalUser.
 129          * Return true if successful, false otherwise.
 130          *
 131          * @param $id string
 132          * @return bool Success?
 133          */
 134         protected abstract function initFromId( $id );
 135
 136         /**
 137          * Given the user's cookie, initialize this object to the correct user if
 138          * the cookie indicates that the user is logged into the external database.
 139          * If successful, return true.  If the external database doesn't support
 140          * cookie-based authentication, or if the cookies don't belong to a
 141          * logged-in user, return false.
 142          *
 143          * TODO: Actually use this.
 144          *
 145          * @param $cookie string
 146          * @return bool Success?
 147          */
 148         protected function initFromCookie( $cookie ) {
 149                 return false;
 150         }
 151
 152         /**
 153          * This must return some identifier that stably, uniquely identifies the
 154          * user.  In a typical web application, this could be an integer
 155          * representing the "user id".  In other cases, it might be a string.  In
 156          * any event, the return value should be a string between 1 and 255
 157          * characters in length; must uniquely identify the user in the foreign
 158          * database; and, if at all possible, should be permanent.
 159          *
 160          * This will only ever be used to reconstruct this ExternalUser object via
 161          * newFromId().  The resulting object in that case should correspond to the
 162          * same user, even if details have changed in the interim (e.g., renames or
 163          * preference changes).
 164          *
 165          * @return string
 166          */
 167         abstract public function getId();
 168
 169         /**
 170          * This must return the name that the user would normally use for login to
 171          * the external database.  It is subject to no particular restrictions
 172          * beyond rudimentary sanity, and in particular may be invalid as a
 173          * MediaWiki username.  It's used to auto-generate an account name that
 174          * *is* valid for MediaWiki, either with or without user input, but
 175          * basically is only a hint.
 176          *
 177          * @return string
 178          */
 179         abstract public function getName();
 180
 181         /**
 182          * Is the given password valid for the external user?  The password is
 183          * provided in plaintext, with whitespace stripped but not otherwise
 184          * modified.
 185          *
 186          * @param $password string
 187          * @return bool
 188          */
 189         abstract public function authenticate( $password );
 190
 191         /**
 192          * Retrieve the value corresponding to the given preference key.  The most
 193          * important values are:
 194          *
 195          * - emailaddress
 196          * - language
 197          *
 198          * The value must meet MediaWiki's requirements for values of this type,
 199          * and will be checked for validity before use.  If the preference makes no
 200          * sense for the backend, or it makes sense but is unset for this user, or
 201          * is unrecognized, return null.
 202          *
 203          * $pref will never equal 'password', since passwords are usually hashed
 204          * and cannot be directly retrieved.  authenticate() is used for this
 205          * instead.
 206          *
 207          * TODO: Currently this is only called for 'emailaddress'; generalize!  Add
 208          * some config option to decide which values are grabbed on user
 209          * initialization.
 210          *
 211          * @param $pref string
 212          * @return mixed
 213          */
 214         public function getPref( $pref ) {
 215                 return null;
 216         }
 217
 218         /**
 219          * Return an array of identifiers for all the foreign groups that this user
 220          * has.  The identifiers are opaque objects that only need to be
 221          * specifiable by the administrator in LocalSettings.php when configuring
 222          * $wgAutopromote.  They may be, for instance, strings or integers.
 223          *
 224          * TODO: Support this in $wgAutopromote.
 225          *
 226          * @return array
 227          */
 228         public function getGroups() {
 229                 return array();
 230         }
 231
 232         /**
 233          * Given a preference key (e.g., 'emailaddress'), provide an HTML message
 234          * telling the user how to change it in the external database.  The
 235          * administrator has specified that this preference cannot be changed on
 236          * the wiki, and may only be changed in the foreign database.  If no
 237          * message is available, such as for an unrecognized preference, return
 238          * false.
 239          *
 240          * TODO: Use this somewhere.
 241          *
 242          * @param $pref string
 243          * @return mixed String or false
 244          */
 245         public static function prefMessage( $pref ) {
 246                 return false;
 247         }
 248
 249         /**
 250          * Set the given preference key to the given value.  Two important
 251          * preference keys that you might want to implement are 'password' and
 252          * 'emailaddress'.  If the set fails, such as because the preference is
 253          * unrecognized or because the external database can't be changed right
 254          * now, return false.  If it succeeds, return true.
 255          *
 256          * If applicable, you should make sure to validate the new value against
 257          * any constraints the external database may have, since MediaWiki may have
 258          * more limited constraints (e.g., on password strength).
 259          *
 260          * TODO: Untested.
 261          *
 262          * @param $key string
 263          * @param $value string
 264          * @return bool Success?
 265          */
 266         public static function setPref( $key, $value ) {
 267                 return false;
 268         }
 269
 270         /**
 271          * Create a link for future reference between this object and the provided
 272          * user_id.  If the user was already linked, the old link will be
 273          * overwritten.
 274          *
 275          * This is part of the core code and is not overridable by specific
 276          * plugins.  It's in this class only for convenience.
 277          *
 278          * @param $id int user_id
 279          */
 280         public final function link( $id ) {
 281                 $dbw = wfGetDB( DB_MASTER );
 282                 $dbw->replace( 'external_user',
 283                         array( 'eu_wiki_id', 'eu_external_id' ),
 284                         array( 'eu_wiki_id' => $id,
 285                                'eu_external_id' => $this->getId() ),
 286                     __METHOD__ );
 287         }
 288
 289         /**
 290          * Check whether this external user id is already linked with
 291          * a local user.
 292          * @return Mixed User if the account is linked, Null otherwise.
 293          */
 294         public final function getLocalUser(){
 295                 $dbr = wfGetDb( DB_SLAVE );
 296                 $row = $dbr->selectRow(
 297                         'external_user',
 298                         '*',
 299                         array( 'eu_external_id' => $this->getId() )
 300                 );
 301                 return $row
 302                         ? User::newFromId( $row->eu_wiki_id )
 303                         : null;
 304         }
 305
 306 }