3 * Authentication plugin interface
5 * Copyright © 2004 Brion Vibber <brion@pobox.com>
6 * https://www.mediawiki.org/
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License along
19 * with this program; if not, write to the Free Software Foundation, Inc.,
20 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21 * http://www.gnu.org/copyleft/gpl.html
27 * Authentication plugin interface. Instantiate a subclass of AuthPlugin
28 * and set $wgAuth to it to authenticate against some external tool.
30 * The default behavior is not to do anything, and use the local user
31 * database for all authentication. A subclass can require that all
32 * accounts authenticate externally, or use it only as a fallback; also
33 * you can transparently create internal wiki accounts the first time
34 * someone logs in who can be authenticated externally.
43 * Check whether there exists a user account with the given name.
44 * The name will be normalized to MediaWiki's requirements, so
45 * you might need to munge it (for instance, for lowercase initial
48 * @param string $username Username.
51 public function userExists( $username ) {
57 * Check if a username+password pair is a valid login.
58 * The name will be normalized to MediaWiki's requirements, so
59 * you might need to munge it (for instance, for lowercase initial
62 * @param string $username Username.
63 * @param string $password User password.
66 public function authenticate( $username, $password ) {
72 * Modify options in the login template.
74 * @param UserLoginTemplate $template
75 * @param string $type 'signup' or 'login'. Added in 1.16.
77 public function modifyUITemplate( &$template, &$type ) {
79 $template->set( 'usedomain', false );
83 * Set the domain this plugin is supposed to use when authenticating.
85 * @param string $domain Authentication domain.
87 public function setDomain( $domain ) {
88 $this->domain
= $domain;
92 * Get the user's domain
96 public function getDomain() {
97 if ( isset( $this->domain
) ) {
100 return 'invaliddomain';
105 * Check to see if the specific domain is a valid domain.
107 * @param string $domain Authentication domain.
110 public function validDomain( $domain ) {
116 * When a user logs in, optionally fill in preferences and such.
117 * For instance, you might pull the email address or real name from the
118 * external user database.
120 * The User object is passed by reference so it can be modified; don't
121 * forget the & on your function declaration.
123 * @deprecated since 1.26, use the UserLoggedIn hook instead. And assigning
124 * a different User object to $user is no longer supported.
128 public function updateUser( &$user ) {
129 # Override this and do something
134 * Return true if the wiki should create a new local account automatically
135 * when asked to login a user who doesn't exist locally but does in the
136 * external auth database.
138 * If you don't automatically create accounts, you must still create
139 * accounts in some way. It's not possible to authenticate without
142 * This is just a question, and shouldn't perform any actions.
146 public function autoCreate() {
151 * Allow a property change? Properties are the same as preferences
152 * and use the same keys. 'Realname' 'Emailaddress' and 'Nickname'
153 * all reference this.
155 * @param string $prop
159 public function allowPropChange( $prop = '' ) {
160 if ( $prop == 'realname' && is_callable( [ $this, 'allowRealNameChange' ] ) ) {
161 return $this->allowRealNameChange();
162 } elseif ( $prop == 'emailaddress' && is_callable( [ $this, 'allowEmailChange' ] ) ) {
163 return $this->allowEmailChange();
164 } elseif ( $prop == 'nickname' && is_callable( [ $this, 'allowNickChange' ] ) ) {
165 return $this->allowNickChange();
172 * Can users change their passwords?
176 public function allowPasswordChange() {
181 * Should MediaWiki store passwords in its local database?
185 public function allowSetLocalPassword() {
190 * Set the given password in the authentication database.
191 * As a special case, the password may be set to null to request
192 * locking the password to an unusable value, with the expectation
193 * that it will be set later through a mail reset or other method.
195 * Return true if successful.
198 * @param string $password Password.
201 public function setPassword( $user, $password ) {
206 * Update user information in the external authentication database.
207 * Return true if successful.
209 * @deprecated since 1.26, use the UserSaveSettings hook instead.
213 public function updateExternalDB( $user ) {
218 * Update user groups in the external authentication database.
219 * Return true if successful.
221 * @deprecated since 1.26, use the UserGroupsChanged hook instead.
223 * @param array $addgroups Groups to add.
224 * @param array $delgroups Groups to remove.
227 public function updateExternalDBGroups( $user, $addgroups, $delgroups = [] ) {
232 * Check to see if external accounts can be created.
233 * Return true if external accounts can be created.
236 public function canCreateAccounts() {
241 * Add a user to the external authentication database.
242 * Return true if successful.
244 * @param User $user Only the name should be assumed valid at this point
245 * @param string $password
246 * @param string $email
247 * @param string $realname
250 public function addUser( $user, $password, $email = '', $realname = '' ) {
255 * Return true to prevent logins that don't authenticate here from being
256 * checked against the local database's password fields.
258 * This is just a question, and shouldn't perform any actions.
262 public function strict() {
267 * Check if a user should authenticate locally if the global authentication fails.
268 * If either this or strict() returns true, local authentication is not used.
270 * @param string $username Username.
273 public function strictUserAuth( $username ) {
278 * When creating a user account, optionally fill in preferences and such.
279 * For instance, you might pull the email address or real name from the
280 * external user database.
282 * The User object is passed by reference so it can be modified; don't
283 * forget the & on your function declaration.
285 * @deprecated since 1.26, use the UserLoggedIn hook instead. And assigning
286 * a different User object to $user is no longer supported.
288 * @param bool $autocreate True if user is being autocreated on login
290 public function initUser( &$user, $autocreate = false ) {
291 # Override this to do something.
295 * If you want to munge the case of an account name before the final
296 * check, now is your chance.
297 * @param string $username
300 public function getCanonicalName( $username ) {
305 * Get an instance of a User object
309 * @return AuthPluginUser
311 public function getUserInstance( User
&$user ) {
312 return new AuthPluginUser( $user );
316 * Get a list of domains (in HTMLForm options format) used.
320 public function domainList() {
325 class AuthPluginUser
{
326 function __construct( $user ) {
330 public function getId() {
336 * Indicate whether the user is locked
337 * @deprecated since 1.26, use the UserIsLocked hook instead.
340 public function isLocked() {
346 * Indicate whether the user is hidden
347 * @deprecated since 1.26, use the UserIsHidden hook instead.
350 public function isHidden() {
356 * @deprecated since 1.28, use SessionManager::invalidateSessionForUser() instead.
358 public function resetAuthToken() {