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 or a PASS with
  87          * no username, this holds a request that should result in a PASS when
  88          * passed to that provider's PrimaryAuthenticationProvider::beginPrimaryAccountCreation().
  89          *
  90          * Returned with an AuthManager login FAIL or RESTART, this holds a
  91          * CreateFromLoginAuthenticationRequest that may be passed to
  92          * AuthManager::beginCreateAccount(), possibly in place of any
  93          * "primary-required" requests. It may also be passed to
  94          * AuthManager::beginAuthentication() to preserve state.
  95          */
  96         public $createRequest = null;
  97
  98         /**
  99          * @var AuthenticationRequest|null Returned with a PrimaryAuthenticationProvider
 100          *  login PASS with no username, this holds a request to pass to
 101          *  AuthManager::changeAuthenticationData() to link the account once the
 102          *  local user has been determined.
 103          */
 104         public $linkRequest = null;
 105
 106         /**
 107          * @var AuthenticationRequest|null Returned with an AuthManager account
 108          *  creation PASS, this holds a request to pass to AuthManager::beginAuthentication()
 109          *  to immediately log into the created account.
 110          */
 111         public $loginRequest = null;
 112
 113         /**
 114          * @param string|null $username Local username
 115          * @return AuthenticationResponse
 116          */
 117         public static function newPass( $username = null ) {
 118                 $ret = new AuthenticationResponse;
 119                 $ret->status = AuthenticationResponse::PASS;
 120                 $ret->username = $username;
 121                 return $ret;
 122         }
 123
 124         /**
 125          * @param Message $msg
 126          * @return AuthenticationResponse
 127          */
 128         public static function newFail( Message $msg ) {
 129                 $ret = new AuthenticationResponse;
 130                 $ret->status = AuthenticationResponse::FAIL;
 131                 $ret->message = $msg;
 132                 return $ret;
 133         }
 134
 135         /**
 136          * @param Message $msg
 137          * @return AuthenticationResponse
 138          */
 139         public static function newRestart( Message $msg ) {
 140                 $ret = new AuthenticationResponse;
 141                 $ret->status = AuthenticationResponse::RESTART;
 142                 $ret->message = $msg;
 143                 return $ret;
 144         }
 145
 146         /**
 147          * @return AuthenticationResponse
 148          */
 149         public static function newAbstain() {
 150                 $ret = new AuthenticationResponse;
 151                 $ret->status = AuthenticationResponse::ABSTAIN;
 152                 return $ret;
 153         }
 154
 155         /**
 156          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 157          * @param Message $msg
 158          * @return AuthenticationResponse
 159          */
 160         public static function newUI( array $reqs, Message $msg ) {
 161                 if ( !$reqs ) {
 162                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 163                 }
 164
 165                 $ret = new AuthenticationResponse;
 166                 $ret->status = AuthenticationResponse::UI;
 167                 $ret->neededRequests = $reqs;
 168                 $ret->message = $msg;
 169                 return $ret;
 170         }
 171
 172         /**
 173          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 174          * @param string $redirectTarget URL
 175          * @param mixed $redirectApiData Data suitable for adding to an ApiResult
 176          * @return AuthenticationResponse
 177          */
 178         public static function newRedirect( array $reqs, $redirectTarget, $redirectApiData = null ) {
 179                 if ( !$reqs ) {
 180                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 181                 }
 182
 183                 $ret = new AuthenticationResponse;
 184                 $ret->status = AuthenticationResponse::REDIRECT;
 185                 $ret->neededRequests = $reqs;
 186                 $ret->redirectTarget = $redirectTarget;
 187                 $ret->redirectApiData = $redirectApiData;
 188                 return $ret;
 189         }
 190
 191 }