Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
Total | n/a |
0 / 0 |
n/a |
0 / 0 |
CRAP | n/a |
0 / 0 |
1 | <?php |
2 | /** |
3 | * Secondary authentication provider interface |
4 | * |
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. |
9 | * |
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. |
14 | * |
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 |
19 | * |
20 | * @file |
21 | * @ingroup Auth |
22 | */ |
23 | |
24 | namespace MediaWiki\Auth; |
25 | |
26 | use MediaWiki\User\User; |
27 | use StatusValue; |
28 | |
29 | /** |
30 | * A secondary provider mostly acts when the submitted authentication data has |
31 | * already been associated to a MediaWiki user account. |
32 | * |
33 | * For login, a secondary provider performs additional authentication steps |
34 | * after a PrimaryAuthenticationProvider has identified which MediaWiki user is |
35 | * trying to log in. For example, it might implement a password reset, request |
36 | * the second factor for two-factor auth, or prevent the login if the account is blocked. |
37 | * |
38 | * For account creation, a secondary provider performs optional extra steps after |
39 | * a PrimaryAuthenticationProvider has created the user; for example, it can collect |
40 | * further user information such as a biography. |
41 | * |
42 | * (For account linking, secondary providers are not involved.) |
43 | * |
44 | * This interface also provides methods for changing authentication data such |
45 | * as a second-factor token, and callbacks that are invoked after login / account creation |
46 | * succeeded or failed. |
47 | * |
48 | * @ingroup Auth |
49 | * @since 1.27 |
50 | * @see https://www.mediawiki.org/wiki/Manual:SessionManager_and_AuthManager |
51 | */ |
52 | interface SecondaryAuthenticationProvider extends AuthenticationProvider { |
53 | |
54 | /** |
55 | * Start an authentication flow |
56 | * |
57 | * Note that this may be called for a user even if |
58 | * beginSecondaryAccountCreation() was never called. The module should take |
59 | * the opportunity to do any necessary setup in that case. |
60 | * |
61 | * @param User $user User being authenticated. This may become a |
62 | * "UserValue" in the future, or User may be refactored into such. |
63 | * @param AuthenticationRequest[] $reqs |
64 | * @return AuthenticationResponse Expected responses: |
65 | * - PASS: The user is authenticated. Additional secondary providers may run. |
66 | * - FAIL: The user is not authenticated. Fail the authentication process. |
67 | * - ABSTAIN: Additional secondary providers may run. |
68 | * - UI: Additional AuthenticationRequests are needed to complete the process. |
69 | * - REDIRECT: Redirection to a third party is needed to complete the process. |
70 | */ |
71 | public function beginSecondaryAuthentication( $user, array $reqs ); |
72 | |
73 | /** |
74 | * Continue an authentication flow |
75 | * @param User $user User being authenticated. This may become a |
76 | * "UserValue" in the future, or User may be refactored into such. |
77 | * @param AuthenticationRequest[] $reqs |
78 | * @return AuthenticationResponse Expected responses: |
79 | * - PASS: The user is authenticated. Additional secondary providers may run. |
80 | * - FAIL: The user is not authenticated. Fail the authentication process. |
81 | * - ABSTAIN: Additional secondary providers may run. |
82 | * - UI: Additional AuthenticationRequests are needed to complete the process. |
83 | * - REDIRECT: Redirection to a third party is needed to complete the process. |
84 | */ |
85 | public function continueSecondaryAuthentication( $user, array $reqs ); |
86 | |
87 | /** |
88 | * Post-login callback |
89 | * |
90 | * This will be called at the end of a login attempt. It will not be called for unfinished |
91 | * login attempts that fail by the session timing out. |
92 | * |
93 | * @param User|null $user User that was attempted to be logged in, if known. |
94 | * This may become a "UserValue" in the future, or User may be refactored |
95 | * into such. |
96 | * @param AuthenticationResponse $response Authentication response that will be returned |
97 | * (PASS or FAIL) |
98 | */ |
99 | public function postAuthentication( $user, AuthenticationResponse $response ); |
100 | |
101 | /** |
102 | * Revoke the user's credentials |
103 | * |
104 | * This may cause the user to no longer exist for the provider, or the user |
105 | * may continue to exist in a "disabled" state. |
106 | * |
107 | * The intention is that the named account will never again be usable for |
108 | * normal login (i.e. there is no way to undo the revocation of access). |
109 | * |
110 | * @param string $username |
111 | */ |
112 | public function providerRevokeAccessForUser( $username ); |
113 | |
114 | /** |
115 | * Determine whether a property can change |
116 | * @see AuthManager::allowsPropertyChange() |
117 | * @param string $property |
118 | * @return bool |
119 | */ |
120 | public function providerAllowsPropertyChange( $property ); |
121 | |
122 | /** |
123 | * Validate a change of authentication data (e.g. passwords) |
124 | * |
125 | * Return StatusValue::newGood( 'ignored' ) if you don't support this |
126 | * AuthenticationRequest type. |
127 | * |
128 | * @param AuthenticationRequest $req |
129 | * @param bool $checkData If false, $req hasn't been loaded from the |
130 | * submission so checks on user-submitted fields should be skipped. |
131 | * $req->username is considered user-submitted for this purpose, even |
132 | * if it cannot be changed via $req->loadFromSubmission. |
133 | * @return StatusValue |
134 | */ |
135 | public function providerAllowsAuthenticationDataChange( |
136 | AuthenticationRequest $req, $checkData = true |
137 | ); |
138 | |
139 | /** |
140 | * Change or remove authentication data (e.g. passwords) |
141 | * |
142 | * If $req was returned for AuthManager::ACTION_CHANGE, the corresponding |
143 | * credentials should result in a successful login in the future. |
144 | * |
145 | * If $req was returned for AuthManager::ACTION_REMOVE, the corresponding |
146 | * credentials should no longer result in a successful login. |
147 | * |
148 | * It can be assumed that providerAllowsAuthenticationDataChange with $checkData === true |
149 | * was called before this, and passed. This method should never fail (other than throwing an |
150 | * exception). |
151 | * |
152 | * @param AuthenticationRequest $req |
153 | */ |
154 | public function providerChangeAuthenticationData( AuthenticationRequest $req ); |
155 | |
156 | /** |
157 | * Determine whether an account creation may begin |
158 | * |
159 | * Called from AuthManager::beginAccountCreation() |
160 | * |
161 | * @note No need to test if the account exists, AuthManager checks that |
162 | * @param User $user User being created (not added to the database yet). |
163 | * This may become a "UserValue" in the future, or User may be refactored |
164 | * into such. |
165 | * @param User $creator User doing the creation. This may become a |
166 | * "UserValue" in the future, or User may be refactored into such. |
167 | * @param AuthenticationRequest[] $reqs |
168 | * @return StatusValue |
169 | */ |
170 | public function testForAccountCreation( $user, $creator, array $reqs ); |
171 | |
172 | /** |
173 | * Start an account creation flow |
174 | * |
175 | * @note There is no guarantee this will be called in a successful account |
176 | * creation process as the user can just abandon the process at any time |
177 | * after the primary provider has issued a PASS and still have a valid |
178 | * account. Be prepared to handle any database inconsistencies that result |
179 | * from this or continueSecondaryAccountCreation() not being called. |
180 | * @param User $user User being created (has been added to the database). |
181 | * This may become a "UserValue" in the future, or User may be refactored |
182 | * into such. |
183 | * @param User $creator User doing the creation. This may become a |
184 | * "UserValue" in the future, or User may be refactored into such. |
185 | * @param AuthenticationRequest[] $reqs |
186 | * @return AuthenticationResponse Expected responses: |
187 | * - PASS: The user creation is ok. Additional secondary providers may run. |
188 | * - ABSTAIN: Additional secondary providers may run. |
189 | * - UI: Additional AuthenticationRequests are needed to complete the process. |
190 | * - REDIRECT: Redirection to a third party is needed to complete the process. |
191 | */ |
192 | public function beginSecondaryAccountCreation( $user, $creator, array $reqs ); |
193 | |
194 | /** |
195 | * Continue an authentication flow |
196 | * |
197 | * @param User $user User being created (has been added to the database). |
198 | * This may become a "UserValue" in the future, or User may be refactored |
199 | * into such. |
200 | * @param User $creator User doing the creation. This may become a |
201 | * "UserValue" in the future, or User may be refactored into such. |
202 | * @param AuthenticationRequest[] $reqs |
203 | * @return AuthenticationResponse Expected responses: |
204 | * - PASS: The user creation is ok. Additional secondary providers may run. |
205 | * - ABSTAIN: Additional secondary providers may run. |
206 | * - UI: Additional AuthenticationRequests are needed to complete the process. |
207 | * - REDIRECT: Redirection to a third party is needed to complete the process. |
208 | */ |
209 | public function continueSecondaryAccountCreation( $user, $creator, array $reqs ); |
210 | |
211 | /** |
212 | * Post-creation callback |
213 | * |
214 | * This will be called at the end of an account creation attempt. It will not be called if |
215 | * the account creation process results in a session timeout (possibly after a successful |
216 | * user creation, while a secondary provider is waiting for a response). |
217 | * |
218 | * @param User $user User that was attempted to be created. |
219 | * This may become a "UserValue" in the future, or User may be refactored |
220 | * into such. |
221 | * @param User $creator User doing the creation. This may become a |
222 | * "UserValue" in the future, or User may be refactored into such. |
223 | * @param AuthenticationResponse $response Authentication response that will be returned |
224 | * (PASS or FAIL) |
225 | */ |
226 | public function postAccountCreation( $user, $creator, AuthenticationResponse $response ); |
227 | |
228 | /** |
229 | * Determine whether an account may be created |
230 | * |
231 | * @param User $user User being created (not added to the database yet). |
232 | * This may become a "UserValue" in the future, or User may be refactored |
233 | * into such. |
234 | * @param bool|string $autocreate False if this is not an auto-creation, or |
235 | * the source of the auto-creation passed to AuthManager::autoCreateUser(). |
236 | * @param array $options |
237 | * - flags: (int) Bitfield of IDBAccessObject::READ_* constants, default IDBAccessObject::READ_NORMAL |
238 | * - creating: (bool) If false (or missing), this call is only testing if |
239 | * a user could be created. If set, this (non-autocreation) is for |
240 | * actually creating an account and will be followed by a call to |
241 | * testForAccountCreation(). In this case, the provider might return |
242 | * StatusValue::newGood() here and let the later call to |
243 | * testForAccountCreation() do a more thorough test. |
244 | * @return StatusValue |
245 | */ |
246 | public function testUserForCreation( $user, $autocreate, array $options = [] ); |
247 | |
248 | /** |
249 | * Post-auto-creation callback |
250 | * @param User $user User being created (has been added to the database now). |
251 | * This may become a "UserValue" in the future, or User may be refactored |
252 | * into such. |
253 | * @param string $source The source of the auto-creation passed to |
254 | * AuthManager::autoCreateUser(). |
255 | */ |
256 | public function autoCreatedAccount( $user, $source ); |
257 | |
258 | } |