Авторизация

В отличие от веб-приложений, RESTful API обычно являются бессостоятельными, что означает, что сессии или куки не должны использоваться. Поэтому каждый запрос должен содержать какие-либо учетные данные для аутентификации, поскольку статус аутентификации пользователя не сохраняется сессиями или куками. Распространённой практикой является отправка секретного токена доступа с каждым запросом для аутентификации пользователя. Поскольку токен доступа может использоваться для уникальной идентификации и аутентификации пользователя, запросы API всегда должны отправляться по протоколу HTTPS для предотвращения атак «человек посередине» (MitM).

Существует несколько способов отправки токена доступа:

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

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

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

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

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

Совет: Вы можете настроить enableSession компонента user приложения в конфигурациях приложения, если вы разрабатываете RESTful API в рамках приложения. Если вы разрабатываете 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 таблицы пользователей. Метод может быть легко реализован в классе 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, вы можете переопределить метод checkAccess() для выполнения проверки авторизации. Этот метод будет вызван встроенными действиями, предоставляемыми yii\rest\ActiveController.