Laravel Sanctum

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

История

Laravel Sanctum был впервые выпущен в марте 2020 года вместе с выходом Laravel 7. Первоначально он назывался Laravel Airlock, но вскоре после релиза был переименован в Sanctum из-за конфликта товарных знаков. Разработчиком пакета является Тейлор Отвелл (Taylor Otwell), создатель фреймворка Laravel. Sanctum был создан как упрощённая альтернатива Laravel Passport, который, несмотря на свою мощь, часто оказывался избыточным для типовых задач аутентификации в SPA и мобильных приложениях. С момента выхода Sanctum стал стандартным пакетом аутентификации для Laravel, включённым в официальную установку фреймворка начиная с Laravel 8.

Архитектура и принцип работы

Sanctum работает на основе двух основных механизмов аутентификации: API-токенов и аутентификации на основе сессий для SPA. В обоих случаях используется единая модель пользователя и единая система хранения токенов.

API-токены

Для аутентификации внешних клиентов (например, мобильных приложений или сторонних сервисов) Sanctum использует персональные API-токены. Каждый токен представляет собой длинную случайную строку, которая хранится в базе данных в захешированном виде (с использованием хеш-функции SHA-256). При запросе к API клиент передаёт токен в заголовке Authorization: Bearer <token>. Sanctum проверяет наличие токена в базе данных и, если он действителен, аутентифицирует пользователя. Токены могут иметь ограниченный срок действия и могут быть отозваны администратором.

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

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

1. SPA отправляет POST-запрос на маршрут /sanctum/csrf-cookie для получения CSRF-токена.
2. После этого SPA отправляет POST-запрос на маршрут /login с учётными данными пользователя.
3. Laravel устанавливает сессионную куку, и все последующие запросы от SPA аутентифицируются автоматически через эту сессию.

Для работы этого механизма необходимо, чтобы SPA и Laravel-приложение находились на одном домене или поддоменах, либо была настроена общая конфигурация CORS (Cross-Origin Resource Sharing).

Ключевые возможности

• Простота настройки: Sanctum не требует сложной конфигурации, такой как создание клиентов OAuth или настройка серверов авторизации. Для начала работы достаточно выполнить несколько команд Artisan.
• Гибкость: Пакет поддерживает как токенную, так и сессионную аутентификацию, что позволяет использовать его для разных типов клиентов.
• Управление токенами: Пользователи могут иметь несколько токенов с разными разрешениями (abilities). Например, можно создать токен только для чтения данных или только для записи.
• Отзыв токенов: Токены могут быть отозваны в любой момент, что позволяет немедленно заблокировать доступ для конкретного клиента.
• Интеграция с Laravel: Sanctum полностью интегрирован с другими компонентами Laravel, такими как Eloquent ORM, система маршрутизации и middleware.

Установка и настройка

Sanctum входит в состав стандартной установки Laravel начиная с версии 8. Для более ранних версий его можно установить через Composer: ``bash composer require laravel/sanctum ` После установки необходимо опубликовать конфигурационный файл и миграции, а затем выполнить миграцию базы данных: `bash php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" php artisan migrate ` В конфигурационном файле config/sanctum.php` можно настроить параметры, такие как срок действия токенов, модель пользователя и middleware.

Использование

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

Для выдачи токена пользователю используется метод createToken() модели пользователя, который должен использовать трейт HasApiTokens. Пример: ``php $token = $user->createToken('token-name', ['read', 'write'])->plainTextToken; ` Метод возвращает объект NewAccessToken`, из которого можно извлечь сам токен в виде обычного текста (plainTextToken). Этот токен должен быть передан клиенту и сохранён им для последующих запросов.

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

Для защиты маршрутов от неаутентифицированных запросов используется middleware auth:sanctum. Пример: ``php Route::get('/user', function (Request $request) { return $request->user(); })->middleware('auth:sanctum'); `` Этот middleware проверяет наличие действительного токена в заголовке запроса или сессионной куки.

Проверка разрешений

Sanctum позволяет проверять, имеет ли токен определённое разрешение (ability). Для этого используется метод tokenCan(): ``php if ($request->user()->tokenCan('read')) { // Пользователь имеет право на чтение } `` Разрешения задаются при создании токена и могут быть проверены в middleware или контроллере.

Сравнение с другими решениями

Laravel Passport

Passport — это полноценная реализация протокола OAuth2, предоставляющая возможность создания серверов авторизации, выдачи токенов доступа, refresh-токенов и т.д. Он значительно сложнее в настройке и требует больше ресурсов. Sanctum, в отличие от Passport, не поддерживает OAuth2, но является более лёгким и быстрым решением для типовых задач.

Laravel Jetstream

Jetstream — это стартовый набор для Laravel, который включает в себя Sanctum для аутентификации API. Jetstream предоставляет готовый интерфейс для управления токенами и командами.

Критика и ограничения

• Отсутствие поддержки OAuth2: Sanctum не поддерживает протокол OAuth2, что делает его непригодным для сложных сценариев, таких как делегирование доступа сторонним приложениям.
• Ограниченная масштабируемость: Для очень крупных проектов с высокой нагрузкой Sanctum может быть менее эффективен, чем более специализированные решения.
• Зависимость от сессий: Для SPA Sanctum полагается на сессионную аутентификацию, что может быть проблематично при использовании распределённых систем или микросервисной архитектуры.

Применение

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

Источники

• Официальная документация Laravel Sanctum (Laravel.com)
• Релизные заметки Laravel 7 (Laravel News)
• Книга «Laravel: Up & Running» (Мэтт Стаффер, 2021)
• Статья «Laravel Sanctum vs Passport» (Laravel Daily)