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
|
<?php
/**
* Secondary authentication provider interface
*
* 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
* @ingroup Auth
*/
namespace MediaWiki\Auth;
use StatusValue;
use User;
/**
* A secondary provider mostly acts when the submitted authentication data has
* already been associated to a MediaWiki user account.
*
* For login, a secondary provider performs additional authentication steps
* after a PrimaryAuthenticationProvider has identified which MediaWiki user is
* trying to log in. For example, it might implement a password reset, request
* the second factor for two-factor auth, or prevent the login if the account is blocked.
*
* For account creation, a secondary provider performs optional extra steps after
* a PrimaryAuthenticationProvider has created the user; for example, it can collect
* further user information such as a biography.
*
* (For account linking, secondary providers are not involved.)
*
* This interface also provides methods for changing authentication data such
* as a second-factor token, and callbacks that are invoked after login / account creation
* succeeded or failed.
*
* @ingroup Auth
* @since 1.27
* @see https://www.mediawiki.org/wiki/Manual:SessionManager_and_AuthManager
*/
interface SecondaryAuthenticationProvider extends AuthenticationProvider {
/**
* Start an authentication flow
*
* Note that this may be called for a user even if
* beginSecondaryAccountCreation() was never called. The module should take
* the opportunity to do any necessary setup in that case.
*
* @param User $user User being authenticated. This may become a
* "UserValue" in the future, or User may be refactored into such.
* @param AuthenticationRequest[] $reqs
* @return AuthenticationResponse Expected responses:
* - PASS: The user is authenticated. Additional secondary providers may run.
* - FAIL: The user is not authenticated. Fail the authentication process.
* - ABSTAIN: Additional secondary providers may run.
* - UI: Additional AuthenticationRequests are needed to complete the process.
* - REDIRECT: Redirection to a third party is needed to complete the process.
*/
public function beginSecondaryAuthentication( $user, array $reqs );
/**
* Continue an authentication flow
* @param User $user User being authenticated. This may become a
* "UserValue" in the future, or User may be refactored into such.
* @param AuthenticationRequest[] $reqs
* @return AuthenticationResponse Expected responses:
* - PASS: The user is authenticated. Additional secondary providers may run.
* - FAIL: The user is not authenticated. Fail the authentication process.
* - ABSTAIN: Additional secondary providers may run.
* - UI: Additional AuthenticationRequests are needed to complete the process.
* - REDIRECT: Redirection to a third party is needed to complete the process.
*/
public function continueSecondaryAuthentication( $user, array $reqs );
/**
* Post-login callback
*
* This will be called at the end of a login attempt. It will not be called for unfinished
* login attempts that fail by the session timing out.
*
* @param User|null $user User that was attempted to be logged in, if known.
* This may become a "UserValue" in the future, or User may be refactored
* into such.
* @param AuthenticationResponse $response Authentication response that will be returned
* (PASS or FAIL)
*/
public function postAuthentication( $user, AuthenticationResponse $response );
/**
* Revoke the user's credentials
*
* This may cause the user to no longer exist for the provider, or the user
* may continue to exist in a "disabled" state.
*
* The intention is that the named account will never again be usable for
* normal login (i.e. there is no way to undo the revocation of access).
*
* @param string $username
*/
public function providerRevokeAccessForUser( $username );
/**
* Determine whether a property can change
* @see AuthManager::allowsPropertyChange()
* @param string $property
* @return bool
*/
public function providerAllowsPropertyChange( $property );
/**
* Validate a change of authentication data (e.g. passwords)
*
* Return StatusValue::newGood( 'ignored' ) if you don't support this
* AuthenticationRequest type.
*
* @param AuthenticationRequest $req
* @param bool $checkData If false, $req hasn't been loaded from the
* submission so checks on user-submitted fields should be skipped.
* $req->username is considered user-submitted for this purpose, even
* if it cannot be changed via $req->loadFromSubmission.
* @return StatusValue
*/
public function providerAllowsAuthenticationDataChange(
AuthenticationRequest $req, $checkData = true
);
/**
* Change or remove authentication data (e.g. passwords)
*
* If $req was returned for AuthManager::ACTION_CHANGE, the corresponding
* credentials should result in a successful login in the future.
*
* If $req was returned for AuthManager::ACTION_REMOVE, the corresponding
* credentials should no longer result in a successful login.
*
* It can be assumed that providerAllowsAuthenticationDataChange with $checkData === true
* was called before this, and passed. This method should never fail (other than throwing an
* exception).
*
* @param AuthenticationRequest $req
*/
public function providerChangeAuthenticationData( AuthenticationRequest $req );
/**
* Determine whether an account creation may begin
*
* Called from AuthManager::beginAccountCreation()
*
* @note No need to test if the account exists, AuthManager checks that
* @param User $user User being created (not added to the database yet).
* This may become a "UserValue" in the future, or User may be refactored
* into such.
* @param User $creator User doing the creation. This may become a
* "UserValue" in the future, or User may be refactored into such.
* @param AuthenticationRequest[] $reqs
* @return StatusValue
*/
public function testForAccountCreation( $user, $creator, array $reqs );
/**
* Start an account creation flow
*
* @note There is no guarantee this will be called in a successful account
* creation process as the user can just abandon the process at any time
* after the primary provider has issued a PASS and still have a valid
* account. Be prepared to handle any database inconsistencies that result
* from this or continueSecondaryAccountCreation() not being called.
* @param User $user User being created (has been added to the database).
* This may become a "UserValue" in the future, or User may be refactored
* into such.
* @param User $creator User doing the creation. This may become a
* "UserValue" in the future, or User may be refactored into such.
* @param AuthenticationRequest[] $reqs
* @return AuthenticationResponse Expected responses:
* - PASS: The user creation is ok. Additional secondary providers may run.
* - ABSTAIN: Additional secondary providers may run.
* - UI: Additional AuthenticationRequests are needed to complete the process.
* - REDIRECT: Redirection to a third party is needed to complete the process.
*/
public function beginSecondaryAccountCreation( $user, $creator, array $reqs );
/**
* Continue an authentication flow
*
* @param User $user User being created (has been added to the database).
* This may become a "UserValue" in the future, or User may be refactored
* into such.
* @param User $creator User doing the creation. This may become a
* "UserValue" in the future, or User may be refactored into such.
* @param AuthenticationRequest[] $reqs
* @return AuthenticationResponse Expected responses:
* - PASS: The user creation is ok. Additional secondary providers may run.
* - ABSTAIN: Additional secondary providers may run.
* - UI: Additional AuthenticationRequests are needed to complete the process.
* - REDIRECT: Redirection to a third party is needed to complete the process.
*/
public function continueSecondaryAccountCreation( $user, $creator, array $reqs );
/**
* Post-creation callback
*
* This will be called at the end of an account creation attempt. It will not be called if
* the account creation process results in a session timeout (possibly after a successful
* user creation, while a secondary provider is waiting for a response).
*
* @param User $user User that was attempted to be created.
* This may become a "UserValue" in the future, or User may be refactored
* into such.
* @param User $creator User doing the creation. This may become a
* "UserValue" in the future, or User may be refactored into such.
* @param AuthenticationResponse $response Authentication response that will be returned
* (PASS or FAIL)
*/
public function postAccountCreation( $user, $creator, AuthenticationResponse $response );
/**
* Determine whether an account may be created
*
* @param User $user User being created (not added to the database yet).
* This may become a "UserValue" in the future, or User may be refactored
* into such.
* @param bool|string $autocreate False if this is not an auto-creation, or
* the source of the auto-creation passed to AuthManager::autoCreateUser().
* @param array $options
* - flags: (int) Bitfield of User:READ_* constants, default User::READ_NORMAL
* - creating: (bool) If false (or missing), this call is only testing if
* a user could be created. If set, this (non-autocreation) is for
* actually creating an account and will be followed by a call to
* testForAccountCreation(). In this case, the provider might return
* StatusValue::newGood() here and let the later call to
* testForAccountCreation() do a more thorough test.
* @return StatusValue
*/
public function testUserForCreation( $user, $autocreate, array $options = [] );
/**
* Post-auto-creation callback
* @param User $user User being created (has been added to the database now).
* This may become a "UserValue" in the future, or User may be refactored
* into such.
* @param string $source The source of the auto-creation passed to
* AuthManager::autoCreateUser().
*/
public function autoCreatedAccount( $user, $source );
}
|
