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 InvalidArgumentException;
  27 use MediaWiki\Message\Message;
  28
  29 /**
  30  * This is a value object to hold authentication response data
  31  *
  32  * An AuthenticationResponse represents both the status of the authentication
  33  * (success, failure, in progress) and its state (what data is needed to continue).
  34  *
  35  * @ingroup Auth
  36  * @since 1.27
  37  */
  38 class AuthenticationResponse {
  39         /** Indicates that the authentication succeeded. */
  40         public const PASS = 'PASS';
  41
  42         /** Indicates that the authentication failed. */
  43         public const FAIL = 'FAIL';
  44
  45         /** Indicates that third-party authentication succeeded but no user exists.
  46          * Either treat this like a UI response or pass $this->createRequest to
  47          * AuthManager::beginCreateAccount(). For use by AuthManager only (providers
  48          * should just return a PASS with no username).
  49          */
  50         public const RESTART = 'RESTART';
  51
  52         /** Indicates that the authentication provider does not handle this request. */
  53         public const ABSTAIN = 'ABSTAIN';
  54
  55         /** Indicates that the authentication needs further user input of some sort. */
  56         public const UI = 'UI';
  57
  58         /** Indicates that the authentication needs to be redirected to a third party to proceed. */
  59         public const REDIRECT = 'REDIRECT';
  60
  61         /** @var string One of the constants above */
  62         public $status;
  63
  64         /** @var string|null URL to redirect to for a REDIRECT response */
  65         public $redirectTarget = null;
  66
  67         /**
  68          * @var mixed Data for a REDIRECT response that a client might use to
  69          * query the remote site via its API rather than by following $redirectTarget.
  70          * Value must be something acceptable to ApiResult::addValue().
  71          */
  72         public $redirectApiData = null;
  73
  74         /**
  75          * @var AuthenticationRequest[] Needed AuthenticationRequests to continue
  76          * after a UI or REDIRECT response. This plays the same role when continuing
  77          * authentication as AuthManager::getAuthenticationRequests() does when
  78          * beginning it.
  79          */
  80         public $neededRequests = [];
  81
  82         /** @var Message|null I18n message to display in case of UI or FAIL */
  83         public $message = null;
  84
  85         /** @var string Whether the $message is an error or warning message, for styling reasons */
  86         public $messageType = 'warning';
  87
  88         /**
  89          * @var string|null Local username from authentication.
  90          * The value may be null if the authentication passed, but no local user is known.
  91          */
  92         public $username = null;
  93
  94         /**
  95          * @var AuthenticationRequest|null
  96          *
  97          * Returned with a PrimaryAuthenticationProvider login FAIL or a PASS with
  98          * no username, this can be set to a request that should result in a PASS when
  99          * passed to that provider's PrimaryAuthenticationProvider::beginPrimaryAccountCreation().
 100          * The client will be able to send that back for expedited account creation where only
 101          * the username needs to be filled.
 102          *
 103          * Returned with an AuthManager login FAIL or RESTART, this holds a
 104          * CreateFromLoginAuthenticationRequest that may be passed to
 105          * AuthManager::beginCreateAccount(), possibly in place of any
 106          * "primary-required" requests. It may also be passed to
 107          * AuthManager::beginAuthentication() to preserve the list of
 108          * accounts which can be linked after success (see $linkRequest).
 109          */
 110         public $createRequest = null;
 111
 112         /**
 113          * @var AuthenticationRequest|null When returned with a PrimaryAuthenticationProvider
 114          *  login PASS with no username, the request this holds will be passed to
 115          *  AuthManager::changeAuthenticationData() once the local user has been determined and the
 116          *  user has confirmed the account ownership (by reviewing the information given by
 117          *  $linkRequest->describeCredentials()). The provider should handle that
 118          *  changeAuthenticationData() call by doing the actual linking.
 119          */
 120         public $linkRequest = null;
 121
 122         /**
 123          * @var AuthenticationRequest|null Returned with an AuthManager account
 124          *  creation PASS, this holds a request to pass to AuthManager::beginAuthentication()
 125          *  to immediately log into the created account. All provider methods except
 126          *   postAuthentication will be skipped.
 127          */
 128         public $loginRequest = null;
 129
 130         /**
 131          * @var string[]|null String data that is optionally provided on a FAIL. It describes information about the
 132          *  failed AuthenticationResponse that shouldn't be shared with the client.
 133          *
 134          *  The CheckUser extension uses this so that it can receive whether a login request for a locked
 135          *  account had the correct password. Using the I18n message would allow the client to see if the
 136          *  password they tried on the locked account was correct while this method does not show the client this info.
 137          */
 138         public $failReasons = null;
 139
 140         /**
 141          * @param string|null $username Local username
 142          * @return AuthenticationResponse
 143          * @see AuthenticationResponse::PASS
 144          */
 145         public static function newPass( $username = null ) {
 146                 $ret = new AuthenticationResponse;
 147                 $ret->status = self::PASS;
 148                 $ret->username = $username;
 149                 return $ret;
 150         }
 151
 152         /**
 153          * @param Message $msg
 154          * @param string[] $failReasons An array of strings that describes the reason(s) for a login failure
 155          * @return AuthenticationResponse
 156          * @see AuthenticationResponse::FAIL
 157          */
 158         public static function newFail( Message $msg, array $failReasons = [] ) {
 159                 $ret = new AuthenticationResponse;
 160                 $ret->status = self::FAIL;
 161                 $ret->message = $msg;
 162                 $ret->messageType = 'error';
 163                 $ret->failReasons = $failReasons;
 164                 return $ret;
 165         }
 166
 167         /**
 168          * @param Message $msg
 169          * @return AuthenticationResponse
 170          * @see AuthenticationResponse::RESTART
 171          */
 172         public static function newRestart( Message $msg ) {
 173                 $ret = new AuthenticationResponse;
 174                 $ret->status = self::RESTART;
 175                 $ret->message = $msg;
 176                 return $ret;
 177         }
 178
 179         /**
 180          * @return AuthenticationResponse
 181          * @see AuthenticationResponse::ABSTAIN
 182          */
 183         public static function newAbstain() {
 184                 $ret = new AuthenticationResponse;
 185                 $ret->status = self::ABSTAIN;
 186                 return $ret;
 187         }
 188
 189         /**
 190          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 191          * @param Message $msg
 192          * @param string $msgtype
 193          * @return AuthenticationResponse
 194          * @see AuthenticationResponse::UI
 195          */
 196         public static function newUI( array $reqs, Message $msg, $msgtype = 'warning' ) {
 197                 if ( !$reqs ) {
 198                         throw new InvalidArgumentException( '$reqs may not be empty' );
 199                 }
 200                 if ( $msgtype !== 'warning' && $msgtype !== 'error' ) {
 201                         throw new InvalidArgumentException( $msgtype . ' is not a valid message type.' );
 202                 }
 203
 204                 $ret = new AuthenticationResponse;
 205                 $ret->status = self::UI;
 206                 $ret->neededRequests = $reqs;
 207                 $ret->message = $msg;
 208                 $ret->messageType = $msgtype;
 209                 return $ret;
 210         }
 211
 212         /**
 213          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 214          * @param string $redirectTarget URL
 215          * @param mixed|null $redirectApiData Data suitable for adding to an ApiResult
 216          * @return AuthenticationResponse
 217          * @see AuthenticationResponse::REDIRECT
 218          */
 219         public static function newRedirect( array $reqs, $redirectTarget, $redirectApiData = null ) {
 220                 if ( !$reqs ) {
 221                         throw new InvalidArgumentException( '$reqs may not be empty' );
 222                 }
 223
 224                 $ret = new AuthenticationResponse;
 225                 $ret->status = self::REDIRECT;
 226                 $ret->neededRequests = $reqs;
 227                 $ret->redirectTarget = $redirectTarget;
 228                 $ret->redirectApiData = $redirectApiData;
 229                 return $ret;
 230         }
 231
 232 }