Yii 中文社区 · 更新于 2017-11-18 20:00:53

认证

和 Web 应用不同,RESTful APIs 通常是无状态的,也就意味着不应使用 sessions 或 cookies,因此每个请求应附带某种授权凭证,因为用户授权状态可能没通过 sessions 或 cookies 维护,常用的做法是每个请求都发送一个秘密的 access token 来认证用户,由于 access token 可以唯一识别和认证用户,API 请求应通过 HTTPS 来防止 man-in-the-middle (MitM) 中间人攻击.

下面有几种方式来发送 access token:

  • HTTP 基本认证: access token 当作用户名发送,应用在 access token 可安全存在 API 使用端的场景,例如,API 使用端是运行在一台服务器上的程序。
  • 请求参数: access token 当作 API URL 请求参数发送,例如 https://example.com/users?access-token=xxxxxxxx,由于大多数服务器都会保存请求参数到日志, 这种方式应主要用于JSONP 请求,因为它不能使用 HTTP 头来发送 access token
  • OAuth 2: 使用者从认证服务器上获取基于 OAuth2 协议的 access token,然后通过 HTTP Bearer Tokens 发送到 API 服务器。

Yii 支持上述的认证方式,你也可很方便的创建新的认证方式。

为你的 APIs 启用认证,做以下步骤:

  1. 配置user 应用组件:
    • 设置 [[yii\web\User::enableSession|enableSession]] 属性为 false.
    • 设置 [[yii\web\User::loginUrl|loginUrl]] 属性为null 显示一个 HTTP 403 错误而不是跳转到登录界面.
  2. 在你的 REST 控制器类中配置authenticator 行为来指定使用哪种认证方式
  3. 在你的[[yii\web\User::identityClass|user identity class]] 类中实现 [[yii\web\IdentityInterface::findIdentityByAccessToken()]] 方法.

步骤 1 不是必要的,但是推荐配置,因为 RESTful APIs 应为无状态的,当[[yii\web\User::enableSession|enableSession]]为 false,请求中的用户认证状态就不能通过 session 来保持,每个请求的认证通过步骤 2 和 3 来实现。

提示: 如果你将 RESTful APIs 作为应用开发,可以设置应用配置中 user 组件的[[yii\web\User::enableSession|enableSession]],如果将 RESTful APIs 作为模块开发,可以在模块的 init() 方法中增加如下代码,如下所示:

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

例如,为使用 HTTP Basic Auth,可配置authenticator 行为,如下所示:

use yii\filters\auth\HttpBasicAuth;

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

如果你系那个支持以上 3 个认证方式,可以使用CompositeAuth,如下所示:

use yii\filters\auth\CompositeAuth;
use yii\filters\auth\HttpBasicAuth;
use yii\filters\auth\HttpBearerAuth;
use yii\filters\auth\QueryParamAuth;

public function behaviors()
{
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => CompositeAuth::className(),
        'authMethods' => [
            HttpBasicAuth::className(),
            HttpBearerAuth::className(),
            QueryParamAuth::className(),
        ],
    ];
    return $behaviors;
}

authMethods 中每个单元应为一个认证方法名或配置数组。

findIdentityByAccessToken()方法的实现是系统定义的,例如,一个简单的场景,当每个用户只有一个 access token, 可存储 access token 到 user 表的access_token列中,方法可在User类中简单实现,如下所示:

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

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

在上述认证启用后,对于每个 API 请求,请求控制器都会在它的beforeAction()步骤中对用户进行认证。

如果认证成功,控制器再执行其他检查(如频率限制,操作权限),然后再执行操作,授权用户信息可使用Yii::$app->user->identity获取.

如果认证失败,会发送一个 HTTP 状态码为 401 的响应,并带有其他相关信息头(如 HTTP 基本认证会有WWW-Authenticate 头信息).

授权

在用户认证成功后,你可能想要检查他是否有权限执行对应的操作来获取资源,这个过程称为 authorization ,详情请参考 Authorization section.

如果你的控制器从[[yii\rest\ActiveController]]类继承,可覆盖 [[yii\rest\Controller::checkAccess()|checkAccess()]] 方法来执行授权检查,该方法会被[[yii\rest\ActiveController]]内置的操作调用。

上一篇: 格式化响应 下一篇: 速率限制