3 * Authentication with a foreign database
5 * Copyright © 2009 Aryeh Gregor
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.
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.
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
26 * @defgroup ExternalUser ExternalUser
30 * A class intended to supplement, and perhaps eventually replace, AuthPlugin.
31 * See: http://www.mediawiki.org/wiki/ExternalAuth
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.
39 * @ingroup ExternalUser
41 abstract class ExternalUser
{
42 protected function __construct() {}
45 * Wrappers around initFrom*().
50 * @return mixed ExternalUser, or false on failure
52 public static function newFromName( $name ) {
53 global $wgExternalAuthType;
54 if ( is_null( $wgExternalAuthType ) ) {
57 $obj = new $wgExternalAuthType;
58 if ( !$obj->initFromName( $name ) ) {
66 * @return mixed ExternalUser, or false on failure
68 public static function newFromId( $id ) {
69 global $wgExternalAuthType;
70 if ( is_null( $wgExternalAuthType ) ) {
73 $obj = new $wgExternalAuthType;
74 if ( !$obj->initFromId( $id ) ) {
81 * @return mixed ExternalUser, or false on failure
83 public static function newFromCookie() {
84 global $wgExternalAuthType;
85 if ( is_null( $wgExternalAuthType ) ) {
88 $obj = new $wgExternalAuthType;
89 if ( !$obj->initFromCookie() ) {
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.
100 * This is a wrapper around newFromId().
103 * @return ExternalUser|bool False on failure
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
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 ) {
119 return self
::newFromId( $id );
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
128 * @param $name string
129 * @return bool Success?
131 protected abstract function initFromName( $name );
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.
139 * @return bool Success?
141 protected abstract function initFromId( $id );
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.
148 * TODO: Actually use this.
150 * @return bool Success?
152 protected function initFromCookie() {
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.
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).
171 abstract public function getId();
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.
183 abstract public function getName();
186 * Is the given password valid for the external user? The password is
187 * provided in plaintext.
189 * @param $password string
192 abstract public function authenticate( $password );
195 * Retrieve the value corresponding to the given preference key. The most
196 * important values are:
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.
206 * $pref will never equal 'password', since passwords are usually hashed
207 * and cannot be directly retrieved. authenticate() is used for this
210 * TODO: Currently this is only called for 'emailaddress'; generalize! Add
211 * some config option to decide which values are grabbed on user
214 * @param $pref string
217 public function getPref( $pref ) {
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.
227 * TODO: Support this in $wgAutopromote.
231 public function getGroups() {
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
243 * TODO: Use this somewhere.
245 * @param $pref string
246 * @return mixed String or false
248 public static function getPrefMessage( $pref ) {
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.
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).
266 * @param $value string
267 * @return bool Success?
269 public static function setPref( $key, $value ) {
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
278 * This is part of the core code and is not overridable by specific
279 * plugins. It's in this class only for convenience.
281 * @param $id int user_id
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() ),
293 * Check whether this external user id is already linked with
295 * @return Mixed User if the account is linked, Null otherwise.
297 public final function getLocalUser(){
298 $dbr = wfGetDB( DB_SLAVE
);
299 $row = $dbr->selectRow(
302 array( 'eu_external_id' => $this->getId() )
305 ? User
::newFromId( $row->eu_local_id
)