sanctum laravel что это
Laravel Framework Russian Community
Пролог
Начало работы
Архитектурные концепции
Основное
Погружение
Безопасность
База данных
Eloquent ORM
Тестирование
Пакеты
Пакет Laravel Sanctum
Введение
Laravel Sanctum предлагает легковесную систему аутентификации для SPA (одностраничных приложений), мобильных приложений и простых API на основе токенов. Sanctum позволяет каждому пользователю вашего приложения создавать несколько токенов API для своей учетной записи. Этим токенам могут быть предоставлены полномочия / области, которые определяют, какие действия токенам разрешено выполнять.
Как это работает
Laravel Sanctum существует для решения двух отдельных задач. Давайте обсудим каждую из них, прежде чем углубиться в изучение пакета.
Краткая информация о токенах API
Во-первых, Sanctum – это простой пакет, который вы можете использовать для выдачи токенов API своим пользователям без осложнений с OAuth. Этот функционал вдохновлен GitHub и другими приложениями, которые выдают «токены личного доступа». Например, представьте, что в «настройках учетной записи» вашего приложения есть экран, на котором пользователь может сгенерировать токен API для своей учетной записи. Вы можете использовать Sanctum для создания этих токенов и управления ими. Эти токены обычно имеют очень длительный срок действия (годы), но могут быть отозваны пользователем самостоятельно в любое время.
Краткая информация об аутентификации SPA
Во-вторых, Sanctum также обеспечивает простой метод аутентификации одностраничных приложений (SPA), взаимодействующих с API Laravel. Эти SPA могут существовать в том же репозитории, что и ваше приложение Laravel, или могут быть полностью отдельным репозиторием, например SPA, созданные с помощью Vue CLI или приложения Next.js.
Для этого функционала Sanctum не использует никаких токенов. Вместо этого Sanctum использует встроенные в Laravel службы аутентификации сессии на основе файлов cookie. Обычно для этого Sanctum использует охранника web аутентификации Laravel. Это обеспечивает преимущества защиты от CSRF, аутентификации сессии, а также защищает от утечки учетных данных аутентификации через XSS.
Sanctum будет пытаться аутентифицироваться с помощью файлов cookie только тогда, когда входящий запрос исходит от вашей собственной клиентской части SPA. Когда Sanctum проверяет входящий HTTP-запрос, он сначала проверяет файл cookie аутентификации, а если он отсутствует, то Sanctum проверяет заголовок Authorization на наличие действительного токена API.
Совершенно нормально использовать Sanctum только для аутентификации токена API или только для аутентификации SPA. Тот факт, что вы используете Sanctum, не означает, что вы должны использовать оба функционала, которые он предлагает.
Установка
Вы можете установить Laravel Sanctum через менеджер пакетов Composer:
Затем, вы должны опубликовать файлы конфигурации и миграции Sanctum с помощью команды vendor:publish Artisan. Файл конфигурации sanctum будет помещен в каталог config вашего приложения:
Наконец, вы должны запустить миграцию базы данных. Sanctum создаст одну таблицу базы данных, в которой будут храниться токены API:
Затем, если вы планируете использовать Sanctum для аутентификации SPA, то вам следует добавить посредника Sanctum в вашу группу посредников api в файле app/Http/Kernel.php :
Настройка миграции
Конфигурирование
Переопределение моделей по умолчанию
Аутентификация токена API
Вы не должны использовать токены API для аутентификации собственного SPA. Вместо этого используйте функционал аутентификации SPA Sanctum.
Выдача токенов API
Чтобы начать выдачу токенов для пользователей, ваша модель User должна использовать трейт Laravel\Sanctum\HasApiTokens :
Вы можете получить доступ ко всем токенам пользователя с помощью отношения Eloquent tokens трейта HasApiTokens :
Полномочия токена
Sanctum позволяет вам назначать «полномочия» (abilities) токенам. Полномочия служат той же цели, что и «права доступа» OAuth Scopes. Вы можете передать массив, содержащий строковые ключи полномочий, в качестве второго аргумента методу createToken :
При обработке входящего запроса, аутентифицированного Sanctum, вы можете определить, обладает ли токен указанными полномочиями, используя метод tokenCan :
Посредник для токена
Посредник abilities может быть назначен маршруту для проверки того, что токен входящего запроса имеет все перечисленные возможности:
Посредник ability может быть назначен маршруту для проверки того, что токен входящего запроса имеет «по крайней мере одну» из перечисленных возможностей:
Однодоменные запросы, инициированные пользовательским интерфейсом
Однако, это не обязательно означает, что ваше приложение должно позволять пользователю выполнять действие. Как правило, политики авторизации вашего приложения определяют, предоставлены ли токену полномочия, а также проверяют, разрешено ли самому экземпляру пользователя выполнять действие.
Например, если мы представим себе приложение, которое управляет серверами, это может означать проверку того, что токен авторизован для обновления серверов и что сервер принадлежит пользователю:
Защита маршрутов
Отзыв токенов
Вы можете «отозвать» токены, удалив их из своей базы данных, используя отношение tokens трейта Laravel\Sanctum\HasApiTokens :
Аутентификация SPA
Sanctum также обеспечивает простой метод аутентификации одностраничных приложений (SPA), взаимодействующих с API Laravel. Эти SPA могут существовать в том же репозитории, что и ваше приложение Laravel, или могут быть полностью отдельным репозиторием.
Для этого функционала Sanctum не использует никаких токенов. Вместо этого Sanctum использует встроенные в Laravel службы аутентификации сессии на основе файлов Cookies. Такой подход к аутентификации обеспечивает преимущества защиты от CSRF, аутентификации сессии, а также защищает от утечки учетных данных аутентификации через XSS.
Для аутентификации ваш SPA и API должны использовать один и тот же домен верхнего уровня, но они могут быть размещены на разных поддоменах. Кроме того, вы должны убедиться, что отправляете заголовок Accept: application/json вместе с запросом.
Конфигурирование SPA
Настройка собственных доменов
Если вы обращаетесь к своему приложению через URL-адрес, содержащий порт (например, 127.0.0.1:8000 ), то вы должны убедиться, что указали номер порта вместе с доменом.
Посредник Sanctum
CORS и Cookies
Если у вас возникли проблемы с аутентификацией вашего SPA, который выполняется на отдельном поддомене, вы, вероятно, неправильно сконфигурировали параметры CORS (совместное использование ресурсов между разными источниками) или cookie сессий.
Выполнение аутентификации SPA
Защита от CSRF
Для аутентификации вашего SPA страница «входа» вашего SPA должна сначала сделать запрос к /sanctum/csrf-cookie для инициализации защиты от CSRF для приложения:
Вход в систему
После того как защита от CSRF была инициализирована, вы должны сделать POST-запрос к маршруту /login вашего приложения Laravel. Этот маршрут /login может быть реализован вручную или с использованием пакета безголовой аутентификации, такого как Laravel Fortify.
Конечно, если сессия вашего пользователя истекает из-за отсутствия активности, то последующие запросы к приложению Laravel могут получить ответ об ошибках 401 или 419 HTTP. В этом случае вы должны перенаправить пользователя на страницу входа в SPA.
Защита маршрутов SPA
Авторизация частных каналов вещания
Если вашему SPA необходимо аутентифицировать трансляцию по частным каналам или каналам присутствия, то вы должны вызвать метод Broadcast::routes в файле routes/api.php вашего приложения:
Аутентификация мобильного приложения
Вы также можете использовать токены Sanctum для аутентификации запросов вашего мобильного приложения к вашему API. Процесс аутентификации запросов мобильного приложения аналогичен аутентификации запросов стороннего API; однако, есть небольшие различия в том, как вы будете выдавать токены API.
Выдача токенов API мобильного приложения
Для начала создайте маршрут, который принимает электронную почту / имя пользователя, пароль и имя устройства, а затем обменивает эти учетные данные на новый токен Sanctum. «Имя устройства», присвоенное этой конечной точке, предназначено для информационных целей и может иметь любое желаемое значение. В общем, значение имени устройства должно быть именем, которое узнает пользователь, например «iPhone 12 Nuno».
Как правило, вы делаете запрос к конечной точке токена с экрана «входа в систему» вашего мобильного приложения. Конечная точка вернет токен API в виде простого текста, который затем может быть сохранен на мобильном устройстве и использован для выполнения дополнительных API-запросов:
При выдаче токенов для мобильного приложения вы также можете указать полномочия токена.
Защита маршрутов API мобильного приложения
Как ранее было задокументировано, вы можете защитить маршруты так, чтобы все входящие запросы аутентифицировались, назначив маршрутам охранника аутентификации sanctum :
Отзыв токенов API мобильного приложения
Чтобы пользователи могли отзывать токены API, выданные для мобильных устройств, вы можете перечислить их по имени вместе с кнопкой «Отозвать» в разделе «Настройки учетной записи» пользовательского интерфейса веб-приложения, например. Когда пользователь нажимает кнопку «Отозвать», вы можете удалить токен из базы данных. Помните, что вы можете получить доступ к токенам API пользователя через отношения tokens трейта Laravel\Sanctum\HasApiTokens :
Тестирование
Во время тестирования метод Sanctum::actingAs может использоваться для аутентификации пользователя и указания, какие полномочия должны быть предоставлены его токену:
Если вы хотите предоставить токену все полномочия, то вы должны указать * в списке полномочий метода actingAs :
Laravel 8 · Пакет Laravel Sanctum
Введение
Laravel Sanctum предлагает легковесную систему аутентификации для SPA (одностраничных приложений), мобильных приложений и простых API на основе токенов. Sanctum позволяет каждому пользователю вашего приложения создавать несколько токенов API для своей учетной записи. Этим токенам могут быть предоставлены полномочия / области, которые определяют, какие действия токенам разрешено выполнять.
Как это работает
Laravel Sanctum существует для решения двух отдельных задач. Давайте обсудим каждую из них, прежде чем углубиться в изучение пакета.
Краткая информация о токенах API
Во-первых, Sanctum – это простой пакет, который вы можете использовать для выдачи токенов API своим пользователям без осложнений с OAuth. Этот функционал вдохновлен GitHub и другими приложениями, которые выдают «токены личного доступа». Например, представьте, что в «настройках учетной записи» вашего приложения есть экран, на котором пользователь может сгенерировать токен API для своей учетной записи. Вы можете использовать Sanctum для создания этих токенов и управления ими. Эти токены обычно имеют очень длительный срок действия (годы), но могут быть отозваны пользователем самостоятельно в любое время.
Краткая информация об аутентификации SPA
Во-вторых, Sanctum также обеспечивает простой метод аутентификации одностраничных приложений (SPA), взаимодействующих с API Laravel. Эти SPA могут существовать в том же репозитории, что и ваше приложение Laravel, или могут быть полностью отдельным репозиторием, например SPA, созданные с помощью Vue CLI или приложения Next.js.
Для этого функционала Sanctum не использует никаких токенов. Вместо этого Sanctum использует встроенные в Laravel службы аутентификации сессии на основе файлов cookie. Обычно для этого Sanctum использует охранника web аутентификации Laravel. Это обеспечивает преимущества защиты от CSRF, аутентификации сессии, а также защищает от утечки учетных данных аутентификации через XSS.
Sanctum будет пытаться аутентифицироваться с помощью файлов cookie только тогда, когда входящий запрос исходит от вашей собственной клиентской части SPA. Когда Sanctum проверяет входящий HTTP-запрос, он сначала проверяет файл cookie аутентификации, а если он отсутствует, то Sanctum проверяет заголовок Authorization на наличие действительного токена API.
Совершенно нормально использовать Sanctum только для аутентификации токена API или только для аутентификации SPA. Тот факт, что вы используете Sanctum, не означает, что вы должны использовать оба функционала, которые он предлагает.
Установка
Вы можете установить Laravel Sanctum через менеджер пакетов Composer:
Затем, вы должны опубликовать файлы конфигурации и миграции Sanctum с помощью команды vendor:publish Artisan. Файл конфигурации sanctum будет помещен в каталог config вашего приложения:
Наконец, вы должны запустить миграцию базы данных. Sanctum создаст одну таблицу базы данных, в которой будут храниться токены API:
Затем, если вы планируете использовать Sanctum для аутентификации SPA, то вам следует добавить посредника Sanctum в вашу группу посредников api в файле app/Http/Kernel.php :
Настройка миграции
Конфигурирование
Переопределение моделей по умолчанию
Аутентификация токена API
Вы не должны использовать токены API для аутентификации собственного SPA. Вместо этого используйте функционал аутентификации SPA Sanctum.
Выдача токенов API
Чтобы начать выдачу токенов для пользователей, ваша модель User должна использовать трейт Laravel\Sanctum\HasApiTokens :
Вы можете получить доступ ко всем токенам пользователя с помощью отношения Eloquent tokens трейта HasApiTokens :
Полномочия токена
Sanctum позволяет вам назначать «полномочия» токенам. Полномочия служат той же цели, что и «права доступа» OAuth Scopes. Вы можете передать массив, содержащий строковые ключи полномочий, в качестве второго аргумента методу createToken :
При обработке входящего запроса, аутентифицированного Sanctum, вы можете определить, обладает ли токен указанными полномочиями, используя метод tokenCan :
Однодоменные запросы, инициированные пользовательским интерфейсом
Однако, это не обязательно означает, что ваше приложение должно позволять пользователю выполнять действие. Как правило, политики авторизации вашего приложения определяют, предоставлены ли токену полномочия, а также проверяют, разрешено ли самому экземпляру пользователя выполнять действие.
Например, если мы представим себе приложение, которое управляет серверами, это может означать проверку того, что токен авторизован для обновления серверов и что сервер принадлежит пользователю:
Защита маршрутов
Отзыв токенов
Вы можете «отозвать» токены, удалив их из своей базы данных, используя отношение tokens трейта Laravel\Sanctum\HasApiTokens :
Аутентификация SPA
Sanctum также обеспечивает простой метод аутентификации одностраничных приложений (SPA), взаимодействующих с API Laravel. Эти SPA могут существовать в том же репозитории, что и ваше приложение Laravel, или могут быть полностью отдельным репозиторием.
Для этого функционала Sanctum не использует никаких токенов. Вместо этого Sanctum использует встроенные в Laravel службы аутентификации сессии на основе файлов Cookies. Такой подход к аутентификации обеспечивает преимущества защиты от CSRF, аутентификации сессии, а также защищает от утечки учетных данных аутентификации через XSS.
Для аутентификации ваш SPA и API должны использовать один и тот же домен верхнего уровня, но они могут быть размещены на разных поддоменах.
Конфигурирование SPA
Настройка собственных доменов
Если вы обращаетесь к своему приложению через URL-адрес, содержащий порт (например, 127.0.0.1:8000 ), то вы должны убедиться, что указали номер порта вместе с доменом.
Посредник Sanctum
CORS и Cookies
Если у вас возникли проблемы с аутентификацией вашего SPA, который выполняется на отдельном поддомене, вы, вероятно, неправильно сконфигурировали параметры CORS (совместное использование ресурсов между разными источниками) или cookie сессий.
Выполнение аутентификации SPA
Защита от CSRF
Для аутентификации вашего SPA страница «входа» вашего SPA должна сначала сделать запрос к конечной точке /sanctum/csrf-cookie для инициализации защиты от CSRF для приложения:
Вход в систему
После того, как защита от CSRF была инициализирована, вы должны сделать POST-запрос к маршруту /login вашего приложения Laravel. Этот маршрут /login может быть реализован вручную или с использованием пакета безголовой аутентификации, такого как Laravel Fortify.
Конечно, если сессия вашего пользователя истекает из-за отсутствия активности, то последующие запросы к приложению Laravel могут получить ответ об ошибках 401 или 419 HTTP. В этом случае вы должны перенаправить пользователя на страницу входа в SPA.
Защита маршрутов SPA
Авторизация частных каналов вещания
Если вашему SPA необходимо аутентифицировать трансляцию по частным каналам или каналам присутствия, то вы должны вызвать метод Broadcast::routes в файле routes/api.php вашего приложения:
Аутентификация мобильного приложения
Вы также можете использовать токены Sanctum для аутентификации запросов вашего мобильного приложения к вашему API. Процесс аутентификации запросов мобильного приложения аналогичен аутентификации запросов стороннего API; однако, есть небольшие различия в том, как вы будете выдавать токены API.
Выдача токенов API мобильного приложения
Для начала создайте маршрут, который принимает электронную почту / имя пользователя, пароль и имя устройства, а затем обменивает эти учетные данные на новый токен Sanctum. «Имя устройства», присвоенное этой конечной точке, предназначено для информационных целей и может иметь любое желаемое значение. В общем, значение имени устройства должно быть именем, которое узнает пользователь, например «iPhone 12 Nuno».
Как правило, вы делаете запрос к конечной точке токена с экрана «входа в систему» вашего мобильного приложения. Конечная точка вернет токен API в виде простого текста, который затем может быть сохранен на мобильном устройстве и использован для выполнения дополнительных API-запросов:
При выдаче токенов для мобильного приложения вы также можете указать полномочия токена.
Защита маршрутов API мобильного приложения
Как ранее было задокументировано, вы можете защитить маршруты так, чтобы все входящие запросы аутентифицировались, назначив маршрутам охранника аутентификации sanctum :
Отзыв токенов API мобильного приложения
Чтобы пользователи могли отзывать токены API, выданные для мобильных устройств, вы можете перечислить их по имени вместе с кнопкой «Отозвать» в разделе «Настройки учетной записи» пользовательского интерфейса веб-приложения, например. Когда пользователь нажимает кнопку «Отозвать», вы можете удалить токен из базы данных. Помните, что вы можете получить доступ к токенам API пользователя через отношения tokens трейта Laravel\Sanctum\HasApiTokens :
Тестирование
Во время тестирования метод Sanctum::actingAs может использоваться для аутентификации пользователя и указания, какие полномочия должны быть предоставлены его токену:
Если вы хотите предоставить токену все полномочия, то вы должны указать * в списке полномочий метода actingAs :
Laravel
Введение
Laravel Sanctum предоставляет легкую систему аутентификации для SPA (одностраничных приложений), мобильных приложений и простых API на основе токенов. Sanctum позволяет каждому пользователю вашего приложения генерировать несколько токенов API для своей учетной записи. Этим токенам могут быть предоставлены способности /области, которые определяют, какие действия разрешено выполнять токенам.
Как это работает
Laravel Sanctum существует для решения двух отдельных проблем.
Токены API
Во-первых, это простой пакет для выдачи токенов API вашим пользователям без усложнения OAuth. Эта функция основана на токенах доступа GitHub » «. Например, представьте, что в настройках учетной записи » » вашего приложения есть экран, на котором пользователь может сгенерировать токен API для своей учетной записи. Вы можете использовать Sanctum для создания этих токенов и управления ими. Эти токены обычно имеют очень долгий срок действия (годы), но могут быть вручную отозваны пользователем в любое время.
Аутентификация SPA
Во-вторых, Sanctum существует для того, чтобы предложить простой способ аутентификации одностраничных приложений (SPA), которым необходимо взаимодействовать с API на базе Laravel. Эти SPA могут существовать в том же репозитории, что и ваше приложение Laravel, или могут быть полностью отдельным репозиторием, например SPA, созданным с помощью Vue CLI.
Для этой функции Sanctum не использует никакие токены. Вместо этого Sanctum использует встроенные в Laravel службы аутентификации сеанса на основе файлов cookie. Это обеспечивает преимущества защиты CSRF, аутентификации сеанса, а также защищает от утечки учетных данных аутентификации через XSS. Sanctum будет пытаться аутентифицироваться с помощью файлов cookie только тогда, когда входящий запрос исходит от вашего собственного интерфейса SPA.
Совершенно нормально использовать Sanctum только для аутентификации токена API или только для аутентификации SPA. Тот факт, что вы используете Sanctum, не означает, что вы обязаны использовать обе функции, которые он предлагает.
Установка
Вы можете установить Laravel Sanctum через Composer:
Наконец, вы должны запустить миграцию вашей базы данных. Sanctum создаст одну таблицу базы данных, в которой будут храниться токены API:
Затем, если вы планируете использовать Sanctum для аутентификации SPA, вам следует добавить промежуточное ПО Sanctum в группу промежуточного программного обеспечения api в файле app/Http/Kernel.php :
Настройка переноса
Аутентификация токена API
Выпуск токенов API
Чтобы начать выпуск токенов для пользователей, ваша модель User должна использовать черту HasApiTokens :
Вы можете получить доступ ко всем токенам пользователя, используя отношение tokens Eloquent, обеспечиваемое чертой HasApiTokens :
Способности жетона
Sanctum позволяет назначать токенам » способности «, аналогично областям действия OAuth » «. Вы можете передать массив строковых возможностей в качестве второго аргумента метода createToken :
При обработке входящего запроса, аутентифицированного Sanctum, вы можете определить, имеет ли токен заданную способность, используя метод tokenCan :
Охраняемые маршруты
Отмена жетонов
Аутентификация SPA
Sanctum существует для того, чтобы предложить простой способ аутентификации одностраничных приложений (SPA), которым необходимо взаимодействовать с API на базе Laravel. Эти SPA могут существовать в том же репозитории, что и ваше приложение Laravel, или могут быть полностью отдельным репозиторием, например SPA, созданным с помощью Vue CLI.
Для этой функции Sanctum не использует никакие токены. Вместо этого Sanctum использует встроенные в Laravel службы аутентификации сеанса на основе файлов cookie. Это обеспечивает преимущества защиты CSRF, аутентификации сеанса, а также защищает от утечки учетных данных аутентификации через XSS. Sanctum будет пытаться аутентифицироваться с помощью файлов cookie, только если входящий запрос исходит от вашего собственного интерфейса SPA.
Для аутентификации ваш SPA и API должны использовать один и тот же домен верхнего уровня. Однако они могут быть размещены в разных субдоменах.
Конфигурация
Настройка собственных доменов
Если вы обращаетесь к своему приложению через URL-адрес, который включает порт ( 127.0.0.1:8000 ), вы должны убедиться, что вы указали номер порта вместе с доменом.
ПО промежуточного слоя Sanctum
CORS & Файлы cookie
Если у вас возникли проблемы с аутентификацией с помощью приложения из SPA, которое выполняется на отдельном поддомене, вы, вероятно, неправильно настроили CORS (совместное использование ресурсов между источниками) или настройки cookie сеанса.
Проверка подлинности
Для аутентификации вашего SPA страница входа вашего SPA должна сначала сделать запрос к маршруту /sanctum/csrf-cookie для инициализации защиты CSRF для приложения:
Если запрос на вход будет успешным, вы будете аутентифицированы, и последующие запросы к вашим маршрутам API будут автоматически аутентифицироваться через cookie сеанса, который серверная часть Laravel отправила вашему клиенту.
Защита маршрутов
Авторизация частных каналов вещания
Аутентификация мобильного приложения
Вы можете использовать токены Sanctum для аутентификации запросов вашего мобильного приложения к вашему API. Процесс аутентификации запросов мобильного приложения аналогичен аутентификации запросов стороннего API; однако есть небольшие различия в том, как вы будете выпускать токены API.
Выдача токенов API
Для начала создайте маршрут, который принимает электронную почту /имя пользователя, пароль и имя устройства, а затем обменивает эти учетные данные на новый токен Sanctum. Конечная точка вернет токен Sanctum в виде обычного текста, который затем может быть сохранен на мобильном устройстве и использован для выполнения дополнительных запросов API:
При выпуске токенов для мобильного приложения вы также можете указать возможности токена
Защита маршрутов
Отмена жетонов
Тестирование
Во время тестирования метод Sanctum::actingAs может использоваться для аутентификации пользователя и указания, какие возможности предоставлены его токену:
Если вы хотите предоставить токену все способности, вы должны включить * в список способностей, предоставленный методу actingAs :
Если не указано иное, согласие на содержание этой страницы разрешено. CC BY 4.0.