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
|
<?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 authentication provider performs additional authentication steps
* after a PrimaryAuthenticationProvider has done its thing.
*
* A SecondaryAuthenticationProvider is used to perform arbitrary checks on an
* authentication request after the user itself has been authenticated. 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.
*
* @ingroup Auth
* @since 1.27
*/
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
* @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
*/
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.
*
* @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
* @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
* @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
*/
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().
* @return StatusValue
*/
public function testUserForCreation( $user, $autocreate );
/**
* 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 );
}
|
