3 * Authentication response value object
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
;
29 * This is a value object to hold authentication response data
31 * An AuthenticationResponse represents both the status of the authentication
32 * (success, failure, in progress) and it its state (what data is needed to continue).
37 class AuthenticationResponse
{
38 /** Indicates that the authentication succeeded. */
41 /** Indicates that the authentication failed. */
44 /** Indicates that third-party authentication succeeded but no user exists.
45 * Either treat this like a UI response or pass $this->createRequest to
46 * AuthManager::beginCreateAccount(). For use by AuthManager only (providers
47 * should just return a PASS with no username).
49 const RESTART
= 'RESTART';
51 /** Indicates that the authentication provider does not handle this request. */
52 const ABSTAIN
= 'ABSTAIN';
54 /** Indicates that the authentication needs further user input of some sort. */
57 /** Indicates that the authentication needs to be redirected to a third party to proceed. */
58 const REDIRECT
= 'REDIRECT';
60 /** @var string One of the constants above */
63 /** @var string|null URL to redirect to for a REDIRECT response */
64 public $redirectTarget = null;
67 * @var mixed Data for a REDIRECT response that a client might use to
68 * query the remote site via its API rather than by following $redirectTarget.
69 * Value must be something acceptable to ApiResult::addValue().
71 public $redirectApiData = null;
74 * @var AuthenticationRequest[] Needed AuthenticationRequests to continue
75 * after a UI or REDIRECT response. This plays the same role when continuing
76 * authentication as AuthManager::getAuthenticationRequests() does when
79 public $neededRequests = [];
81 /** @var Message|null I18n message to display in case of UI or FAIL */
82 public $message = null;
85 * @var string|null Local user name from authentication.
86 * May be null if the authentication passed but no local user is known.
88 public $username = null;
91 * @var AuthenticationRequest|null
93 * Returned with a PrimaryAuthenticationProvider login FAIL or a PASS with
94 * no username, this can be set to a request that should result in a PASS when
95 * passed to that provider's PrimaryAuthenticationProvider::beginPrimaryAccountCreation().
96 * The client will be able to send that back for expedited account creation where only
97 * the username needs to be filled.
99 * Returned with an AuthManager login FAIL or RESTART, this holds a
100 * CreateFromLoginAuthenticationRequest that may be passed to
101 * AuthManager::beginCreateAccount(), possibly in place of any
102 * "primary-required" requests. It may also be passed to
103 * AuthManager::beginAuthentication() to preserve the list of
104 * accounts which can be linked after success (see $linkRequest).
106 public $createRequest = null;
109 * @var AuthenticationRequest|null When returned with a PrimaryAuthenticationProvider
110 * login PASS with no username, the request this holds will be passed to
111 * AuthManager::changeAuthenticationData() once the local user has been determined and the
112 * user has confirmed the account ownership (by reviewing the information given by
113 * $linkRequest->describeCredentials()). The provider should handle that
114 * changeAuthenticationData() call by doing the actual linking.
116 public $linkRequest = null;
119 * @var AuthenticationRequest|null Returned with an AuthManager account
120 * creation PASS, this holds a request to pass to AuthManager::beginAuthentication()
121 * to immediately log into the created account. All provider methods except
122 * postAuthentication will be skipped.
124 public $loginRequest = null;
127 * @param string|null $username Local username
128 * @return AuthenticationResponse
129 * @see AuthenticationResponse::PASS
131 public static function newPass( $username = null ) {
132 $ret = new AuthenticationResponse
;
133 $ret->status
= AuthenticationResponse
::PASS
;
134 $ret->username
= $username;
139 * @param Message $msg
140 * @return AuthenticationResponse
141 * @see AuthenticationResponse::FAIL
143 public static function newFail( Message
$msg ) {
144 $ret = new AuthenticationResponse
;
145 $ret->status
= AuthenticationResponse
::FAIL
;
146 $ret->message
= $msg;
151 * @param Message $msg
152 * @return AuthenticationResponse
153 * @see AuthenticationResponse::RESTART
155 public static function newRestart( Message
$msg ) {
156 $ret = new AuthenticationResponse
;
157 $ret->status
= AuthenticationResponse
::RESTART
;
158 $ret->message
= $msg;
163 * @return AuthenticationResponse
164 * @see AuthenticationResponse::ABSTAIN
166 public static function newAbstain() {
167 $ret = new AuthenticationResponse
;
168 $ret->status
= AuthenticationResponse
::ABSTAIN
;
173 * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
174 * @param Message $msg
175 * @return AuthenticationResponse
176 * @see AuthenticationResponse::UI
178 public static function newUI( array $reqs, Message
$msg ) {
180 throw new \
InvalidArgumentException( '$reqs may not be empty' );
183 $ret = new AuthenticationResponse
;
184 $ret->status
= AuthenticationResponse
::UI
;
185 $ret->neededRequests
= $reqs;
186 $ret->message
= $msg;
191 * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
192 * @param string $redirectTarget URL
193 * @param mixed $redirectApiData Data suitable for adding to an ApiResult
194 * @return AuthenticationResponse
195 * @see AuthenticationResponse::REDIRECT
197 public static function newRedirect( array $reqs, $redirectTarget, $redirectApiData = null ) {
199 throw new \
InvalidArgumentException( '$reqs may not be empty' );
202 $ret = new AuthenticationResponse
;
203 $ret->status
= AuthenticationResponse
::REDIRECT
;
204 $ret->neededRequests
= $reqs;
205 $ret->redirectTarget
= $redirectTarget;
206 $ret->redirectApiData
= $redirectApiData;