Component Auth
Описание

Данный компонент используется для обработки действий, связанных с пользователями, таких как:

  • создание нового пользователя с отправкой ему уведомления на email и по СМС; удаление пользователя;
  • авторизация через форму входа;
  • аутентификация пользователя для контроля доступа к классам приложения;
  • личный кабинет пользователя (включая замену логина, пароля, аватара, электронной почты и телефона);
  • установка, замена и удаление фонов;
  • создание электронной подписи, подписание документов и проверка подписи.
Использование

Авторизация

Для получения формы входа можно использовать:

  • системный роут /xtables-login/enter, будет загружена отдельная страница только с формой входа;
  • публичный метод getLoginForm() для вставки формы на странице.

Пример получения формы входа.


use xtables\components\Auth\Login;

$login = new Login();
$login->getLoginForm();

При осуществлении входа через системную форму входа данные о логине и пароле направляются на сервер в зашифрованном открытым RSA ключом виде (end-to-end шифрование), что является необходимой при отсутствии SSL либо дополнительной при слабых SSL ключах мерой от прослушивания трафика.

При удачной авторизации приложение создает специальную сессионную переменную для пользователя, в которую сохраняет данные о нем. Данная авторизационная сессия управляется специальным механизмом и не связана с сессиями PHP, для использования которых служит класс xtables\base\Session. В качестве провайдера для авторизационных сессий используется тот же, что подключенный в настройках провайдер кеша (файловый, redis).

Доступны настройки авторизационных сессий в файле /config/config.php:

  • engine - по умолчанию, если данный параметр не установлен, то для авторизационных сессий будет использоваться тот же провайдер, что и является текущим для обычного кеша; если требует отличный от него провайдер, то нужно определить данный параметр, указав: type - тип, соответствующий одному из типов провайдеров кеша Cache::REDIS, Cache::FILE, Cache::MEMCACHE, Cache::DB
    server - могут быть указаны дополнительные настройки, для провайдера Cache::DB здесь может быть указано имя подключения к базе данных из пула подключений, если не указано, то будет использоваться первое подключение из пула;
  • paralell - разрешены ли паралеллельные сессии, если да, то это дает возможность подключаться с одним логин-паролем к приложению с разных устройств для одновременной работы; если нет, то каждая последующая авторизация будет аннулировать все другие авторизации (данный режим используется по умолчанию);
  • min_life - минимальное время жизни сессии в секундах; по умолчанию составляет 120 сек. (2 минуты);
  • max_life - максимальное время жизни сессии в секундах, после которого такие сессии будут считаться устаревшими; по умолчанию составляет 1200 сек. (20 минут).

/**
 * special sessions for access purporses
 * @since version 1.5.3
 */
'access_ses' => [
    /**
     * by default (if not set) use cache other engine settings
     * if use Cache::DB sqlite is bad for access sessions
     */
    'engine' => [
        'type' => Cache::REDIS,
        /*
         * OR
         * 
        'type' => Cache::MEMCACHE,
        'server' => [
            [
                'host' => '127.0.0.1',
                'port' => 11211,
                'weight' => 100
            ]
        ]
         * 
         * OR
         * 
        'type' => Cache::REDIS,
        'server' => [
            'params' => [

            ],
            'options' => [

            ]
        ]
         * 
         * OR
         * 
        'type' => Cache::DB,
        'server' => 'pgsql'
         * 
         */
    ],
    /**
     * set true to allow parallel user access sessions
     * by default (if not set) false
     * in type Cache::MEMCACHE paralell is always true
     */
    //'paralell' => true,
    /**
     * min life in sec; after regenerate
     * by default (if not set) 120
     * must be 7 or more
     */
    //'min_life' => 7,
    /**
     * max life in sec; after clear
     * by default (if not set) 1200
     * must be 21 or more
     */
    //'max_life' => 21
]

После авторизации в авторизационную сессию сохраняются данные о пользователе:

  • 'id' - идентификатор пользователя;
  • 'name' - имя пользователя;
  • @since cv1.7.25 'email' - email пользователя;
  • 'access' - уровень доступа;
  • 'key' - идентификационный ключ, включающий информацию об IP адресе и USER AGENT пользователя;
  • 'skey' - информация, необходимая для безопасного хранения служебного ключа в период работы с ним;
  • 'user_regdate' - дата регистрации пользователя;
  • 'csrf_token' - csrf токен.

Добавление данных в авторизационную сессию

Для добавления данных в авторизационную сессию нужно определить параметр access_data_in в файле /config/config.php. В данном параметре нужно указать абсолютный путь к файлу или имя callable, которые должны возвратить array с дополнительными данными.

При неудачной авторизации выводится информация об этом.

Для осуществления выхода с очисткой сессионных данных можно использовать системный роут /xtables-login/exitapp.

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

При создании компонентов проекта для обеспечения контроля доступа к классам приложения необходимо в класса контроллерах наследовать базовый класс xtables\base\Controller и определять уровни доступа в методе accessLevels(): array|string. Если данный метод будет не указан, то умолчанию доступ к данному методам данного контроллера через роутер будет иметь только пользователь с высшими правами.

Access::FREE

Для свободного доступа к модулю нужно использовать константу FREE класса Access.


use xtables\components\auth\model\Access;
use xtables\base\Controller;

class SomeAppClass extends Controller
{
    public function accessLevels()
    {
        return Access::FREE;
    }
    
    //....................
}

Access::OK

В качестве ответа в методах, которые будут использоваться для отдельных проверок доступа, можно возвращать значение константы OK класса Access.


use xtables\components\auth\model\Access;
use xtables\base\Controller;

class SomeAppClass extends Controller
{
    public function accessLevels()
    {
        return $this->someCheck();
    }
    
    private function someCheck()
    {
        // some checks
        return Access::OK;
    }

    //....................
}

Уровни доступа к системным классам xtables, которые могут вызываться через системные роуты, определяются в настройках в файле /config/xtables-classes-access.php.

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

При инициализации приложения главный класс xtables/xTables создает экзепляр класса Access, который может быть использован для проверки уровней доступа в компонентах проекта. Доступ к экземпляру класса осуществляется через публичное статическое свойство $access.

Могут использоваться методы:

ses(string $name)

Получение данных из авторизационной сессии по имени.


xTables::$access->ses('id');

xTables::$access->ses('name');

has(string|array $access)

возвращает true при соответствии доступа (сочетает в себе однократный вызов метода set() и последующий вызов check()), в качестве аргумента в метод должен быть передан:

  • массив уровней доступа или строка с одним уровней доступа;
  • массив для вызова callable функции, которая должна возвратить массив уровней доступа или строку с одним уровнем доступа:
    func - название callable функции;
    params - параметры;

xTables::$access->has('some_access);

xTables::$access->has([
    'one_access',
    'other_access'
]);

xTables::$access->has([
    'func' => 'some\Callable::func',
    'params' => [
        'one' => 'some',
        'two' => 'two'
    ]
]);

hasHighest()

Возвращает true, если пользователь имеет высшие права в соответствии с настройками в файле /config/xtables-classes-access.php

getHighest()

Возвращает название уровня доступа пользователя с высшими правами согласно настройкам в файле /config/xtables-classes-access.php

isUser()

Возвращает true, если пользователь авторизован.


if (xTables::$access->isUser()) {
    // some action
}

anyUser()

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


class SomeController extends Controller
{
    public function accessLevels() {
        return xTables::$access->anyUser();
    }

}

set(array|string $access)

Добавление разрешенных уровней доступа; в качестве параметра в метод нужно передать строку с одним добавляемым уровнем доступа или массив с добавляемыми уровнями доступа.


xTables::$access->set([
    'one_access',
    'other_access'
]);

xTables::$access->set('some_access');

check()

Проверка на соответствие введенному массиву значений уровню доступа пользователя, хранящемуся в его сессии, метод возвращает true в случае успеха.

setLevelsFor(string $name, array|string $levels)

Установка дополнительных, помимо содержащихся в файле /config/xtables-classes-access.php уровней для первичной проверки уровня доступа.

getLevelsFor(string $name)

Получение уровней доступа к контроллеру с указанным именем для первичной проверки уровня доступа.


xTables::$access->getLevelsFor('base')

allLevels()

Возвратит массив со всеми уровнями доступа, определяемыми в файле /config/xtables-classes-access.php и динамически через метод setLevelsFor().


use xtables\xTables;

xTables::$access->set(['granted_level1', 'granted_level2']);
if (!xTables::$access->check()) {
    // some act if access check failed
    // return;
}

if (xTables::$access->hasAccess(['level1', 'level2'])) {
    // some action
}

if (xTables::$access->hasAccess([
        'func' => 'some/callable::func',
        'params' => [
            'param1',
            'param2'
        ]
    ])) {
    // some action
}

Установка фонов

Установка фонов осуществляется в личном кабинете пользователя.

Поддерживаются фоны и картинки-заставки на весь экран.
Для добавления или удаления фонов и картинок нужно добавить/удалить файлы в папках /images/backgrounds/full_screen и /images/backgrounds/textures.

Изменение внешнего вида формы, куда выводятся фоны, осуществляется в настройках в файле /config/User/backgrounds.php.

Электронная подпись

Создание электронной подписи осуществляется в личном кабинете пользователя.
Если определен файл настроек /config/ds/config.php, то в личном кабинете появится форма для создания электронной подписи и просмотра уведомления о сертификате.

Внешний вид уведомления о выпущенном сертификате может быть изменен в настройках в файле /config/ds/ds-cert.php.

Работа с электронной подписью обеспечивается в расширениях dsCerts, dsDocs, dsProvision.

Подписание файла через базовую форму
@since version 1.5.8

Для подписания файла через базовую форму можно использовать класс xtables\components\auth\model\SignDoc.

Необходимо:
Создать экземлпяр данного класса. Передать в него входящие параметры:

  • for_table - обязательно название sql таблицы, для которой был сохранен файл, для поиска подписываемого файла в таблице;
    данный параметр может быть определен в методе setPrimary;
  • for_id - обязательно номер идентификатора таблицы, соответствующей параметру for_table, подписываемого файла для поиска в таблице;
  • sign_button_path - обязательно роут для возврата из кнопки ПОДПИСАТЬ окна, где выбирается тип подписи и вводится пароль от закрытого ключа;
  • need_sign_type - необязательно название ключа типа подписи для установки на нем значения selected
  • only_sign_types - необязательно массив с типами подписей (имена ключей), которые должны присутствовать в форме подписания, другие показываться не будут;
  • form_sample - необязательно абсоблютный путь до файла с шаблоном формы подписания, если не определен, то по умолчанию используется шаблон из /config/ds/sign-file.php;
  • reset_tables - необязательно названия sql таблиц, кеш которых нужно очищать для компонентов TableView, CardView.

  • pass - обязательно данный параметр необходим при подписании файла и его автоматически передает базовая форма, необходимо обеспечить его передачу в SignDoc;
  • sign_type - обязательно данный параметр необходим при подписании файла и его автоматически передает базовая форма, необходимо обеспечить его передачу в SignDoc.

Также необходимо определить имена sql таблиц через методы:

setTable($table)

определить таблицу, в которую будет сохраняться подпись; если не определена, то умолчанию будет использоваться app_signature

setDocTable($docTable)

определить таблицу, из которой будут получаться данные по подписываемому файлу (путь, хранилище, хеш); если не определена, то умолчанию будет использоваться attachments

Класс содержит три базовых метода:

page()

выводит полную страницу с html head с формой подписания

form()

выводит только форму подписания, используя аякс диспетчер, загружая ее в #workflow шаблона xtables-basic

sign()

подписывает файл и возвращает информацию о результате подписи, используя аякс диспетчер, загружая его в #ds-body

Пример подписания файла через базовую форму класса xtables\components\auth\model\SignDoc:


use xtables\components\auth\model\SignDoc;
use xtables\base\Request;
use xtables\xTables;

private function getSignInited()
{
    $sign = new SignDoc(array_merge($this->params, [
        'for_table' => 'docs_for_sign',
        'sign_button_path' => '/ds-docs/sign',
        'reset_tables' => [
            'app_signatures',
            'docs_for_sign'
        ]
    ]));
    $sign->setTable('app_signatures') // not need if use default app_signatures table
         ->setDocTable('docs_for_sign_files');
    return $sign;
}

public function sign_document()
{
    $sign = $this->getSignInited();
    if (Request::isAjDi()) {
        xTables::$response->write($sign->form());
    } else {
        xTables::$response->write($sign->page());
    }
}

public function sign()
{
    $sign = $this->getSignInited();
    if (Request::isAjDi()) {
        xTables::$response->json($sign->act());
    }
}
Настройки

Используются различные настроки, описанные выше.