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         /**
  85          * @var string|null Local user name from authentication.
  86          * May be null if the authentication passed but no local user is known.
  87          */
  88         public $username = null;
  89
  90         /**
  91          * @var AuthenticationRequest|null
  92          *
  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.
  98          *
  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).
 105          */
 106         public $createRequest = null;
 107
 108         /**
 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.
 115          */
 116         public $linkRequest = null;
 117
 118         /**
 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.
 123          */
 124         public $loginRequest = null;
 125
 126         /**
 127          * @param string|null $username Local username
 128          * @return AuthenticationResponse
 129          * @see AuthenticationResponse::PASS
 130          */
 131         public static function newPass( $username = null ) {
 132                 $ret = new AuthenticationResponse;
 133                 $ret->status = AuthenticationResponse::PASS;
 134                 $ret->username = $username;
 135                 return $ret;
 136         }
 137
 138         /**
 139          * @param Message $msg
 140          * @return AuthenticationResponse
 141          * @see AuthenticationResponse::FAIL
 142          */
 143         public static function newFail( Message $msg ) {
 144                 $ret = new AuthenticationResponse;
 145                 $ret->status = AuthenticationResponse::FAIL;
 146                 $ret->message = $msg;
 147                 return $ret;
 148         }
 149
 150         /**
 151          * @param Message $msg
 152          * @return AuthenticationResponse
 153          * @see AuthenticationResponse::RESTART
 154          */
 155         public static function newRestart( Message $msg ) {
 156                 $ret = new AuthenticationResponse;
 157                 $ret->status = AuthenticationResponse::RESTART;
 158                 $ret->message = $msg;
 159                 return $ret;
 160         }
 161
 162         /**
 163          * @return AuthenticationResponse
 164          * @see AuthenticationResponse::ABSTAIN
 165          */
 166         public static function newAbstain() {
 167                 $ret = new AuthenticationResponse;
 168                 $ret->status = AuthenticationResponse::ABSTAIN;
 169                 return $ret;
 170         }
 171
 172         /**
 173          * @param AuthenticationRequest[] $reqs AuthenticationRequests needed to continue
 174          * @param Message $msg
 175          * @return AuthenticationResponse
 176          * @see AuthenticationResponse::UI
 177          */
 178         public static function newUI( array $reqs, Message $msg ) {
 179                 if ( !$reqs ) {
 180                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 181                 }
 182
 183                 $ret = new AuthenticationResponse;
 184                 $ret->status = AuthenticationResponse::UI;
 185                 $ret->neededRequests = $reqs;
 186                 $ret->message = $msg;
 187                 return $ret;
 188         }
 189
 190         /**
 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
 196          */
 197         public static function newRedirect( array $reqs, $redirectTarget, $redirectApiData = null ) {
 198                 if ( !$reqs ) {
 199                         throw new \InvalidArgumentException( '$reqs may not be empty' );
 200                 }
 201
 202                 $ret = new AuthenticationResponse;
 203                 $ret->status = AuthenticationResponse::REDIRECT;
 204                 $ret->neededRequests = $reqs;
 205                 $ret->redirectTarget = $redirectTarget;
 206                 $ret->redirectApiData = $redirectApiData;
 207                 return $ret;
 208         }
 209
 210 }