3 * Primary authentication provider interface
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.
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.
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
24 namespace MediaWiki\Auth
;
30 * A primary authentication provider determines which user is trying to log in.
32 * A PrimaryAuthenticationProvider is used as part of presenting a login form
33 * to authenticate a user. In particular, the PrimaryAuthenticationProvider
34 * takes form data and determines the authenticated user (if any) corresponds
35 * to that form data. It might do this on the basis of a username and password
36 * in that data, or by interacting with an external authentication service
37 * (e.g. using OpenID), or by some other mechanism.
39 * A PrimaryAuthenticationProvider would not be appropriate for something like
40 * HTTP authentication, OAuth, or SSL client certificates where each HTTP
41 * request contains all the information needed to identify the user. In that
42 * case you'll want to be looking at a \\MediaWiki\\Session\\SessionProvider
45 * This interface also provides methods for changing authentication data such
46 * as passwords and for creating new users who can later be authenticated with
52 interface PrimaryAuthenticationProvider
extends AuthenticationProvider
{
53 /** Provider can create accounts */
54 const TYPE_CREATE
= 'create';
55 /** Provider can link to existing accounts elsewhere */
56 const TYPE_LINK
= 'link';
57 /** Provider cannot create or link to accounts */
58 const TYPE_NONE
= 'none';
63 * Of the requests returned by this method, exactly one should have
64 * {@link AuthenticationRequest::$required} set to REQUIRED.
66 public function getAuthenticationRequests( $action, array $options );
69 * Start an authentication flow
71 * @param AuthenticationRequest[] $reqs
72 * @return AuthenticationResponse Expected responses:
73 * - PASS: The user is authenticated. Secondary providers will now run.
74 * - FAIL: The user is not authenticated. Fail the authentication process.
75 * - ABSTAIN: These $reqs are not handled. Some other primary provider may handle it.
76 * - UI: The $reqs are accepted, no other primary provider will run.
77 * Additional AuthenticationRequests are needed to complete the process.
78 * - REDIRECT: The $reqs are accepted, no other primary provider will run.
79 * Redirection to a third party is needed to complete the process.
81 public function beginPrimaryAuthentication( array $reqs );
84 * Continue an authentication flow
85 * @param AuthenticationRequest[] $reqs
86 * @return AuthenticationResponse Expected responses:
87 * - PASS: The user is authenticated. Secondary providers will now run.
88 * - FAIL: The user is not authenticated. Fail the authentication process.
89 * - UI: Additional AuthenticationRequests are needed to complete the process.
90 * - REDIRECT: Redirection to a third party is needed to complete the process.
92 public function continuePrimaryAuthentication( array $reqs );
96 * @param User|null $user User that was attempted to be logged in, if known.
97 * This may become a "UserValue" in the future, or User may be refactored
99 * @param AuthenticationResponse $response Authentication response that will be returned
101 public function postAuthentication( $user, AuthenticationResponse
$response );
104 * Test whether the named user exists
105 * @param string $username
106 * @param int $flags Bitfield of User:READ_* constants
109 public function testUserExists( $username, $flags = User
::READ_NORMAL
);
112 * Test whether the named user can authenticate with this provider
113 * @param string $username
116 public function testUserCanAuthenticate( $username );
119 * Normalize the username for authentication
121 * Any two inputs that would result in the same user being authenticated
122 * should return the same string here, while inputs that would result in
123 * different users should return different strings.
125 * If possible, the best thing to do here is to return the canonicalized
126 * name of the local user account that would be used. If not, return
127 * something that would be invalid as a local username (e.g. wrap an email
128 * address in "<>", or append "#servicename" to the username passed to a
129 * third-party service).
131 * If the provider doesn't use a username at all in its
132 * AuthenticationRequests, return null. If the name is syntactically
133 * invalid, it's probably best to return null.
135 * @param string $username
136 * @return string|null
138 public function providerNormalizeUsername( $username );
141 * Revoke the user's credentials
143 * This may cause the user to no longer exist for the provider, or the user
144 * may continue to exist in a "disabled" state.
146 * The intention is that the named account will never again be usable for
147 * normal login (i.e. there is no way to undo the revocation of access).
149 * @param string $username
151 public function providerRevokeAccessForUser( $username );
154 * Determine whether a property can change
155 * @see AuthManager::allowsPropertyChange()
156 * @param string $property
159 public function providerAllowsPropertyChange( $property );
162 * Validate a change of authentication data (e.g. passwords)
164 * Return StatusValue::newGood( 'ignored' ) if you don't support this
165 * AuthenticationRequest type.
167 * @param AuthenticationRequest $req
168 * @param bool $checkData If false, $req hasn't been loaded from the
169 * submission so checks on user-submitted fields should be skipped.
170 * $req->username is considered user-submitted for this purpose, even
171 * if it cannot be changed via $req->loadFromSubmission.
172 * @return StatusValue
174 public function providerAllowsAuthenticationDataChange(
175 AuthenticationRequest
$req, $checkData = true
179 * Change or remove authentication data (e.g. passwords)
181 * If $req was returned for AuthManager::ACTION_CHANGE, the corresponding
182 * credentials should result in a successful login in the future.
184 * If $req was returned for AuthManager::ACTION_REMOVE, the corresponding
185 * credentials should no longer result in a successful login.
187 * @param AuthenticationRequest $req
189 public function providerChangeAuthenticationData( AuthenticationRequest
$req );
192 * Fetch the account-creation type
193 * @return string One of the TYPE_* constants
195 public function accountCreationType();
198 * Determine whether an account creation may begin
200 * Called from AuthManager::beginAccountCreation()
202 * @note No need to test if the account exists, AuthManager checks that
203 * @param User $user User being created (not added to the database yet).
204 * This may become a "UserValue" in the future, or User may be refactored
206 * @param User $creator User doing the creation. This may become a
207 * "UserValue" in the future, or User may be refactored into such.
208 * @param AuthenticationRequest[] $reqs
209 * @return StatusValue
211 public function testForAccountCreation( $user, $creator, array $reqs );
214 * Start an account creation flow
215 * @param User $user User being created (not added to the database yet).
216 * This may become a "UserValue" in the future, or User may be refactored
218 * @param User $creator User doing the creation. This may become a
219 * "UserValue" in the future, or User may be refactored into such.
220 * @param AuthenticationRequest[] $reqs
221 * @return AuthenticationResponse Expected responses:
222 * - PASS: The user may be created. Secondary providers will now run.
223 * - FAIL: The user may not be created. Fail the creation process.
224 * - ABSTAIN: These $reqs are not handled. Some other primary provider may handle it.
225 * - UI: The $reqs are accepted, no other primary provider will run.
226 * Additional AuthenticationRequests are needed to complete the process.
227 * - REDIRECT: The $reqs are accepted, no other primary provider will run.
228 * Redirection to a third party is needed to complete the process.
230 public function beginPrimaryAccountCreation( $user, $creator, array $reqs );
233 * Continue an account creation flow
234 * @param User $user User being created (not added to the database yet).
235 * This may become a "UserValue" in the future, or User may be refactored
237 * @param User $creator User doing the creation. This may become a
238 * "UserValue" in the future, or User may be refactored into such.
239 * @param AuthenticationRequest[] $reqs
240 * @return AuthenticationResponse Expected responses:
241 * - PASS: The user may be created. Secondary providers will now run.
242 * - FAIL: The user may not be created. Fail the creation process.
243 * - UI: Additional AuthenticationRequests are needed to complete the process.
244 * - REDIRECT: Redirection to a third party is needed to complete the process.
246 public function continuePrimaryAccountCreation( $user, $creator, array $reqs );
249 * Post-creation callback
251 * Called after the user is added to the database, before secondary
252 * authentication providers are run.
254 * @param User $user User being created (has been added to the database now).
255 * This may become a "UserValue" in the future, or User may be refactored
257 * @param User $creator User doing the creation. This may become a
258 * "UserValue" in the future, or User may be refactored into such.
259 * @param AuthenticationResponse $response PASS response returned earlier
260 * @return string|null 'newusers' log subtype to use for logging the
261 * account creation. If null, either 'create' or 'create2' will be used
262 * depending on $creator.
264 public function finishAccountCreation( $user, $creator, AuthenticationResponse
$response );
267 * Post-creation callback
269 * Called when the account creation process ends.
271 * @param User $user User that was attempted to be created.
272 * This may become a "UserValue" in the future, or User may be refactored
274 * @param User $creator User doing the creation. This may become a
275 * "UserValue" in the future, or User may be refactored into such.
276 * @param AuthenticationResponse $response Authentication response that will be returned
278 public function postAccountCreation( $user, $creator, AuthenticationResponse
$response );
281 * Determine whether an account may be created
283 * @param User $user User being created (not added to the database yet).
284 * This may become a "UserValue" in the future, or User may be refactored
286 * @param bool|string $autocreate False if this is not an auto-creation, or
287 * the source of the auto-creation passed to AuthManager::autoCreateUser().
288 * @param array $options
289 * - flags: (int) Bitfield of User:READ_* constants, default User::READ_NORMAL
290 * - creating: (bool) If false (or missing), this call is only testing if
291 * a user could be created. If set, this (non-autocreation) is for
292 * actually creating an account and will be followed by a call to
293 * testForAccountCreation(). In this case, the provider might return
294 * StatusValue::newGood() here and let the later call to
295 * testForAccountCreation() do a more thorough test.
296 * @return StatusValue
298 public function testUserForCreation( $user, $autocreate, array $options = [] );
301 * Post-auto-creation callback
302 * @param User $user User being created (has been added to the database now).
303 * This may become a "UserValue" in the future, or User may be refactored
305 * @param string $source The source of the auto-creation passed to
306 * AuthManager::autoCreateUser().
308 public function autoCreatedAccount( $user, $source );
311 * Start linking an account to an existing user
312 * @param User $user User being linked.
313 * This may become a "UserValue" in the future, or User may be refactored
315 * @param AuthenticationRequest[] $reqs
316 * @return AuthenticationResponse Expected responses:
317 * - PASS: The user is linked.
318 * - FAIL: The user is not linked. Fail the linking process.
319 * - ABSTAIN: These $reqs are not handled. Some other primary provider may handle it.
320 * - UI: The $reqs are accepted, no other primary provider will run.
321 * Additional AuthenticationRequests are needed to complete the process.
322 * - REDIRECT: The $reqs are accepted, no other primary provider will run.
323 * Redirection to a third party is needed to complete the process.
325 public function beginPrimaryAccountLink( $user, array $reqs );
328 * Continue linking an account to an existing user
329 * @param User $user User being linked.
330 * This may become a "UserValue" in the future, or User may be refactored
332 * @param AuthenticationRequest[] $reqs
333 * @return AuthenticationResponse Expected responses:
334 * - PASS: The user is linked.
335 * - FAIL: The user is not linked. Fail the linking process.
336 * - UI: Additional AuthenticationRequests are needed to complete the process.
337 * - REDIRECT: Redirection to a third party is needed to complete the process.
339 public function continuePrimaryAccountLink( $user, array $reqs );
343 * @param User $user User that was attempted to be linked.
344 * This may become a "UserValue" in the future, or User may be refactored
346 * @param AuthenticationResponse $response Authentication response that will be returned
348 public function postAccountLink( $user, AuthenticationResponse
$response );