介绍(Introduction) 入门(Getting Started) 应用结构(Application Structure) 请求处理(Handling Requests) 关键概念(Key Concepts) 配合数据库工作(Working with Databases) 接收用户数据(Getting Data from Users) 显示数据(Displaying Data) 安全(Security) 缓存(Caching) RESTful Web 服务(RESTful Web Services) 开发工具(Development Tools) 测试(Testing) 高级专题(Special Topics) 小部件(Widgets) 助手类(Helpers)

认证

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

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

提示: 如果你将 RESTful APIs 作为应用开发,可以设置应用配置中 user 组件的 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;
}

如果你想支持上面解释的所有三种认证方法,可以使用 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() 方法 来执行授权检查,该方法会被 yii\rest\ActiveController 内置的操作调用。

发现错别字或您认为此页面需要改进?
点此进入 Github 编辑!