includes/auth/AuthenticationResponse.php

   1 <?php
   2 /**
   3  * Authentication response value object
   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 Message;
  27
  28 /**
  29  * This is a value object to hold authentication response data
  30  *
  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).
  33  *
  34  * @ingroup Auth
  35  * @since 1.27
  36  */
  37 class AuthenticationResponse {
  38         /** Indicates that the authentication succeeded. */
  39         const PASS = 'PASS';
  40
  41         /** Indicates that the authentication failed. */
  42         const FAIL = 'FAIL';
  43
  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).
  48          */
  49         const RESTART = 'RESTART';
  50
  51         /** Indicates that the authentication provider does not handle this request. */
  52         const ABSTAIN = 'ABSTAIN';
  53
  54         /** Indicates that the authentication needs further user input of some sort. */
  55         const UI = 'UI';
  56
  57         /** Indicates that the authentication needs to be redirected to a third party to proceed. */
  58         const REDIRECT = 'REDIRECT';
  59
  60         /** @var string One of the constants above */
  61         public $status;
  62
  63         /** @var string|null URL to redirect to for a REDIRECT response */
  64         public $redirectTarget = null;
  65
  66         /**
  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().
  70          */
  71         public $redirectApiData = null;
  72
  73         /**
  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
  77          * beginning it.
  78          */
  79         public $neededRequests = [];
  80
  81         /** @var Message|null I18n message to display in case of UI or FAIL */
  82         public $message = null;
  83
  84         /** @var string Whether the $message is an error or warning message, for styling reasons */
  85         public $messageType = 'warning';
  86
  87         /**
  88          * @var string|null Local user name from authentication.
  89          * May be null if the authentication passed but no local user is known.
  90          */
  91         public $username = null;
  92
  93         /**
  94          * @var AuthenticationRequest|null
  95          *
  96          * Returned with a PrimaryAuthenticationProvider login FAIL or a PASS with
  97          * no username, this can be set to a request that should result in a PASS when
  98          * passed to that provider's PrimaryAuthenticationProvider::beginPrimaryAccountCreation().
  99          * The client will be able to send that back for expedited account creation where only
 100          * the username needs to be filled.
 101          *
 102          * Returned with an AuthManager login FAIL or RESTART, this holds a
 103          * CreateFromLoginAuthenticationRequest that may be passed to
 104          * AuthManager::beginCreateAccount(), possibly in place of any
 105          * "primary-required" requests. It may also be passed to
 106          * AuthManager::beginAuthentication() to preserve the list of
 107          * accounts which can be linked after success (see $linkRequest).
 108          */
 109         public $createRequest = null;
 110
 111         /**
 112          * @var AuthenticationRequest|null When returned with a PrimaryAuthenticationProvider
 113          *  login PASS with no username, the request this holds will be passed to
 114          *  AuthManager::changeAuthenticationData() once the local user has been determined and the
 115          *  user has confirmed the account ownership (by reviewing the information given by
 116          *  $linkRequest->describeCredentials()). The provider should handle that
 117          *  changeAuthenticationData() call by doing the actual linking.
 118          */
 119         public $linkRequest = null;
 120
 121         /**
 122          * @var AuthenticationRequest|null Returned with an AuthManager account
 123          *  creation PASS, this holds a request to pass to AuthManager::beginAuthentication()
 124          *  to immediately log into the created account. All provider methods except
 125          *   postAuthentication will be skipped.
 126          */
 127         public $loginRequest = null;
 128
 129         /**
 130          * @param string|null $username Local username
 131          * @return AuthenticationResponse
 132          * @see AuthenticationResponse::PASS
 133          */
 134         public static function newPass( $username = null ) {
 135                 $ret = new AuthenticationResponse;
 136                 $ret->status = self::PASS;
 137                 $ret->username = $username;
 138                 return $ret;
 139         }
 140
 141         /**
 142          * @param Message $msg
 143          * @return AuthenticationResponse
 144          * @see AuthenticationResponse::FAIL
 145          */
 146         public static function newFail( Message $msg ) {
 147                 $ret = new AuthenticationResponse;
 148                 $ret->status = self::FAIL;
 149                 $ret->message = $msg;
 150                 $ret->messageType = 'error';
 151                 return $ret;
 152         }
 153
 154         /**
 155          * @param Message $msg
 156          * @return AuthenticationResponse
 157          * @see AuthenticationResponse::RESTART
 158          */
 159         public static function newRestart( Message $msg ) {
 160                 $ret = new AuthenticationResponse;
 161                 $ret->status = self::RESTART;
 162                 $ret->message = $msg;
 163                 return $ret;
 164         }
 165
 166         /**
 167          * @return AuthenticationResponse
 168          * @see AuthenticationResponse::ABSTAIN
 169          */
 170         public static function newAbstain() {
 171                 $ret = new AuthenticationResponse;
 172                 $ret->status = self::ABSTAIN;
 173                 return $ret;
 174         }
 175
 176         /**
 177          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 178          * @param Message $msg
 179          * @param string $msgtype
 180          * @return AuthenticationResponse
 181          * @see AuthenticationResponse::UI
 182          */
 183         public static function newUI( array $reqs, Message $msg, $msgtype = 'warning' ) {
 184                 if ( !$reqs ) {
 185                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 186                 }
 187                 if ( $msgtype !== 'warning' && $msgtype !== 'error' ) {
 188                         throw new \InvalidArgumentException( $msgtype . ' is not a valid message type.' );
 189                 }
 190
 191                 $ret = new AuthenticationResponse;
 192                 $ret->status = self::UI;
 193                 $ret->neededRequests = $reqs;
 194                 $ret->message = $msg;
 195                 $ret->messageType = $msgtype;
 196                 return $ret;
 197         }
 198
 199         /**
 200          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 201          * @param string $redirectTarget URL
 202          * @param mixed $redirectApiData Data suitable for adding to an ApiResult
 203          * @return AuthenticationResponse
 204          * @see AuthenticationResponse::REDIRECT
 205          */
 206         public static function newRedirect( array $reqs, $redirectTarget, $redirectApiData = null ) {
 207                 if ( !$reqs ) {
 208                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 209                 }
 210
 211                 $ret = new AuthenticationResponse;
 212                 $ret->status = self::REDIRECT;
 213                 $ret->neededRequests = $reqs;
 214                 $ret->redirectTarget = $redirectTarget;
 215                 $ret->redirectApiData = $redirectApiData;
 216                 return $ret;
 217         }
 218
 219 }