Download the PHP package sinbadxiii/phalcon-auth without Composer

Phalcon Auth

You can see an example of an application with authentication here sinbadxiii/phalcon-auth-example

Extended guards

• JWT Guard

Phalcon version

Unfortunately version 2 of the library no longer supports Phalcon 4.

PHP are supported

^7.4-8.1.

Install

Require the project using composer:

composer require "sinbadxiii/phalcon-auth:^v2.0.0"

Introduction

Phalcon Auth позволит вам создать систему аутентификации в вашем веб-приложении.

Система аутентификации имеет такие понятия как «Охранники» (Guard) и «Поставщики» (Provider), охранники определяют, как пользователи будут аутентифицироваться, например, используя стандартные Хранилища Сессии и файлов куки.

Провайдеры определяют, какие данные будут браться в качестве пользователей, и так же откуда будут извлекаться эти пользователи. Откуда будут извлекаться данные пользователей определяют Адаптеры (Adapter). Обычно это Phalcon\Mvc\Model и построитель запросов к базе данных.

Кроме того есть другие варианты адаптеров: файл или массив с данными. Можно создать свой адаптер, реализуя интерфейс адаптера. Об этом поговорим чуть позже.

Guards и Providers не следует путать с «roles» и «permissions» ACL. Auth и ACL следует использовать вместе, если требуется более точная надстройка доступа к узлам приложения. Например использовать роль manager со специфическими правами.

Быстрый старт

Полностью пример готового приложения с аутентификацией доступен по адресу sinbadxiii/phalcon-auth-example. Это типовой проект на Phalcon, который можно использовать как старт нового приложения, либо же просто ознакомиться с возможностями аутентификации на примере данного приложения.

Логика работы

Общий принцип работы аутентификации заключается в том, что пользователь вводит свое имя пользователя и пароль через форму входа. Если эти учетные данные верны, приложение сохранит информацию об аутентифицированном пользователе в сессии пользователя и будет считать пользователя "аутентифицированным". В случае использования "Запомнить меня" может быть создан файл cookie, который содержит идентификатор сессии, чтобы последующие запросы к приложению могли быть связаны с нужным пользователем. После получения идентификатора сессии из файла cookie приложение извлечет данные пользователя.

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

Подготовка базы данных

Для использования данных из бд, понадобится создать таблицу users.

Если необходимо будет использовать функцию "Запомнить меня" - RememberMe, которая позволяет хранить сеанс аутентификации пользователя длительное время, то так же понадобится таблица users_remember_tokens, ну и соответственно ее модель в виде App\Models\RememberToken.

Для быстрого создания таблиц вы можете импортировать файлы из папки db/users.sql, db/users_remember_tokens.sql, а так же db/create_auth_token_users.sql, если будете использовать в качестве Guard - Token, которому необходимо поле auth_token для корректной работы.

Managers

При создании аутентификации вы можете воспользоваться одним из двух менеджеров: Sinbadxiii\PhalconAuth\Manager или Sinbadxiii\PhalconAuth\ManagerFactory.

Manager

Если вы строго придерживаетесь философии фреймворка Phalcon и хотите вручную настроить все компоненты аутентификации, то вам понадобится класс Sinbadxiii\PhalconAuth\Manager - с помощью данного менеджера можно настроить охранника, адаптер поставщиков и распределить доступы пользователям.

В результате получился менеджер, который будет искать пользователей через модель User в таблице базе данных users. Результат аутентификации будет храниться в сессии, и куках, если выбрать "Запомнить меня". В качестве других аргументов нужно передать сервис провайдеры $this->security, $this->session, $this->cookies, $this->request, $this->eventsManager, которые будут необходимы при дальнейшем использовании охранника и адаптера поставщиков.

• public addGuard(string $nameGuard, GuardInterface $guard, bool $isDefault = false) - добавить охранника
• public guard(?string $name = null) - получить конкретного охранника или по заданного по дефолту
• public setDefaultGuard(GuardInterface $guard) - задать охранника по дефолту
• public getDefaultGuard() - получить охранника по дефолту
• public access(string $accessName) - назначить контроллеру определенный доступ
• public getAccess(string $accessName) - назначить требуемый доступ
• public setAccess(AccessInterface $access) - получить требуемый доступ
• public setAccessList(array $accessList) - зарегистрировать список доступов
• public addAccessList(array $accessList) - добавить список доступов
• public except(...$actions) - исключенные экшны из проверки доступа
• public only(...$actions) - обязательные экшны для проверки доступа
• public call() - magic call

Guards

На данный момент существует два вида Охранников, которые покроют 90% типовых задач создания аутентификации веб-приложений. Это Sinbadxiii\PhalconAuth\Guard\Session и Sinbadxiii\PhalconAuth\Guard\Token, указывая одного из этих охранников вы выбираете, что будете использовать в своем приложении, аутентификацию на основе сессий или токена.

Предположительно Сессии вы будете использовать в веб-приложениях после логина в личный кабинет,а Токен, например, в микро приложениях в качестве api сервисов. Но ничего вам не мешает применять или комбинировать охранников в нестандартных приложениях.

Session Guard

• public function __construct(AdapterInterface $adapter, SessionManagerInterface $session, Cookies $cookies, Request $request, EventsManagerInterface $eventsManager)
• public function attempt(array $credentials = [], $remember = false) - попытка аутентификации
• public function user() - получить аутентифицированного пользователя
• public function validate(array $credentials = []) - валидация входных данных
• public function getName() - получение имени сессии
• public function getRememberName() - имя куки при запомнить меня
• public function login(AuthenticatableInterface $user, bool $remember = false) - логин экземпляра пользователя
• public function loginById($id, bool $remember = false) - логин по Id пользователя
• public function once(array $credentials = []) - логин без сохранения пользователя в сессию
• public function logout() - выход
• public function getLastUserAttempted() - получение последнего попытавшегося залогиниться пользователя
• public function viaRemember() - проверка что пользователь был вытащен из Запомнить меня
• public function getUser() - получить пользователя
• public function setRequest(Request $request)
• public function setSession(SessionManagerInterface $session)
• public function setCookies(Cookies $cookies)
• public function getAdapter() - получить адаптер поставщика
• public function setAdapter(AdapterInterface $adapter) - назначить адаптера поставшика

Basic

• public function basic(string $field = 'email', array $extraConditions = []) - аутентификация через Basic Auth
• public function onceBasic(string $field = 'email', array $extraConditions = []) - аутентификация через Basic Auth без сохранения в сессию

Token Guard

Чтобы воспользоваться Sinbadxiii\PhalconAuth\Guard\Token, необходимо в качестве второго аргумента передать конфиг с названиями имя параметра запроса и поля в хранилище данных пользователей, например, поле таблицы users в бд:

Соответствено GET запрос должен будет иметь вид:

POST запрос:

или заголовок Authorization:

Помните, что каждый ваш запрос к приложению, должен сопровождаться параметром auth_token с токеном доступа.

• public function __construct(AdapterInterface $adapter, array $config, Request $request)
• public function user() - аутентифицированный пользователь
• public function validate(array $credentials = []) - валидация
• public function getTokenForRequest() - поулчить токен из запросов (GET, POST, Headers)
• public function setRequest(Request $request)
• public function getRequest()
• public function getAdapter()
• public function setAdapter(AdapterInterface $adapter)

Создание своего Охранника

Реализуя интерфейс Sinbadxiii\PhalconAuth\Guard\GuardInterface вы можете создать своего Guard.

Access

С помощью Доступов (Access) вы можете задавать и проверять требуемый доступ к тем или иным областям приложения, например в контроллер профиля пользователя разрешен доступ только аутентифицированным пользователям.

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

Задается доступ в конструкторе контроллера onConstruct().

Из коробки есть два основных вида доступа - аутентифицированный и гостевой:

• Sinbadxiii\PhalconAuth\Access\Auth
• Sinbadxiii\PhalconAuth\Access\Guest

Если доступ удовлетворяет условию в методе allowIf, то дается разрешение на дальнейшее использование контроллера, например в дефолтном auth условием является:

$this->auth->check() - проверка на аутентификацию пользователя, т.е. чтобы получить доступ к $this->auth->access('auth') нужно быть аутентифицированным, а вот условие у $this->auth->access('guest') прямо противоположно:

В случае если метод allowedIf() вернет true, то пользователь сможет идти дальше, если же результат будет равен false, то сработает метод неудачи redirectTo(), и приложение перенаправит пользователя, т.к. у каждого приложение логика перенаправлений может быть разная, то вам следует создать свои классы Access auth и guest, наследовав от дефолтных классов и переопределить метод redirectTo():

и

Чтобы создать свой Access, можно имплементировать интерфейс Sinbadxiii\PhalconAuth\Access\AccessInterface:

либо просто наследовав абстрактный класс Sinbadxiii\PhalconAuth\Access\AbstractAccess для более быстрого и гибкого использования кастомных доступов, например, давайте создадим доступ для пользователей, имеющих роль админа:

или пример проверки доступа для Http Basic Auth:

Регистрация доступов

Доступы должны быть зарегистрированы в системе аутентификации, если этого не сделать, то при запросе доступа $this->auth->access("auth") будет выдаваться ошибка, типа: Access with 'auth' name is not included in the access list.

Чтобы зарегистрировать доступы в системе, необходимо создать некоторое промежуточное программное обеспечение, подтипа middleware и прикрепить его к dispatcher приложения.

Минимальный вид класса App\Security\Authenticate будет таков:

А затем необходимо прикрепить его к сервиc-провайдеру dispatcher:

Свойство $accessList позволяет быстро добавлять новые уровни доступа в приложении, например, чтобы добавить новый доступ admin, достаточно создать класс с условием и добавить его в список $accessList:

Так же список доступов можно зарегистрировать непосредственно в Manager при создании сервис провайдера с помощью метода setAccessList():

Поставщики (Providers) и Адаптеры (Adapters)

Как уже было сказано ранее поставщики определяют какие сущности будут являться пользователями, например users или contacts, все зависит от контекста вашего приложения.

В настоящий момент существуют три вида адаптера:

• Sinbadxiii\PhalconAuth\Adapter\Model
• Sinbadxiii\PhalconAuth\Adapter\Stream
• Sinbadxiii\PhalconAuth\Adapter\Memory

Модель, файл и массив с данными в приложении. Все адаптеры наследуются от абстрактного класса Sinbadxiii\PhalconAuth\Adapter\AbstractAdapter, который имеет:

• public setModel(AuthenticatableInterface $model)` - назначить модель поставщика
• public getModel()` - получить модель поставщика
• public setConfig(array $config)` - установить конфиг
• public getConfig()` - получить конфиг адаптера

Адаптер поставщика Model

Для использования адаптера Model нам понадобится модель пользователя, например App\Models\User::class вида:

Чтобы при использовании в нашем приложении, не выдавалась ошибка:

PHP Fatal error: Uncaught TypeError: Sinbadxiii\PhalconAuth\Adapter\Model::validateCredentials(): Argument #1 ($user) must be of type Sinbadxiii\PhalconAuth\AuthenticatableInterface.

Т.е. модель User надо имплементировать от Sinbadxiii\PhalconAuth\AuthenticatableInterface, а если хочется использовать возможности функции RememberMe (Запомнить меня), то так же надо будет наследовать интерфейс Sinbadxiii\PhalconAuth\RememberingInterface: В конечном счете, ваша модель должна иметь класс следующего вида:

Модель App\Models\RememberToken будет иметь вид:

Интерфейс Sinbadxiii\PhalconAuth\AuthenticatableInterface имеет следущий вид:

а реализация "Запомнить меня" - Sinbadxiii\PhalconAuth\RememberingInterface:

Теперь можно использовать модель при создании менеджера:

Адаптер поставщика memory

Используя setData() можно задать массив данных с пользователями, который имеет вид:

• public setData(array $data) - массив с данными
• public getData() - получить массив с данными

Адаптер поставщика Stream

Если взять в качестве адаптера поставщиков users не Sinbadxiii\PhalconAuth\Adapter\Model, а файл Sinbadxiii\PhalconAuth\Adapter\Stream: то необходимо будет задать источник файла формата json, например, users.json, который имеет вид:

Возвращаемый пользователь в виде модели App\Models\UserSimple должен будет реализовывать интерфейс Sinbadxiii\PhalconAuth\AuthenticatableInterface, например:

но следует учитывать, что нельзя будет использовать функцию RememberMe (Запомнить меня), т.к. Stream не имплементирует интерфейс Sinbadxiii\PhalconAuth\RememberingInterface ввиду отсутствия возможности сохранить токен сессии в файлом хранилище пользователей (что не мешает вам реализовать эту функцию в своем охраннике на основе хранилища в файле).

• public setFileSource(string $pathSrcFile) - указать путь к файлу
• public getFileSource() - получить путь к файлу
• public setData(array $data) - массив с данными пользователей
• public getData() - получить массив с данными пользователей

Не рекомендуется использовать адаптеры stream и memory в реальных приложениях из-за их функциональной ограниченности и сложности управления пользователями. Это может быть полезно в прототипах приложений и для ограниченных приложений, которые не хранят пользователей в базах данных.

Создание своего адаптера поставщика

Интерфейс адаптера поставщика Sinbadxiii\PhalconAuth\Adapter\AdapterInterface имеет вид:

Так же для создания функционала "Запомнить меня" нужна реализация интерфейса Sinbadxiii\PhalconAuth\Adapter\AdapterWithRememberTokenInterface:

Manager Factory

Sinbadxiii\PhalconAuth\MangerFactory - это создание менеджера аутентификации с минимальными усилиями, если вы не хотите настраивать вручную менеджер аутентификации, а хотите быстро запустить сервис провайдер аутентификации, вы можете сделать это так:

Все, дальше ManagerFactory сделает все за вас, на основе вашего конфигурационного файла. По умолчанию используется конфигурация из $this->config->auth, если вы хотите использовать другую конфигурацию, отличную от $this->config->auth то можно передать в качестве первого аргумента другой конфиг:

Пример конфигурационного файла для использования Сессий

Итак, типичный пример конфигурационного файла приложения на основе Сессий. Файл может находится в папке конфигов config/auth.php или в глобальном файле config.php с доступом по ключу auth ($this->config->auth).

Т.е. приложение будет использовать guard = web. В свою очередь Охранник web основан на драйвере session и использует поставщика пользователей users, которые извлекаются через Адаптера model - App\Models\Users. Данный конфигурационный файл позволяет создавать различные комбинации охранников и поставщиков, разделяя доступы в вашем приложений.

Пример конфигурационного файла для использования Токена

Расширить охранников можно с помощью extendGuard и передать в качестве аргумента имя охранника, используемого в конфиге jwt, а так же Closure с передачей аргументов в новый класс охранника, например:

Вы можете расширить список адаптеров с помощью метода extendProviderAdapter, например:

Методы

Задать требуемый доступ к контроллеру

Метод access() позволит задать требуемый доступ к контроллеру, из коробки auth - для аутентифицированных, guest - для гостей.

Проверка аутентификации текущего пользователя

Чтобы определить, аутентифицирован ли пользователь, выполняющий входящий HTTP-запрос, вы можете использовать метод check(). Этот метод вернет true, если пользователь аутентифицирован:

Например, вы можете проверить на странице формы входа, что если пользователь вошел в систему, то не показывать ему форму ввода:

Получение аутентифицированного пользователя

При обработке входящего запроса вы можете получить доступ к аутентифицированному пользователю с помощью метода user(). Результатом будет провайдер, указанный в конфигурации config->auth, в соответствии с интерфейсом Sinbadxiii\PhalconAuth\AuthenticatableInterface.

Вы также можете запросить идентификатор пользователя (ID) с помощью метода id():

Попытка аутентификации

Метод attempt() используется для обработки попыток аутентификации из формы входа в ваше приложение:

Метод attempt() принимает в качестве первого аргумента массив пар ключ/значение. Значения в массиве будут использоваться для поиска пользователя в таблице базы данных пользователей. Итак, в приведенном выше примере пользователь будет получен по значению столбца имени пользователя. Если пользователь найден, хешированный пароль, хранящийся в базе данных, будет сравниваться со значением пароля, переданным методу. Вы не должны хешировать значение входящего запроса пароля, так как пароль уже автоматически хэшируется, чтобы сравнить его с хешированным паролем в базе данных. Аутентифицированный сеанс будет запущен для пользователя, если хешированные пароли совпадают.

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

Метод attempt() вернет true, если аутентификация прошла успешно. В противном случае будет возвращено false.

Указание дополнительных учетных данных

Вы также можете добавить запрос дополнительных данные в дополнение к электронной почте/имени пользователя и паролю. Для этого просто добавьте условия запроса в массив, переданный методу attempt(). Например, мы можем проверить, является ли пользователь опубликованным is_published:

"Запомнить меня"

Если вы хотите обеспечить функциональность «запомнить меня» в своем приложении, вы можете передать логическое значение в качестве второго аргумента метода попытки.

Если это значение равно true, пользователь будет аутентифицироваться на неопределенный срок или до тех пор, пока пользователь не выйдет из системы вручную с помощью logout(). Таблица users_remember_tokens содержит столбец строки токена, который будет использоваться для хранения токена «запомнить меня»:

Используйте метод viaRemember(), чтобы проверить, аутентифицирован ли пользователь с помощью файла cookie «запомнить меня»:

Аутентифицировать пользовательский экземпляр

Если вам нужно установить существующий пользовательский экземпляр в качестве текущего аутентифицированного пользователя, вы можете передать пользовательский экземпляр методу login(). Данный пользовательский экземпляр должен быть реализацией Sinbadxiii\PhalconAuth\AuthenticatableInterface.

Этот метод аутентификации полезен, когда у вас уже есть действующий экземпляр пользователя, например, сразу после регистрации пользователя в вашем приложении:

Аутентифицировать пользователя по идентификатору

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

Аутентифицировать пользователя один раз

Используя метод once() вы можете аутентифицировать пользователя в приложении для одного запроса. При вызове этого метода не будут использоваться сессии или файлы cookie:

Выход

Чтобы вручную разлогинить пользователя из вашего приложения, вы можете использовать метод logout(). После этого удалится вся информация об аутентификации из сессии пользователя, так что последующие запросы уже не будут аутентифицированы.

HTTP Basic Authentication

Базовая аутентификация HTTP обеспечивает быстрый способ аутентификации пользователей вашего приложения без настройки специальной страницы «входа в систему». Достаточно передать в заголовке Authorization, значение Basic и пары емейл (либо другое поле пользователя) и пароль, разделенные двоеточием и закодированые base64_encode()

Метод $this->auth->basic("email") позволит создать свой Access для использования доступа с помощью Auth Basic.

Аргумент email указывает на то, что поиск пользователя будет осуществляться по полям email и password. Указав другое поле, например username, поиск будет осуществляться по паре username и password:

После запроса, в сессию запишется пользователь, и последующие запросы, могут уже не содержать пользовательские данные в заголовке Authorization, до тех пор пока сессия не "стухнет".

Basic HTTP-аутентификация без сохранения состояния

Вы можете использовать базовую аутентификацию HTTP без сохранения пользователя в сессии. Это в первую очередь полезно, если вы решите использовать HTTP-аутентификацию для аутентификации запросов к API вашего приложения. Для этого можно создать Access, который вызывает метод onceBasic(), например:

После запроса, ни куки, ни сессия не будут содержать данные о пользователе, и следущий запрос так же должен содержать пользовательские данные заголовка Authorization, иначе будет вызвано исключение Sinbadxiii\PhalconAuth\Exceptions

Events

License

The MIT License (MIT). Please see License File for more information.