includes/ExternalUser.php

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