yii2專案實戰-restful api之授權驗證
什麼是restful風格的api呢?我們之前有寫過大篇的文章來介紹其概念以及基本操作。
既然寫過了,那今天是要說點什麼嗎?
這篇文章主要針對實際場景中api的部署來寫。
我們今天就來大大的侃侃那些年api遇到的授權驗證問題!獨家幹活,如果看完有所受益,記得不要忘記給我點贊哦。
業務分析
我們先來了解一下整個邏輯
- 使用者在客戶端填寫登入表單
- 使用者提交表單,客戶端請求登入介面login
- 服務端校驗使用者的帳號密碼,並返回一個有效的token給客戶端
- 客戶端拿到使用者的token,將之儲存在客戶端比如cookie中
- 客戶端攜帶token訪問需要校驗的介面比如獲取使用者個人資訊介面
- 服務端校驗token的有效性,校驗通過,反正返回客戶端需要的資訊,校驗失敗,需要使用者重新登入
本文我們以使用者登入,獲取使用者的個人資訊為例進行詳細的完整版說明。
以上,便是我們本篇文章要實現的重點。先別激動,也別緊張,分析好了之後,細節部分我們再一步一個腳印走下去。
準備工作
- 你應該有一個api應用,如果你還沒有,請先移步這裡→_→Restful api基礎
- 對於客戶端,我們準備採用postman進行模擬,如果你的google瀏覽器還沒有安裝postman,請先自行下載
- 要測試的使用者表需要有一個api_token的欄位,沒有的請先自行新增,並保證該欄位足夠長度
- api應用開啟了路由美化,並先配置post型別的login操作和get型別的signup-test操作
- 關閉了user元件的session會話
關於上面準備工作的第4點和第5點,我們貼一下程式碼方便理解
'components' => [
'user' => [
'identityClass' => 'common\models\User',
'enableAutoLogin' => true,
'enableSession' => false,
],
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false ,
'enableStrictParsing' => true,
'rules' => [
[
'class' => 'yii\rest\UrlRule',
'controller' => ['v1/user'],
'extraPatterns' => [
'POST login' => 'login',
'GET signup-test' => 'signup-test',
]
],
]
],
// ......
],
signup-test操作我們後面新增測試使用者,為登入操作提供便利。其他型別的操作後面看需要再做新增。
認證類的選擇
我們在api\modules\v1\controllers\UserController中設定的model類指向 common\models\User類,為了說明重點這裡我們就不單獨拿出來重寫了,看各位需要,有必要的話再單獨copy一個User類到api\models下。
校驗使用者許可權我們以 yii\filters\auth\QueryParamAuth 為例
use yii\filters\auth\QueryParamAuth;
public function behaviors()
{
return ArrayHelper::merge (parent::behaviors(), [
'authenticator' => [
'class' => QueryParamAuth::className()
]
] );
}
如此一來,那豈不是所有訪問user的操作都需要認證了?那不行,客戶端第一個訪問login操作的時候哪來的token,yii\filters\auth\QueryParamAuth對外提供一個屬性,用於過濾不需要驗證的action。我們將UserController的behaviors方法稍作修改
public function behaviors()
{
return ArrayHelper::merge (parent::behaviors(), [
'authenticator' => [
'class' => QueryParamAuth::className(),
'optional' => [
'login',
'signup-test'
],
]
] );
}
這樣login操作就無需許可權驗證即可訪問了。
新增測試使用者
為了避免讓客戶端登入失敗,我們先寫一個簡單的方法,往user表裡面插入兩條資料,便於接下來的校驗。
UserController增加signupTest操作,注意此方法不屬於講解範圍之內,我們僅用於方便測試。
use common\models\User;
/**
* 新增測試使用者
*/
public function actionSignupTest ()
{
$user = new User();
$user->generateAuthKey();
$user->setPassword('123456');
$user->username = '111';
$user->email = '[email protected]';
$user->save(false);
return [
'code' => 0
];
}
如上,我們添加了一個username是111,密碼是123456的使用者
登入操作
假設使用者在客戶端輸入使用者名稱和密碼進行登入,服務端login操作其實很簡單,大部分的業務邏輯處理都在api\models\loginForm上,來先看看login的實現
use api\models\LoginForm;
/**
* 登入
*/
public function actionLogin ()
{
$model = new LoginForm;
$model->setAttributes(Yii::$app->request->post());
if ($user = $model->login()) {
if ($user instanceof IdentityInterface) {
return $user->api_token;
} else {
return $user->errors;
}
} else {
return $model->errors;
}
}
登入成功後這裡給客戶端返回了使用者的token,再來看看登入的具體邏輯的實現
新建api\models\LoginForm.php
<?php
namespace api\models;
use Yii;
use yii\base\Model;
use common\models\User;
/**
* Login form
*/
class LoginForm extends Model
{
public $username;
public $password;
private $_user;
const GET_API_TOKEN = 'generate_api_token';
public function init ()
{
parent::init();
$this->on(self::GET_API_TOKEN, [$this, 'onGenerateApiToken']);
}
/**
* @inheritdoc
* 對客戶端表單資料進行驗證的rule
*/
public function rules()
{
return [
[['username', 'password'], 'required'],
['password', 'validatePassword'],
];
}
/**
* 自定義的密碼認證方法
*/
public function validatePassword($attribute, $params)
{
if (!$this->hasErrors()) {
$this->_user = $this->getUser();
if (!$this->_user || !$this->_user->validatePassword($this->password)) {
$this->addError($attribute, '使用者名稱或密碼錯誤.');
}
}
}
/**
* @inheritdoc
*/
public function attributeLabels()
{
return [
'username' => '使用者名稱',
'password' => '密碼',
];
}
/**
* Logs in a user using the provided username and password.
*
* @return boolean whether the user is logged in successfully
*/
public function login()
{
if ($this->validate()) {
$this->trigger(self::GET_API_TOKEN);
return $this->_user;
} else {
return null;
}
}
/**
* 根據使用者名稱獲取使用者的認證資訊
*
* @return User|null
*/
protected function getUser()
{
if ($this->_user === null) {
$this->_user = User::findByUsername($this->username);
}
return $this->_user;
}
/**
* 登入校驗成功後,為使用者生成新的token
* 如果token失效,則重新生成token
*/
public function onGenerateApiToken ()
{
if (!User::apiTokenIsValid($this->_user->api_token)) {
$this->_user->generateApiToken();
$this->_user->save(false);
}
}
}
我們回過頭來看一下,當我們在UserController的login操作中呼叫LoginForm的login操作後都發生了什麼
1、呼叫LoginForm的login方法
2、呼叫validate方法,隨後對rules進行校驗
3、rules校驗中呼叫validatePassword方法,對使用者名稱和密碼進行校驗
4、validatePassword方法校驗的過程中呼叫LoginForm的getUser方法,通過common\models\User類的findByUsername獲取使用者,找不到或者common\models\User的validatePassword對密碼校驗失敗則返回error
5、觸發LoginForm::GENERATE_API_TOKEN事件,呼叫LoginForm的onGenerateApiToken方法,通過common\models\User的apiTokenIsValid校驗token的有效性,如果無效,則呼叫User的generateApiToken方法重新生成
注意common\models\User類必須是使用者的認證類,如果不知道如何建立完善該類,請圍觀這裡 使用者管理之user元件的配置
下面補充本節增加的common\models\User的相關方法
/**
* 生成 api_token
*/
public function generateApiToken()
{
$this->api_token = Yii::$app->security->generateRandomString() . '_' . time();
}
/**
* 校驗api_token是否有效
*/
public static function apiTokenIsValid($token)
{
if (empty($token)) {
return false;
}
$timestamp = (int) substr($token, strrpos($token, '_') + 1);
$expire = Yii::$app->params['user.apiTokenExpire'];
return $timestamp + $expire >= time();
}
繼續補充apiTokenIsValid方法中涉及到的token有效期,在api\config\params.php檔案內增加即可
<?php
return [
// ...
// token 有效期預設1天
'user.apiTokenExpire' => 1*24*3600,
];
到這裡呢,客戶端登入 服務端返回token給客戶端就完成了。
按照文中一開始的分析,客戶端應該把獲取到的token存到本地,比如cookie中。以後再需要token校驗的介面訪問中,從本地讀取比如從cookie中讀取並訪問介面即可。
根據token請求使用者的認證操作
假設我們已經把獲取到的token儲存起來了,我們再以訪問使用者資訊的介面為例。
yii\filters\auth\QueryParamAuth類認定的token引數是 access-token,我們可以在行為中修改下
public function behaviors()
{
return ArrayHelper::merge (parent::behaviors(), [
'authenticator' => [
'class' => QueryParamAuth::className(),
'tokenParam' => 'token',
'optional' => [
'login',
'signup-test'
],
]
] );
}
這裡將預設的access-token修改為token。
我們在配置檔案的urlManager元件中增加對userProfile操作
'extraPatterns' => [
'POST login' => 'login',
'GET signup-test' => 'signup-test',
'GET user-profile' => 'user-profile',
]
我們用postman模擬請求訪問下 /v1/users/user-profile?token=apeuT9dAgH072qbfrtihfzL6qDe_l4qz_1479626145發現,丟擲了一個異常
\"findIdentityByAccessToken\" is not implemented.
這是怎麼回事呢?
我們找到 yii\filters\auth\QueryParamAuth 的authenticate方法,發現這裡呼叫了 common\models\User類的loginByAccessToken方法,有同學疑惑了,common\models\User類沒實現loginByAccessToken方法為啥說findIdentityByAccessToken方法沒實現?如果你還記得common\models\User類實現了yii\web\user類的介面的話,你應該會開啟yii\web\User類找答案。沒錯,loginByAccessToken方法在yii\web\User中實現了,該類中呼叫了common\models\User的findIdentityByAccessToken,但是我們看到,該方法中通過throw丟擲了異常,也就是說這個方法要我們自己手動實現!
這好辦了,我們就來實現下common\models\User類的findIdentityByAccessToken方法吧
public static function findIdentityByAccessToken($token, $type = null)
{
// 如果token無效的話,
if(!static::apiTokenIsValid($token)) {
throw new \yii\web\UnauthorizedHttpException("token is invalid.");
}
return static::findOne(['api_token' => $token, 'status' => self::STATUS_ACTIVE]);
// throw new NotSupportedException('"findIdentityByAccessToken" is not implemented.');
}
驗證完token的有效性,下面就要開始實現主要的業務邏輯部分了。
/**
* 獲取使用者資訊
*/
public function actionUserProfile ($token)
{
// 到這一步,token都認為是有效的了
// 下面只需要實現業務邏輯即可,下面僅僅作為案例,比如你可能需要關聯其他表獲取使用者資訊等等
$user = User::findIdentityByAccessToken($token);
return [
'id' => $user->id,
'username' => $user->username,
'email' => $user->email,
];
}
服務端返回的資料型別定義
在postman中我們可以以何種資料型別輸出的介面的資料,但是,有些人發現,當我們把postman模擬請求的地址copy到瀏覽器位址列,返回的又卻是xml格式了,而且我們明明在UserProfile操作中返回的是屬組,怎麼回事呢?
這其實是官方搗的鬼啦,我們一層層原始碼追下去,發現在yii\rest\Controller類中,有一個 contentNegotiator行為,該行為指定了允許返回的資料格式formats是json和xml,返回的最終的資料格式根據請求頭中Accept包含的首先出現在formats中的為準,你可以在yii\filters\ContentNegotiator的negotiateContentType方法中找到答案。
你可以在瀏覽器的請求頭中看到
Accept:
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
即application/xml首先出現在formats中,所以返回的資料格式是xml型別,如果客戶端獲取到的資料格式想按照json進行解析,只需要設定請求頭的Accept的值等於application/json即可
有同學可能要說,這樣太麻煩了,啥年代了,誰還用xml,我就想服務端輸出json格式的資料,怎麼做?
辦法就是用來解決問題滴,來看看怎麼做。api\config\main.php檔案中增加對response的配置
'response' => [
'class' => 'yii\web\Response',
'on beforeSend' => function ($event) {
$response = $event->sender;
$response->format = yii\web\Response::FORMAT_JSON;
},
],
如此,不管你客戶端傳什麼,服務端最終輸出的都會是json格式的資料了。
自定義錯誤處理機制
再來看另外一個比較常見的問題:
你看我們上面幾個方法哈,返回的結果是各式各樣的,這樣就給客戶端解析增加了困擾,而且一旦有異常丟擲,返回的程式碼還都是一堆一堆的,頭疼,怎麼辦?
說到這個問題之前呢,我們先說一下yii中先關的異常處理類,當然,有很多哈。比如下面常見的一些,其他的自己去挖掘
yii\web\BadRequestHttpException yii\web\ForbiddenHttpException yii\web\NotFoundHttpException yii\web\ServerErrorHttpException yii\web\UnauthorizedHttpException yii\web\TooManyRequestsHttpException
實際開發中各位要善於去利用這些類去捕獲異常,丟擲異常。說遠了哈,我們回到重點,來說如何自定義介面異常響應或者叫自定義統一的資料格式,比如向下面這種配置,統一響應客戶端的格式標準。
'response' => [
'class' => 'yii\web\Response',
'on beforeSend' => function ($event) {
$response = $event->sender;
$response->data = [
'code' => $response->getStatusCode(),
'data' => $response->data,
'message' => $response->statusText
];
$response->format = yii\web\Response::FORMAT_JSON;
},
],
說道了那麼多,本文就要結束了,剛開始接觸的同學可能有一些蒙,不要蒙,慢慢消化,先知道這麼個意思,瞭解下restful api介面在整個過程中是怎麼用token授權的就好。這樣真正實際用到的時候,你也能舉一反三!老樣子,有任何問題或者讚美的話,下方留言哦