summaryrefslogtreecommitdiff
path: root/includes/ExternalUser.php
blob: 580b98966a7ad9d9228db26ec0d23c83b8e00eee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
<?php
/**
 * Authentication with a foreign database
 *
 * Copyright © 2009 Aryeh Gregor
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @file
 */

/**
 * @defgroup ExternalUser ExternalUser
 */

/**
 * A class intended to supplement, and perhaps eventually replace, AuthPlugin.
 * See: http://www.mediawiki.org/wiki/ExternalAuth
 *
 * The class represents a user whose data is in a foreign database.  The
 * database may have entirely different conventions from MediaWiki, but it's
 * assumed to at least support the concept of a user id (possibly not an
 * integer), a user name (possibly not meeting MediaWiki's username
 * requirements), and a password.
 *
 * @ingroup ExternalUser
 */
abstract class ExternalUser {
	protected function __construct() {}

	/**
	 * Wrappers around initFrom*().
	 */

	/**
	 * @param $name string
	 * @return mixed ExternalUser, or false on failure
	 */
	public static function newFromName( $name ) {
		global $wgExternalAuthType;
		if ( is_null( $wgExternalAuthType ) ) {
			return false;
		}
		$obj = new $wgExternalAuthType;
		if ( !$obj->initFromName( $name ) ) {
			return false;
		}
		return $obj;
	}

	/**
	 * @param $id string
	 * @return mixed ExternalUser, or false on failure
	 */
	public static function newFromId( $id ) {
		global $wgExternalAuthType;
		if ( is_null( $wgExternalAuthType ) ) {
			return false;
		}
		$obj = new $wgExternalAuthType;
		if ( !$obj->initFromId( $id ) ) {
			return false;
		}
		return $obj;
	}

	/**
	 * @return mixed ExternalUser, or false on failure
	 */
	public static function newFromCookie() {
		global $wgExternalAuthType;
		if ( is_null( $wgExternalAuthType ) ) {
			return false;
		}
		$obj = new $wgExternalAuthType;
		if ( !$obj->initFromCookie() ) {
			return false;
		}
		return $obj;
	}

	/**
	 * Creates the object corresponding to the given User object, assuming the
	 * user exists on the wiki and is linked to an external account.  If either
	 * of these is false, this will return false.
	 *
	 * This is a wrapper around newFromId().
	 *
	 * @param $user User
	 * @return ExternalUser|bool False on failure
	 */
	public static function newFromUser( $user ) {
		global $wgExternalAuthType;
		if ( is_null( $wgExternalAuthType ) ) {
			# Short-circuit to avoid database query in common case so no one
			# kills me
			return false;
		}

		$dbr = wfGetDB( DB_SLAVE );
		$id = $dbr->selectField( 'external_user', 'eu_external_id',
			array( 'eu_local_id' => $user->getId() ), __METHOD__ );
		if ( $id === false ) {
			return false;
		}
		return self::newFromId( $id );
	}

	/**
	 * Given a name, which is a string exactly as input by the user in the
	 * login form but with whitespace stripped, initialize this object to be
	 * the corresponding ExternalUser.  Return true if successful, otherwise
	 * false.
	 *
	 * @param $name string
	 * @return bool Success?
	 */
	abstract protected function initFromName( $name );

	/**
	 * Given an id, which was at some previous point in history returned by
	 * getId(), initialize this object to be the corresponding ExternalUser.
	 * Return true if successful, false otherwise.
	 *
	 * @param $id string
	 * @return bool Success?
	 */
	abstract protected function initFromId( $id );

	/**
	 * Try to magically initialize the user from cookies or similar information
	 * so he or she can be logged in on just viewing the wiki.  If this is
	 * impossible to do, just return false.
	 *
	 * TODO: Actually use this.
	 *
	 * @return bool Success?
	 */
	protected function initFromCookie() {
		return false;
	}

	/**
	 * This must return some identifier that stably, uniquely identifies the
	 * user.  In a typical web application, this could be an integer
	 * representing the "user id".  In other cases, it might be a string.  In
	 * any event, the return value should be a string between 1 and 255
	 * characters in length; must uniquely identify the user in the foreign
	 * database; and, if at all possible, should be permanent.
	 *
	 * This will only ever be used to reconstruct this ExternalUser object via
	 * newFromId().  The resulting object in that case should correspond to the
	 * same user, even if details have changed in the interim (e.g., renames or
	 * preference changes).
	 *
	 * @return string
	 */
	abstract public function getId();

	/**
	 * This must return the name that the user would normally use for login to
	 * the external database.  It is subject to no particular restrictions
	 * beyond rudimentary sanity, and in particular may be invalid as a
	 * MediaWiki username.  It's used to auto-generate an account name that
	 * *is* valid for MediaWiki, either with or without user input, but
	 * basically is only a hint.
	 *
	 * @return string
	 */
	abstract public function getName();

	/**
	 * Is the given password valid for the external user?  The password is
	 * provided in plaintext.
	 *
	 * @param $password string
	 * @return bool
	 */
	abstract public function authenticate( $password );

	/**
	 * Retrieve the value corresponding to the given preference key.  The most
	 * important values are:
	 *
	 * - emailaddress
	 * - language
	 *
	 * The value must meet MediaWiki's requirements for values of this type,
	 * and will be checked for validity before use.  If the preference makes no
	 * sense for the backend, or it makes sense but is unset for this user, or
	 * is unrecognized, return null.
	 *
	 * $pref will never equal 'password', since passwords are usually hashed
	 * and cannot be directly retrieved.  authenticate() is used for this
	 * instead.
	 *
	 * TODO: Currently this is only called for 'emailaddress'; generalize!  Add
	 * some config option to decide which values are grabbed on user
	 * initialization.
	 *
	 * @param $pref string
	 * @return mixed
	 */
	public function getPref( $pref ) {
		return null;
	}

	/**
	 * Return an array of identifiers for all the foreign groups that this user
	 * has.  The identifiers are opaque objects that only need to be
	 * specifiable by the administrator in LocalSettings.php when configuring
	 * $wgAutopromote.  They may be, for instance, strings or integers.
	 *
	 * TODO: Support this in $wgAutopromote.
	 *
	 * @return array
	 */
	public function getGroups() {
		return array();
	}

	/**
	 * Given a preference key (e.g., 'emailaddress'), provide an HTML message
	 * telling the user how to change it in the external database.  The
	 * administrator has specified that this preference cannot be changed on
	 * the wiki, and may only be changed in the foreign database.  If no
	 * message is available, such as for an unrecognized preference, return
	 * false.
	 *
	 * TODO: Use this somewhere.
	 *
	 * @param $pref string
	 * @return mixed String or false
	 */
	public static function getPrefMessage( $pref ) {
		return false;
	}

	/**
	 * Set the given preference key to the given value.  Two important
	 * preference keys that you might want to implement are 'password' and
	 * 'emailaddress'.  If the set fails, such as because the preference is
	 * unrecognized or because the external database can't be changed right
	 * now, return false.  If it succeeds, return true.
	 *
	 * If applicable, you should make sure to validate the new value against
	 * any constraints the external database may have, since MediaWiki may have
	 * more limited constraints (e.g., on password strength).
	 *
	 * TODO: Untested.
	 *
	 * @param $key string
	 * @param $value string
	 * @return bool Success?
	 */
	public static function setPref( $key, $value ) {
		return false;
	}

	/**
	 * Create a link for future reference between this object and the provided
	 * user_id.  If the user was already linked, the old link will be
	 * overwritten.
	 *
	 * This is part of the core code and is not overridable by specific
	 * plugins.  It's in this class only for convenience.
	 *
	 * @param int $id user_id
	 */
	final public function linkToLocal( $id ) {
		$dbw = wfGetDB( DB_MASTER );
		$dbw->replace( 'external_user',
			array( 'eu_local_id', 'eu_external_id' ),
			array( 'eu_local_id' => $id,
				'eu_external_id' => $this->getId() ),
			__METHOD__ );
	}

	/**
	 * Check whether this external user id is already linked with
	 * a local user.
	 * @return Mixed User if the account is linked, Null otherwise.
	 */
	final public function getLocalUser() {
		$dbr = wfGetDB( DB_SLAVE );
		$row = $dbr->selectRow(
			'external_user',
			'*',
			array( 'eu_external_id' => $this->getId() )
		);
		return $row
			? User::newFromId( $row->eu_local_id )
			: null;
	}

}