Fixes #3765: Added `yii\web\User::enableSession` to support authentication without using session

docs/guide/rest-authentication.md

 Authentication
 ==============
 
-Unlike Web applications, RESTful APIs should be stateless, which means sessions or cookies should not
+Unlike Web applications, RESTful APIs are usually stateless, which means sessions or cookies should not
 be used. Therefore, each request should come with some sort of authentication credentials because
 the user authentication status may not be maintained by sessions or cookies. A common practice is
 to send a secret access token with each request to authenticate the user. Since an access token
@@ -23,12 +23,27 @@ There are different ways to send an access token:
 
 Yii supports all of the above authentication methods. You can also easily create new authentication methods.
 
-To enable authentication for your APIs, do the following two steps:
+To enable authentication for your APIs, do the following steps:
 
-1. Specify which authentication methods you plan to use by configuring the `authenticator` behavior
+1. Configure the [[yii\web\User::enableSession|enableSession]] property of the `user` application component to be false.
+2. Specify which authentication methods you plan to use by configuring the `authenticator` behavior
    in your REST controller classes.
-2. Implement [[yii\web\IdentityInterface::findIdentityByAccessToken()]] in your [[yii\web\User::identityClass|user identity class]].
+3. Implement [[yii\web\IdentityInterface::findIdentityByAccessToken()]] in your [[yii\web\User::identityClass|user identity class]].
 
+Step 1 is not required but is recommended for RESTful APIs which should be stateless. When [[yii\web\User::enableSession|enableSession]]
+is false, the user authentication status will NOT be persisted across requests using sessions. Instead, authentication
+will be performed for every request, which is accomplished by Step 2 and 3.
+
+> Tip: You may configure [[yii\web\User::enableSession|enableSession]] of the `user` application component
+  in application configurations if you are developing RESTful APIs in terms of an application. If you develop
+  RESTful APIs as a module, you may put the following line in the module's `init()` method, like the following:
+> ```php
+public function init()
+{
+    parent::init();
+    \Yii::$app->user->enableSession = false;
+}
+```
 
 For example, to use HTTP Basic Auth, you may configure `authenticator` as follows,
 

framework/CHANGELOG.md

@@ -75,7 +75,7 @@ Yii Framework 2 Change Log
 - Enh #3132: `yii\rbac\PhpManager` now supports more compact data file format (qiangxue)
 - Enh #3154: Added validation error display for `GridView` filters (ivan-kolmychek)
 - Enh #3196: Masked input upgraded to use jquery.inputmask plugin with more features. (kartik-v)
-- Enh #3220: Added support for setting transation isolation levels (cebe)
+- Enh #3220: Added support for setting transaction isolation levels (cebe)
 - Enh #3222: Added `useTablePrefix` option to the model generator for Gii (horizons2)
 - Enh #3230: Added `yii\filters\AccessControl::user` to support access control with different actors (qiangxue)
 - Enh #3232: Added `export()` and `exportAsString()` methods to `yii\helpers\BaseVarDumper` (klimov-paul)
@@ -99,6 +99,7 @@ Yii Framework 2 Change Log
 - Enh #3631: Added property `currencyCode` to `yii\i18n\Formatter` (leandrogehlen)
 - Enh #3636: Hide menu container tag with empty items in `yii\widgets\Menu` (arturf)
 - Enh #3643: Improved Mime-Type detection by using the `mime.types` file from apache http project to dected mime types by file extension (cebe, pavel-voronin, trejder)
+- Enh #3765: Added `yii\web\User::enableSession` to support authentication without using session (qiangxue)
 - Enh #3773: Added `FileValidator::mimeTypes` to support validating MIME types of files (Ragazzo)
 - Enh #3774: Added `FileValidator::checkExtensionByMimeType` to support validating file types against file mime-types (Ragazzo)
 - Enh #3801: Base migration controller `yii\console\controllers\BaseMigrateController` extracted (klimov-paul)

framework/UPGRADE.md

@@ -66,3 +66,6 @@ Upgrade from Yii 2.0 Beta
   differentiate it more from calling `update(false)` and to ensure it can be used in `afterSave()` without triggering infinite
   loops.
 
+* If you are developing RESTful APIs and using an authentication method such as `yii\filters\auth\HttpBasicAuth`,
+  you should explicitly configure `yii\web\User::enableSession` in the application configuration to be false to avoid
+  starting a session when authentication is performed. Previously this was done automatically by authentication method.

framework/filters/auth/HttpBasicAuth.php

@@ -70,7 +70,7 @@ class HttpBasicAuth extends AuthMethod
             if ($username !== null || $password !== null) {
                 $identity = call_user_func($this->auth, $username, $password);
                 if ($identity !== null) {
-                    $user->setIdentity($identity);
+                    $user->switchIdentity($identity);
                 } else {
                     $this->handleFailure($response);
                 }