Аутентификация

  1. Авторизация

В отличие от веб-приложений, RESTful API обычно не сохраняют информацию о состоянии, а это означает, что сессии и куки использовать не следует. Следовательно, раз состояние аутентификации пользователя не может быть сохранено в сессиях или куках, каждый запрос должен приходить вместе с определенным видом параметров аутентификации. Общепринятая практика состоит в том, что для аутентификации пользователя с каждым запросом отправляется секретный токен доступа. Так как токен доступа может использоваться для уникальной идентификации и аутентификации пользователя, запросы к API всегда должны отсылаться через протокол HTTPS, чтобы предотвратить атаки «человек посередине» (англ. "man-in-the-middle", MitM).

Есть различные способы отправки токена доступа:

  • HTTP Basic Auth: токен доступа отправляется как имя пользователя. Такой подход следует использовать только в том случае, когда токен доступа может быть безопасно сохранен на стороне пользователя API. Например, если API используется программой, запущенной на сервере.
  • Параметр запроса: токен доступа отправляется как параметр запроса в URL-адресе API, т.е. примерно таким образом: https://example.com/users?access-token=xxxxxxxx. Так как большинство веб-серверов сохраняют параметры запроса в своих логах, такой подход следует применять только при работе с JSONP-запросами, которые не могут отправлять токены доступа в HTTP-заголовках.
  • OAuth 2: токен доступа выдается пользователю API сервером авторизации и отправляется API-серверу через HTTP Bearer Tokens, в соответствии с протоколом OAuth2.

Yii поддерживает все выше перечисленные методы аутентификации. Вы также можете легко создавать новые методы аутентификации.

Чтобы включить аутентификацию для ваших API, выполните следующие шаги:

  1. У компонента приложения user установите свойство enableSession равным false.
  2. Укажите, какие методы аутентификации вы планируете использовать, настроив поведение authenticator в ваших классах REST-контроллеров.
  3. Реализуйте метод yii\web\IdentityInterface::findIdentityByAccessToken() в вашем классе UserIdentity.

Шаг 1 не обязателен, но рекомендуется его всё-таки выполнить, так как RESTful API не должен сохранять информацию о состоянии клиента. Когда свойство enableSession установлено в false, состояние аутентификации пользователя НЕ БУДЕТ сохраняться между запросами с использованием сессий. Вместо этого аутентификация будет выполняться для каждого запроса, что достигается шагами 2 и 3.

Tip: если вы разрабатываете RESTful API в пределах приложения, вы можете настроить свойство enableSession компонента приложения user в конфигурации приложения. Если вы разрабатываете RESTful API как модуль, можете добавить следующую строчку в метод 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 таблицы пользователей. В этом случае метод findIdentityByAccessToken() может быть легко реализован в классе 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 вместе с другими необходимыми заголовками (такими, как заголовок WWW-Authenticate для HTTP Basic Auth).

Авторизация

После аутентификации пользователя вы, вероятно, захотите проверить, есть ли у него или у неё разрешение на выполнение запрошенного действия с запрошенным ресурсом. Этот процесс называется авторизацией и подробно описан в разделе «Авторизация».

Если ваши контроллеры унаследованы от yii\rest\ActiveController, вы можете переопределить метод yii\rest\Controller::checkAccess() для выполнения авторизации. Этот метод будет вызываться встроенными действиями, предоставляемыми контроллером yii\rest\ActiveController.