Yii2 Api认证和授权(翻译)

Authentication 认证

RESTful Api 是无状态的， 因此这意味着不能使用 sessions && cookies。

因此每一个请求应该带有一些 authentication credentials 因为用户的 authentication 状态可能不是保存在 sessions || cookies 中的。

一个通用的实例就是在发送每一个请求的同时带一个 secret access token 来验证用户。因为一个 access token 可以用来确定一个唯一的用户和验证这个用户, API Requests 应该总是通过 https 协议来传输， 以防止 man-in-the-middle (MitM) 攻击。

有多种不同的方式来发送 access token：

• HTTP Basic Auth
  • access token 作为一个用户名被传递。这种情况只适合“当access token可以安全的存储在API 接收端”的情况， 比如 调用 API 的是一个在服务器上运行的程序
• Query parameter
  • access token 在 API URL 中作为一个查询参数被传递，比如 https://example.com/users?access-token=123456789
  • 因为多数的 Web 服务器会保存 query 参数在服务器日志中， 这个方法应该主要是用于响应无法使用 HTTP 头部信息来发送 access token 的 JSONP 请求的。
• OAuth 2
  • 遵照 OAth2.0 协议， 调用者从一个 授权服务器 上获取 access token， 再通过 HTTP Bearer Tokens 发送给 Api 服务器。

Yii 支持上面的几种认证方式， 你也可以自己创建新的认证方法。

要对你的 APIs 启用认证的话， 遵照下面的步骤：

1. 配置 user 组件的 yii\web\User::enableSession|enableSession 属性为 false
2. 在你的 REST 控制器中 指明你准备使用哪一种 authenticator 方法
3. 在你的 yii\web\User::identityClass|user identity class 中实施 yii\web\IdentityInterface::findIdentityByAccessToken()

第一步并不是必须， 但是针对无状态的 RESTful APIs 还是建议要有。 当 yii\web\User::enableSession|enableSession 是 false 的时候， 用户认证状态不能通过 sessions 在多个请求之间保持。反倒是， 第二步和第三部的配置会对来的每一个请求都执行认证检查。

Tips: 你可以在应用的 configurations 的 user application component 中配置 yii\web\User::enableSession|enableSession， 如果你是将 RESTful APIs 作为一个 模块 module， 你可以像下面一样在 module的 init() 方法中添加代码：

public function init()
{
    parent::init();
    \Yii::$app->user->enableSession = false;
}

下面针对上面几种情况，在 Yii2 的情况下举几个例子：

第一种情况， 使用 HTTP Basci Auth

use yii\helpers\ArrayHelper;
use yii\filters\auth\HttpBasicAuth;

public function behaviors()
{
    return ArrayHelper::merge(
        parent::behaviors(),[
            'authenticator' => [
                'class' => HttpBasicAuth::className(),
            ]
        ]
    );
}

如果你想要使用上面讲到的 3 种方式， 可以像下面一样使用 CompositeAuth :

use yii\helpers\ArrayHelper;
use yii\filters\auth\CompositeAuth;
use yii\filters\auth\HttpBasciAuth;
use yii\filters\auth\HttpBearerAuth;
use yii\filters\auth\QueryParamAuth;

public function behaviors()
{
    return ArrayHelper::merge(parent::behaviors(), [
        'authenticator' => [
            #这个地方使用`ComopositeAuth` 混合认证
            'class' => CompositeAuth::className(),
            #`authMethods` 中的每一个元素都应该是 一种 认证方式的类或者一个 配置数组
            'authMethods' => [
                HttpBasicAuth::className(),
                HttpBearerAuth::className(),
                QueryParamAuth::className(),
            ]
        ]
    ]);
}

例如， 一个简单的情景是当每一个用户只能拥有一个 ·access token· 的时候， 你可以在 user 表中的 access_token 列存储它。这种方式可以像下面一样轻易的实现：

use yii\db\ActiveRecord;
use yii\web\IdentityInterface;

class User extends ActiveRecord implements IdentityInterface
{
    public static function findIndentityByAccessToken($token)
    {
        return static::findOne(['access_token' => $token]);
    }
}

经过上面的认证之后， 对每一个 API 请求， 被请求的 控制都会 在它的 beforeAction() 步骤之前尝试认证用户。

如果认证成功， 控制器会执行其他的检查，（比如rate limiting, authorization）。被认证了的用户的认证信息可以通过 Yii::$app->user->identity 获得。

如果认证失败， 一个 401 HTTP 状态的响应会被发送回来连同其他的头部信息 （比如一个 HTTP BASIC Auth 认证的 WWW-Authenticate 头部信息）

Authorization 授权

一个用户经过认证之后， 你可能还想要检查他是否有对请求的资源执行某个请求动作的权限。这个过程叫做授权

授权是验证用户是否有足够权限做一些事情的过程。（译者注：Authentication就是验证是否注册，Authorization是检查已登录用户是否有权限） Yii 提供了两种方法来管理授权：

访问控制过滤器（Access Control Filter，简称 ACF）和 基于角色的访问控制（Role-Based Access Control，简称 RBAC）。

如果你的控制器 extend yii\rest\ActiveController， 你可以覆盖重写 yii\rest\Controller::checkAccess()|checkAccess() 方法来执行授权检查。因为这个方法会被内建动作 yii\rest\ActiveController 调用。