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  * @ingroup Auth
  31  * @since 1.27
  32  */
  33 class AuthenticationResponse {
  34         /** Indicates that the authentication succeeded. */
  35         const PASS = 'PASS';
  36
  37         /** Indicates that the authentication failed. */
  38         const FAIL = 'FAIL';
  39
  40         /** Indicates that third-party authentication succeeded but no user exists.
  41          * Either treat this like a UI response or pass $this->createRequest to
  42          * AuthManager::beginCreateAccount().
  43          */
  44         const RESTART = 'RESTART';
  45
  46         /** Indicates that the authentication provider does not handle this request. */
  47         const ABSTAIN = 'ABSTAIN';
  48
  49         /** Indicates that the authentication needs further user input of some sort. */
  50         const UI = 'UI';
  51
  52         /** Indicates that the authentication needs to be redirected to a third party to proceed. */
  53         const REDIRECT = 'REDIRECT';
  54
  55         /** @var string One of the constants above */
  56         public $status;
  57
  58         /** @var string|null URL to redirect to for a REDIRECT response */
  59         public $redirectTarget = null;
  60
  61         /**
  62          * @var mixed Data for a REDIRECT response that a client might use to
  63          * query the remote site via its API rather than by following $redirectTarget.
  64          * Value must be something acceptable to ApiResult::addValue().
  65          */
  66         public $redirectApiData = null;
  67
  68         /**
  69          * @var AuthenticationRequest[] Needed AuthenticationRequests to continue
  70          * after a UI or REDIRECT response
  71          */
  72         public $neededRequests = [];
  73
  74         /** @var Message|null I18n message to display in case of UI or FAIL */
  75         public $message = null;
  76
  77         /**
  78          * @var string|null Local user name from authentication.
  79          * May be null if the authentication passed but no local user is known.
  80          */
  81         public $username = null;
  82
  83         /**
  84          * @var AuthenticationRequest|null
  85          *
  86          * Returned with a PrimaryAuthenticationProvider login FAIL, this holds a
  87          * request that should result in a PASS when passed to that provider's
  88          * PrimaryAuthenticationProvider::beginPrimaryAccountCreation().
  89          *
  90          * Returned with an AuthManager login FAIL or RESTART, this holds a request
  91          * that may be passed to AuthManager::beginCreateAccount() after setting
  92          * its ->returnToUrl property. It may also be passed to
  93          * AuthManager::beginAuthentication() to preserve state.
  94          */
  95         public $createRequest = null;
  96
  97         /**
  98          * @var AuthenticationRequest|null Returned with a PrimaryAuthenticationProvider
  99          *  login PASS with no username, this holds a request to pass to
 100          *  AuthManager::changeAuthenticationData() to link the account once the
 101          *  local user has been determined.
 102          */
 103         public $linkRequest = null;
 104
 105         /**
 106          * @var AuthenticationRequest|null Returned with an AuthManager account
 107          *  creation PASS, this holds a request to pass to AuthManager::beginAuthentication()
 108          *  to immediately log into the created account.
 109          */
 110         public $loginRequest = null;
 111
 112         /**
 113          * @param string|null $username Local username
 114          * @return AuthenticationResponse
 115          */
 116         public static function newPass( $username = null ) {
 117                 $ret = new AuthenticationResponse;
 118                 $ret->status = AuthenticationResponse::PASS;
 119                 $ret->username = $username;
 120                 return $ret;
 121         }
 122
 123         /**
 124          * @param Message $msg
 125          * @return AuthenticationResponse
 126          */
 127         public static function newFail( Message $msg ) {
 128                 $ret = new AuthenticationResponse;
 129                 $ret->status = AuthenticationResponse::FAIL;
 130                 $ret->message = $msg;
 131                 return $ret;
 132         }
 133
 134         /**
 135          * @param Message $msg
 136          * @return AuthenticationResponse
 137          */
 138         public static function newRestart( Message $msg ) {
 139                 $ret = new AuthenticationResponse;
 140                 $ret->status = AuthenticationResponse::RESTART;
 141                 $ret->message = $msg;
 142                 return $ret;
 143         }
 144
 145         /**
 146          * @return AuthenticationResponse
 147          */
 148         public static function newAbstain() {
 149                 $ret = new AuthenticationResponse;
 150                 $ret->status = AuthenticationResponse::ABSTAIN;
 151                 return $ret;
 152         }
 153
 154         /**
 155          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 156          * @param Message $msg
 157          * @return AuthenticationResponse
 158          */
 159         public static function newUI( array $reqs, Message $msg ) {
 160                 if ( !$reqs ) {
 161                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 162                 }
 163
 164                 $ret = new AuthenticationResponse;
 165                 $ret->status = AuthenticationResponse::UI;
 166                 $ret->neededRequests = $reqs;
 167                 $ret->message = $msg;
 168                 return $ret;
 169         }
 170
 171         /**
 172          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 173          * @param string $redirectTarget URL
 174          * @param mixed $redirectApiData Data suitable for adding to an ApiResult
 175          * @return AuthenticationResponse
 176          */
 177         public static function newRedirect( array $reqs, $redirectTarget, $redirectApiData = null ) {
 178                 if ( !$reqs ) {
 179                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 180                 }
 181
 182                 $ret = new AuthenticationResponse;
 183                 $ret->status = AuthenticationResponse::REDIRECT;
 184                 $ret->neededRequests = $reqs;
 185                 $ret->redirectTarget = $redirectTarget;
 186                 $ret->redirectApiData = $redirectApiData;
 187                 return $ret;
 188         }
 189
 190 }