What is a restful style API? We have written large articles before to introduce its concepts and basic operations.
Since I have written it, do you want to say something today?
This article is mainly written for the deployment of APIs in actual scenarios.
Today, let’s talk about the authorization verification problems encountered by APIs in those years! Exclusive work, if you benefit from reading it, remember not to forget to like me.
Business Analysis
Let's first understand the whole logic
1. The user fills in the login form on the client
2. The user submits the form and the client requests the login interface
3. The server side checks the user's account password and returns a valid token to the client
4. The client gets the user's token and stores it in the client, such as a cookie.
5. The client carries token to access the interface that needs to be verified, such as the interface to obtain user personal information
6. The server side checks the validity of the token and passes the verification. Anyway, the information required by the client is returned. The verification fails and the user needs to log in again.
In this article, we use the user to log in and obtain the user's personal information as an example to provide a detailed and complete version description.
The above are the key points to achieve in this article. Don’t be excited or nervous. After analyzing it, let’s continue to follow the details.
Preparation
1. You should have an API application.
2. For the client, we are planning to use postman for simulation. If your Google browser has not installed postman yet, please download it yourself first.
3. The user table to be tested needs to have an api_token field. If not, please add it yourself first and ensure that the field is sufficiently long.
The application has enabled routing beautification, and first configure the post-type login operation and the get-type signup-test operation.
5. Close the session session of the user component
Regarding the above preparation points 4 and 5, we will post the code to make it easier to understand.
'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',
]
],
]
],
// ......
],
We will add test users to the signup-test operation to facilitate login operation. Other types of operations need to be added later.
Selection of certification
The model class we set in api\modules\v1\controllers\UserController points to the common\models\User class. In order to explain the key points, we will not rewrite it separately. Depending on your needs, if necessary, copy a User class separately to api\models.
Check user permissions Let's take yii\filters\auth\QueryParamAuth as an example
use yii\filters\auth\QueryParamAuth;
public function behaviors()
{
return ArrayHelper::merge (parent::behaviors(), [
'authenticator' => [
'class' => QueryParamAuth::className()
]
] );
}
In this way, won’t all accessing user operations require authentication? That won't work. Where does the token come from when the client first accesses the login operation? Yii\filters\auth\QueryParamAuth provides an external attribute to filter actions that do not require verification. We slightly modify the behaviors method of UserController
public function behaviors()
{
return ArrayHelper::merge (parent::behaviors(), [
'authenticator' => [
'class' => QueryParamAuth::className(),
'optional' => [
'login',
'signup-test'
],
]
] );
}
In this way, the login operation can be accessed without permission verification.
Add test user
In order to avoid failure of client login, we first write a simple method to insert two pieces of data into the user table to facilitate the subsequent verification.
UserController adds a signupTest operation. Note that this method does not fall within the scope of explanation, and we are only used for convenient testing.
use common\models\User;
/**
* Add test user
*/
public function actionSignupTest ()
{
$user = new User();
$user->generateAuthKey();
$user->setPassword('123456');
$user->username = '111';
$user->email = '111@';
$user->save(false);
return [
'code' => 0
];
}
As above, we added a user whose username is 111 and password is 123456
Login operation
Assuming that the user enters the username and password to log in on the client, the server login operation is actually very simple. Most of the business logic processing is on the api\models\loginForm. Let's take a look at the implementation of login first.
use api\models\LoginForm;
/**
* Log in
*/
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;
}
}
After logging in successfully, the user's token is returned to the client, and then let's take a look at the specific logic of login.
Create a new api\models\
<?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 for verifying client form data
*/
public function rules()
{
return [
[['username', 'password'], 'required'],
['password', 'validatePassword'],
];
}
/**
* Custom password authentication method
*/
public function validatePassword($attribute, $params)
{
if (!$this->hasErrors()) {
$this->_user = $this->getUser();
if (!$this->_user || !$this->_user->validatePassword($this->password)) {
$this->addError($attribute, 'Incorrect username or password.');
}
}
}
/**
* @inheritdoc
*/
public function attributeLabels()
{
return [
'username' => 'username',
'password' => '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;
}
}
/**
* Obtain user authentication information based on username
*
* @return User|null
*/
protected function getUser()
{
if ($this->_user === null) {
$this->_user = User::findByUsername($this->username);
}
return $this->_user;
}
/**
* After the login verification is successful, a new token is generated for the user
* If the token fails, regenerate the token
*/
public function onGenerateApiToken ()
{
if (!User::apiTokenIsValid($this->_user->api_token)) {
$this->_user->generateApiToken();
$this->_user->save(false);
}
}
}
Let's look back at what happened after we called LoginForm's login operation in the UserController's login operation
1. Call the login method of LoginForm
2. Call the validate method and then verify the rules
3. Call the validatePassword method in rules verification to verify the user name and password
4. During the validatePassword method verification process, call the getUser method of LoginForm, and obtain the user through the findByUsername of common\models\User class. If it cannot be found or if the validatePassword of common\models\User fails to verify the password, it will return an error.
5. Trigger LoginForm::GENERATE_API_TOKEN event, call LoginForm's onGenerateApiToken method, verify the validity of the token through common\models\User's apiTokenIsValid. If it is invalid, call User's generateApiToken method to regenerate
Note that the common\models\User class must be the user's authentication class.
The following are the relevant methods of common\models\User added in this section
/**
* Generate api_token
*/
public function generateApiToken()
{
$this->api_token = Yii::$app->security->generateRandomString() . '_' . time();
}
/**
* Check whether api_token is valid
*/
public static function apiTokenIsValid($token)
{
if (empty($token)) {
return false;
}
$timestamp = (int) substr($token, strrpos($token, '_') + 1);
$expire = Yii::$app->params[''];
return $timestamp + $expire >= time();
}
Continue to supplement the validity period of tokens involved in apiTokenIsValid method, and add them in api\config\ file.
<?php return [ // ... // token validity period is 1 day by default '' => 1*24*3600, ];
At this point, the client logs in and the server returns token to the client and completes.
According to the initial analysis in the article, the client should save the obtained token locally, such as in a cookie. In the future, when accessing the interface that requires token verification, you can read from local, such as reading from cookies and access the interface.
Requesting user authentication operations based on token
Suppose we have saved the obtained token, and we will take the interface to access user information as an example.
The token parameter recognized by yii\filters\auth\QueryParamAuth class is access-token, we can modify it in the behavior
public function behaviors()
{
return ArrayHelper::merge (parent::behaviors(), [
'authenticator' => [
'class' => QueryParamAuth::className(),
'tokenParam' => 'token',
'optional' => [
'login',
'signup-test'
],
]
] );
}
Here, the default access-token is changed to token.
We add userProfile operation to the urlManager component of the configuration file
'extraPatterns' => [ 'POST login' => 'login', 'GET signup-test' => 'signup-test', 'GET user-profile' => 'user-profile', ]
We use postman to simulate the request to access /v1/users/user-profile?token=apeuT9dAgH072qbfrtihfzL6qDe_l4qz_1479626145 and found that an exception was thrown
\"findIdentityByAccessToken\" is not implemented.
What's going on?
We found the authenticate method of yii\filters\auth\QueryParamAuth and found that the loginByAccessToken method of common\models\User class is called here. Some students were puzzled. The common\models\User class did not implement the loginByAccessToken method. Why does it say that the findIdentityByAccessToken method is not implemented? If you still remember that the common\models\User class implements the yii\web\user class interface, you should open the yii\web\User class to find the answer. That's right, the loginByAccessToken method is implemented in yii\web\User. The common\models\User's findIdentityByAccessToken is called in this class, but we see that an exception is thrown through throw in this method, which means that we have to implement this method manually!
This is easy to do, let's implement the findIdentityByAccessToken method of common\models\User class
public static function findIdentityByAccessToken($token, $type = null)
{
// If the token is invalid, 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.');
}
After verifying the validity of the token, we will start to implement the main business logic parts.
/**
* Get user information
*/
public function actionUserProfile ($token)
{
// At this point, tokens think it is valid // Just implement business logic below, just use it as a case, for example, you may need to associate other tables to obtain user information, etc. $user = User::findIdentityByAccessToken($token);
return [
'id' => $user->id,
'username' => $user->username,
'email' => $user->email,
];
}
Data type definition returned by the server
In postman, what data type can we output the interface data. However, some people have found that when we copy the address requested by postman to the browser address bar, the returned xml format is also in the form of the userProfile operation, and we obviously return the belonging group in the UserProfile operation. What's going on?
This is actually the official trick. We followed up the source code layer by layer and found that in the yii\rest\Controller class, there is a contentNegotiator behavior. This behavior specifies that the data formats allowed to be returned are json and xml. The final data format returned is based on the Accept included in the request header that first appears in the formats. You can find the answer in the negotiateContentType method of yii\filters\ContentNegotiator.
You can see it in the browser's request header
Accept:
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
That is, application/xml appears in formats first, so the returned data format is xml type. If the data format obtained by the client wants to be parsed according to json, you only need to set the Accept value of the request header equals application/json.
Some students may say that this is too troublesome. In what era, who still uses xml? I want to output json format data on the server. How to do it?
The solution is to solve the problem, let’s see how to do it. Add the configuration of response to the api\config\ file
'response' => [
'class' => 'yii\web\Response',
'on beforeSend' => function ($event) {
$response = $event->sender;
$response->format = yii\web\Response::FORMAT_JSON;
},
],
In this way, no matter what your client transmits, the server will eventually output data in json format.
Custom error handling mechanism
Let’s look at another common question:
Look at the above methods, the results returned are of various types, which adds trouble to client parsing. And once an exception is thrown, the returned codes are still piled up. What should I do?
Before talking about this issue, let’s talk about the exception handling classes that are first closed in Yii. Of course, there are many. For example, some common ones below, dig into others yourself
yii\web\BadRequestHttpException yii\web\ForbiddenHttpException yii\web\NotFoundHttpException yii\web\ServerErrorHttpException yii\web\UnauthorizedHttpException yii\web\TooManyRequestsHttpException
In actual development, you should be good at using these classes to catch exceptions and throw exceptions. Let's talk about it far, let's go back to the point, how to customize interface exception response or customize unified data formats, such as to the following configuration, unified response client format standards.
'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;
},
],
After saying so much, this article is about to end. Students who are just starting to come into contact with may have some confusion. Don’t be confused, digest it slowly. First, know this meaning and understand how the restful API interface is authorized by token throughout the entire process. When this is really used, you can learn from it!
The above is all the content of this article. I hope it will be helpful to everyone's study and I hope everyone will support me more.