Laravel Sanctum

• Введение
  • Как это работает
• Установка
• Настройка
  • Переопределение моделей по умолчанию
• Аутентификация с помощью API токенов
  • Выдача API токенов
  • Права токенов
  • Защита маршрутов
  • Отзыв токенов
  • Истечение срока действия токенов
• Аутентификация SPA
  • Настройка
  • Аутентификация
  • Защита маршрутов
  • Авторизация приватных каналов трансляции
• Аутентификация мобильных приложений
  • Выдача API токенов
  • Защита маршрутов
  • Отзыв токенов
• Тестирование

#Введение

Laravel Sanctum предоставляет лёгкую систему аутентификации для SPA (одностраничных приложений), мобильных приложений и простых API на основе токенов. Sanctum позволяет каждому пользователю вашего приложения создавать несколько API токенов для своей учётной записи. Этим токенам могут быть назначены права / области, которые определяют, какие действия разрешены для токенов.

#Как это работает

Laravel Sanctum решает две отдельные задачи. Рассмотрим каждую из них перед более глубоким изучением библиотеки.

#API токены

Во-первых, Sanctum — это простой пакет, который вы можете использовать для выдачи API токенов вашим пользователям без сложности OAuth. Эта функция вдохновлена GitHub и другими приложениями, которые выдают «персональные токены доступа». Например, представьте, что в разделе «настройки аккаунта» вашего приложения есть экран, где пользователь может создать API токен для своей учётной записи. Вы можете использовать Sanctum для создания и управления этими токенами. Обычно такие токены имеют очень длительный срок действия (годы), но могут быть отозваны пользователем в любое время.

Laravel Sanctum реализует эту функцию, сохраняя API токены пользователей в одной таблице базы данных и аутентифицируя входящие HTTP-запросы через заголовок Authorization, который должен содержать действительный API токен.

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

Во-вторых, Sanctum предлагает простой способ аутентификации одностраничных приложений (SPA), которым нужно взаимодействовать с API на Laravel. Эти SPA могут находиться в том же репозитории, что и ваше Laravel-приложение, или быть полностью отдельным проектом, например SPA, созданным с помощью Vue CLI или Next.js.

Для этой функции Sanctum не использует токены. Вместо этого Sanctum применяет встроенную в Laravel аутентификацию на основе сессионных cookie. Обычно Sanctum использует guard web для этого. Это обеспечивает защиту от CSRF, аутентификацию сессий и предотвращает утечку учётных данных через XSS.

Sanctum пытается аутентифицировать с помощью cookie только если запрос приходит с вашего собственного SPA фронтенда. При обработке входящего HTTP-запроса Sanctum сначала проверит наличие cookie для аутентификации, а если его нет, то проверит заголовок Authorization на наличие действительного API токена.

#Установка

Вы можете установить Laravel Sanctum через менеджер пакетов Composer:

composer require laravel/sanctum

Далее следует опубликовать конфигурационные и миграционные файлы Sanctum с помощью Artisan-команды vendor:publish. Файл конфигурации sanctum будет размещён в директории config вашего приложения:

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

Наконец, выполните миграции базы данных. Sanctum создаст одну таблицу для хранения API токенов:

php artisan migrate

Если вы планируете использовать Sanctum для аутентификации SPA, добавьте middleware Sanctum в группу middleware api в файле app/Http/Kernel.php вашего приложения:

'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    \Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

#Настройка миграций

Если вы не собираетесь использовать миграции Sanctum по умолчанию, вызовите метод Sanctum::ignoreMigrations в методе register вашего класса App\Providers\AppServiceProvider. Вы можете экспортировать стандартные миграции, выполнив команду: php artisan vendor:publish --tag=sanctum-migrations

#Настройка

#Переопределение моделей по умолчанию

Хотя это обычно не требуется, вы можете расширить модель PersonalAccessToken, используемую внутри Sanctum:

use Laravel\Sanctum\PersonalAccessToken as SanctumPersonalAccessToken;

class PersonalAccessToken extends SanctumPersonalAccessToken
{
    // ...
}

Затем вы можете указать Sanctum использовать вашу кастомную модель через метод usePersonalAccessTokenModel, предоставляемый Sanctum. Обычно этот метод вызывается в методе boot одного из сервис-провайдеров вашего приложения:

use App\Models\Sanctum\PersonalAccessToken;
use Laravel\Sanctum\Sanctum;

/**
 * Инициализация сервисов приложения.
 */
public function boot(): void
{
    Sanctum::usePersonalAccessTokenModel(PersonalAccessToken::class);
}

#Аутентификация с помощью API токенов

#Выдача API токенов

Sanctum позволяет выдавать API токены / персональные токены доступа, которые могут использоваться для аутентификации API-запросов к вашему приложению. При отправке запросов с API токенами токен должен быть включён в заголовок Authorization как токен типа Bearer.

Для начала выдачи токенов пользователям ваша модель User должна использовать трейт Laravel\Sanctum\HasApiTokens:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

Чтобы выдать токен, можно использовать метод createToken. Метод createToken возвращает экземпляр Laravel\Sanctum\NewAccessToken. API-токены хешируются с помощью SHA-256 перед сохранением в вашей базе данных, но вы можете получить значение токена в открытом виде через свойство plainTextToken экземпляра NewAccessToken. Это значение следует сразу показать пользователю после создания токена:

use Illuminate\Http\Request;

Route::post('/tokens/create', function (Request $request) {
    $token = $request->user()->createToken($request->token_name);

    return ['token' => $token->plainTextToken];
});

Вы можете получить все токены пользователя через Eloquent-связь tokens, предоставляемую трейтом HasApiTokens:

foreach ($user->tokens as $token) {
    // ...
}

#Права токенов

Sanctum позволяет назначать токенам «права» (abilities). Права выполняют функцию, аналогичную «scopes» в OAuth. Вы можете передать массив строк с правами вторым аргументом в метод createToken:

return $user->createToken('token-name', ['server:update'])->plainTextToken;

При обработке входящего запроса, аутентифицированного Sanctum, вы можете проверить, обладает ли токен определённым правом, используя метод tokenCan:

if ($user->tokenCan('server:update')) {
    // ...
}

#Middleware для прав токенов

Sanctum также включает два middleware, которые можно использовать для проверки, что входящий запрос аутентифицирован токеном с заданным правом. Для начала добавьте следующие middleware в свойство $middlewareAliases файла app/Http/Kernel.php вашего приложения:

'abilities' => \Laravel\Sanctum\Http\Middleware\CheckAbilities::class,
'ability' => \Laravel\Sanctum\Http\Middleware\CheckForAnyAbility::class,

Middleware abilities можно назначить маршруту для проверки, что токен запроса имеет все перечисленные права:

Route::get('/orders', function () {
    // Токен имеет права "check-status" и "place-orders"...
})->middleware(['auth:sanctum', 'abilities:check-status,place-orders']);

Middleware ability можно назначить маршруту для проверки, что токен запроса имеет хотя бы одно из перечисленных прав:

Route::get('/orders', function () {
    // Токен имеет право "check-status" или "place-orders"...
})->middleware(['auth:sanctum', 'ability:check-status,place-orders']);

#Запросы, инициированные UI первого лица

Для удобства метод tokenCan всегда возвращает true, если входящий аутентифицированный запрос был из вашего SPA первого лица и вы используете встроенную аутентификацию SPA Sanctum.

Однако это не означает, что приложению обязательно разрешать пользователю выполнять действие. Обычно политики авторизации вашего приложения определяют, имеет ли токен разрешение на выполнение прав, а также проверяют, разрешено ли самому пользователю выполнять действие.

Например, если представить приложение для управления серверами, это может означать проверку, что токен авторизован на обновление серверов и что сервер принадлежит пользователю:

return $request->user()->id === $server->user_id &&
       $request->user()->tokenCan('server:update')

Сначала может показаться странным, что метод tokenCan всегда возвращает true для запросов, инициированных UI первого лица; однако это удобно, так как всегда можно предполагать наличие API токена и проверять его через tokenCan. Такой подход позволяет вызывать tokenCan в политиках авторизации без забот о том, был ли запрос вызван из UI приложения или инициирован сторонним API клиентом.

#Защита маршрутов

Чтобы защитить маршруты и требовать аутентификацию для всех входящих запросов, прикрепите guard sanctum к защищённым маршрутам в файлах routes/web.php и routes/api.php. Этот guard обеспечит аутентификацию запросов либо как stateful с использованием cookie сессии, либо с помощью действительного API токена в заголовке, если запрос идёт от третьей стороны.

Возможно, вы задаётесь вопросом, почему мы рекомендуем аутентифицировать маршруты в routes/web.php с помощью guard sanctum. Помните, Sanctum сначала пытается аутентифицировать запросы с помощью стандартного cookie сессии Laravel. Если cookie отсутствует, Sanctum проверяет заголовок Authorization на наличие токена. Кроме того, аутентификация всех запросов через Sanctum гарантирует, что вы всегда сможете вызвать метод tokenCan у текущего аутентифицированного пользователя:

use Illuminate\Http\Request;

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

#Отзыв токенов

Вы можете «отозвать» токены, удаляя их из базы данных через связь tokens, предоставляемую трэйтом Laravel\Sanctum\HasApiTokens:

// Отозвать все токены...
$user->tokens()->delete();

// Отозвать токен, использованный для аутентификации текущего запроса...
$request->user()->currentAccessToken()->delete();

// Отозвать конкретный токен...
$user->tokens()->where('id', $tokenId)->delete();

#Истечение срока действия токенов

По умолчанию токены Sanctum не истекают и могут быть недействительны только после отзыва токена. Однако, если вы хотите настроить время жизни API токенов вашего приложения, это можно сделать через опцию expiration в конфигурационном файле sanctum. Эта опция задаёт количество минут, после которых выданный токен считается истёкшим:

'expiration' => 525600,

Если вы хотите задавать время жизни каждого токена отдельно, вы можете передать время истечения третьим аргументом в метод createToken:

return $user->createToken(
    'token-name', ['*'], now()->addWeek()
)->plainTextToken;

Если вы настроили время жизни токенов, возможно, вам захочется запланировать задачу для очистки просроченных токенов. К счастью, Sanctum включает Artisan-команду sanctum:prune-expired, которую можно использовать для этого. Например, вы можете настроить задачу, которая удаляет все записи просроченных токенов, срок действия которых истёк не менее 24 часов назад:

$schedule->command('sanctum:prune-expired --hours=24')->daily();

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

Sanctum также предоставляет простой способ аутентификации одностраничных приложений (SPA), которым нужно взаимодействовать с API на Laravel. Эти SPA могут находиться в том же репозитории, что и ваше Laravel-приложение, или быть полностью отдельным проектом.

Для этой функции Sanctum не использует токены. Вместо этого Sanctum применяет встроенную в Laravel аутентификацию на основе сессионных cookie. Такой подход обеспечивает защиту от CSRF, аутентификацию сессий и предотвращает утечку учётных данных через XSS.

#Настройка

#Настройка доменов первого лица

Сначала настройте домены, с которых ваше SPA будет отправлять запросы. Вы можете указать эти домены в опции stateful конфигурационного файла sanctum. Эта настройка определяет, какие домены будут поддерживать «stateful» аутентификацию с использованием сессионных cookie Laravel при обращении к вашему API.

#Middleware Sanctum

Далее добавьте middleware Sanctum в группу middleware api в файле app/Http/Kernel.php. Этот middleware отвечает за то, чтобы входящие запросы с вашего SPA могли аутентифицироваться с помощью сессионных cookie Laravel, при этом позволяя запросам от третьих лиц или мобильных приложений аутентифицироваться с помощью API токенов:

'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    \Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

#CORS и cookie

Если у вас возникают проблемы с аутентификацией из SPA, работающего на отдельном поддомене, скорее всего, вы неправильно настроили CORS (Cross-Origin Resource Sharing) или параметры сессионных cookie.

Убедитесь, что CORS-конфигурация вашего приложения возвращает заголовок Access-Control-Allow-Credentials со значением True. Для этого установите опцию supports_credentials в файле config/cors.php вашего приложения в значение true.

Кроме того, включите опции withCredentials и withXSRFToken в глобальном экземпляре axios вашего приложения. Обычно это делается в файле resources/js/bootstrap.js. Если вы не используете Axios для HTTP-запросов на фронтенде, настройте аналогичные параметры в вашем HTTP клиенте:

axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;

Наконец, убедитесь, что настройка домена cookie сессии вашего приложения поддерживает любые поддомены корневого домена. Вы можете сделать это, добавив в начало домена ведущую . в файле конфигурации вашего приложения config/session.php:

'domain' => '.domain.com',

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

#Защита от CSRF

Для аутентификации вашего SPA страница входа должна сначала сделать запрос к эндпоинту /sanctum/csrf-cookie, чтобы инициализировать защиту от CSRF:

axios.get('/sanctum/csrf-cookie').then(response => {
    // Вход в систему...
});

Во время этого запроса Laravel установит cookie XSRF-TOKEN с текущим CSRF токеном. Этот токен должен передаваться в заголовке X-XSRF-TOKEN при последующих запросах, что некоторые HTTP-клиенты, такие как Axios и Angular HttpClient, делают автоматически. Если ваш HTTP-клиент не устанавливает этот заголовок, вам нужно будет сделать это вручную, установив X-XSRF-TOKEN в значение cookie XSRF-TOKEN, установленной этим маршрутом.

#Вход в систему

После инициализации защиты CSRF сделайте POST запрос к маршруту /login вашего Laravel-приложения. Этот маршрут /login может быть реализован вручную или с помощью безголового пакета аутентификации, например Laravel Fortify.

Если запрос на вход успешен, вы будете аутентифицированы, и последующие запросы к маршрутам вашего приложения будут автоматически аутентифицироваться через сессионный cookie, выданный Laravel. Кроме того, поскольку ваше приложение уже сделало запрос к маршруту /sanctum/csrf-cookie, последующие запросы автоматически получат защиту CSRF, если ваш JavaScript HTTP клиент отправляет значение cookie XSRF-TOKEN в заголовке X-XSRF-TOKEN.

Разумеется, если сессия пользователя истечёт из-за бездействия, последующие запросы к Laravel могут получить HTTP ошибки 401 или 419. В этом случае следует перенаправить пользователя на страницу входа вашего SPA.

#Защита маршрутов

Чтобы защитить маршруты и требовать аутентификацию для всех входящих запросов, прикрепите guard sanctum к API маршрутам в файле routes/api.php. Этот guard обеспечит аутентификацию запросов либо как stateful запросы от вашего SPA, либо с помощью действительного API токена в заголовке, если запрос идёт от третьей стороны:

use Illuminate\Http\Request;

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

#Авторизация приватных каналов трансляции

Если вашему SPA нужна аутентификация с приватными / присутствующими каналами трансляции, вызовите метод Broadcast::routes в файле routes/api.php:

Broadcast::routes(['middleware' => ['auth:sanctum']]);

Далее, чтобы запросы авторизации Pusher проходили успешно, необходимо предоставить кастомный authorizer Pusher при инициализации Laravel Echo. Это позволит вашему приложению настроить Pusher на использование экземпляра axios, который корректно настроен для кросс-доменных запросов:

window.Echo = new Echo({
    broadcaster: "pusher",
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    encrypted: true,
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    authorizer: (channel, options) => {
        return {
            authorize: (socketId, callback) => {
                axios.post('/api/broadcasting/auth', {
                    socket_id: socketId,
                    channel_name: channel.name
                })
                .then(response => {
                    callback(false, response.data);
                })
                .catch(error => {
                    callback(true, error);
                });
            }
        };
    },
})

#Аутентификация мобильных приложений

Вы также можете использовать токены Sanctum для аутентификации запросов мобильного приложения к вашему API. Процесс аутентификации мобильных приложений похож на аутентификацию сторонних API клиентов, но есть небольшие отличия в выдаче API токенов.

#Выдача API токенов

Для начала создайте маршрут, который принимает email / имя пользователя, пароль и имя устройства, а затем обменивает эти данные на новый токен Sanctum. Имя устройства, передаваемое этому эндпоинту, служит для информации и может быть любым. Обычно это имя, которое пользователь узнает, например «iPhone 12 Нуну».

Обычно запрос к этому эндпоинту делается с экрана входа мобильного приложения. Эндпоинт возвращает открытый API токен, который затем может быть сохранён на устройстве и использован для последующих API запросов:

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

Route::post('/sanctum/token', function (Request $request) {
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
        'device_name' => 'required',
    ]);

    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages([
            'email' => ['Предоставленные учетные данные неверны.'],
        ]);
    }

    return $user->createToken($request->device_name)->plainTextToken;
});

При использовании токена мобильным приложением для API запроса, токен должен передаваться в заголовке Authorization как токен типа Bearer.

#Защита маршрутов

Как описано ранее, вы можете защитить маршруты, требуя аутентификацию для всех входящих запросов, прикрепив guard sanctum к маршрутам:

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

#Отзыв токенов

Чтобы позволить пользователям отзывать API токены, выданные мобильным устройствам, вы можете вывести их список с именами и кнопкой «Отозвать» в разделе «настройки аккаунта» вашего веб-интерфейса. При нажатии кнопки «Отозвать» токен удаляется из базы. Помните, что вы можете получить доступ к API токенам пользователя через связь tokens, предоставляемую трэйтом Laravel\Sanctum\HasApiTokens:

// Отозвать все токены...
$user->tokens()->delete();

// Отозвать конкретный токен...
$user->tokens()->where('id', $tokenId)->delete();

#Тестирование

Во время тестирования метод Sanctum::actingAs может использоваться для аутентификации пользователя и указания, какие права должны быть предоставлены его токену:

use App\Models\User;
use Laravel\Sanctum\Sanctum;

public function test_task_list_can_be_retrieved(): void
{
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );

    $response = $this->get('/api/task');

    $response->assertOk();
}

Если вы хотите предоставить все права токену, включите * в список прав, передаваемых методу actingAs:

Sanctum::actingAs(
    User::factory()->create(),
    ['*']
);