Инструкция по настройке приложения [Auth]

Установка доверенных отношений между клиентом и сервером

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

Предварительные требования

Перед началом настройки убедитесь, что у вас есть следующие компоненты:

Сервер: Система, которая будет выступать в роли сервера.
Клиент: Система, которая будет выступать в роли клиента.
Доменные имена серверной и клиентской сторон.
Доступ к интерфейсу [Auth] на каждой из сторон (клиент/сервер). Для доступа требуется роль admin.

tip

Общие рекомендации

Безопасность: Убедитесь, что все ключи и сертификаты безопасно хранятся и недоступны для посторонних лиц.
Проверка доменных имен: Убедитесь, что доменные имена клиента и сервера правильно введены для успешной настройки доверительных отношений.
Логи: В случае возникновения ошибок, проверьте журналы (logs) для подробного описания проблемы.

Инструкция по установке [Auth]

Установите приложение [Auth] на обеих сторонах (на серверной и клиентской системах).
После установки войдите в агентский интерфейс приложения для последующей настройки.

Генерация ключей

note

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

Установите приложение [Auth] на обеих сторонах (на серверной и клиентской).
На сервере:
1. Перейдите в навигаторе в Auth → Crypto Keys.
2. Нажмите Generate new pair. В результате страница обновится и на форме появятся две записи ключей – открытый и закрытый.
Повторите действие 2 на экземпляре клиента.
Произведите обмен открытыми ключами между сервером и клиентом. Для этого добавьте записи созданных открытых/public ключей на оба экземпляра:
1. На сервере создайте запись ключа в Auth → Crypto Keys и скопируйте в поля записи соответствующие данные открытого/public ключа, созданного на экземпляре клиента, и сохраните запись.
2. На экземпляре клиента создайте запись ключа в Auth → Crypto Keys и скопируйте в поля записи соответствующие данные открытого/public ключа, созданного на сервере, и сохраните запись.
В результате в таблице Crypto Keys (ain_crypto_key) будт отображаться три записи – две, сгенерированные на текущем экземпляре и одна, добавленная вручную со второго экземпляра.
После установки войдите в агентский интерфейс приложения для последующей настройки доверенного сервера и клиента.

Добавление доверенного клиента

Действие выполняется на стороне сервера:

Перейдите в раздел Auth → Trusted Clients.
Нажмите New, чтобы создать новую запись клиента.
Добавьте доменное имя клиента. Например, client.example.com.
Нажмите Save или Save and exit, чтобы сохранить запись.

Поля формы Trusted Client

Поле	Обязательно	Описание
Domain name	Да	Укажите доменное имя клиента.
Type	Да	Укажите тип авторизации. Доступные опции: Certificate JWT
Use authorization rules	Нет	Установите флажок, чтобы настроить правила авторизации (Authorization rules). Поле доступно, если в поле Type выбрано Certificate.
Authorization Rules	Нет	Настройте правила авторизации для пользователей. Поле обязательно, если флажок Use authorization rules установлен.
Client secret	Да	Укажите клиентский ключ. Поле доступно, если в поле Type выбрано JWT.

Настройка с JSON Web Token

При выбранном типе авторизации JWT настройка доверенного клиента требует добавления клиентского ключа (Client secret) – пароля, необходимого для обмена временного токена на JWT.

Пример

Для входа перейдите по ссылке вида https://test-server.simpleone.ru/auth/login-to?client_id=test&redirect_url=https://test.local/callback.php, в которой:

client_id – то, что указано в поле Domain name записи доверенного клиента.
redirect_url – URL, на который необходимо отправить пользователя потом, и куда будет передан временный токен через параметр ?code=....

При возникновении ошибки пользователь будет переадресован на страницу, указанную в redirect_url, а в параметрах ?error=1&error_message=... будет передан текст ошибки.

После получения временного токена обменяйте его на JWT, выполнив запрос к getTokenByAuthorizationCode.

Сопоставление временного токена и JWT хранится в таблице Temporary token mapping (ain_temp_token_mapping). После обмена на записи временного токена будет установлен флажок Used. Повторный обмен этого временного токена станет невозможным.

Конечные точки

/v1/api/auth/ro/getTokenByAuthorizationCode – используйте для обмена временного токена на JWT. Параметры:

client_id – то, что указано в Domain name записи доверенного клиента.
client_secret – клиентский ключ.
code – временный токен, полученный при переадресации.

/v1/api/auth/ro/user-info – используйте для получения данных о пользователе.

Для авторизации укажите в заголовке Authorization: Bearer JWT_TOKEN_HERE.

Пример скрипта PHP

Добавление доверенного сервера

Действие выполняется на стороне клиента:

Перейдите в раздел Auth → Trusted Servers.
Нажмите New, чтобы создать новую запись сервера.
Добавьте доменное имя сервера (например, server.example.com).
Нажмите Save или Save and exit, чтобы сохранить запись.

Поля формы Trusted Server

Поле	Обязательно	Описание
Domain name	Да	Укажите доменное имя.
Auto Provision	Нет	Установите флажок, чтобы разрешить автоматическое создание пользователей. Если флажок снят, доступ в систему будет закрыт для пользователей, записей которых нет в системе.
Get roles from trusted server	Нет	Установите флажок, чтобы разрешить системе передачу ролей и групп на клиент с помощью настроенных пользовательских критериев (User criteria) разделе Auth → Authorization Rules. Вы также можете настроить назначение ролей пользователям и добавление их в группы со стороны клиента в поле Authorization Rules формы Trusted Client.
Use authorization rules	Нет	Установите флажок, чтобы настроить правила авторизации (Authorization rules).
Authorization Rules	Нет	Настройте правила авторизации для пользователей. Вы можете добавить несколько записей правил авторизации. Поле обязательно, если флажок Use authorization rules установлен.

Настройка страницы авторизации

Если на форме доверенного клиента (Trusted client) вы указали Certificate как тип авторизации, разместите ссылку /auth/login-via на странице авторизации для входа через [Auth].

Например, разместите в подсказке виджета авторизации. Для этого добавьте ссылку в свойство simple.auth_page.help_info.ru. Ниже приведен пример настройки свойства и результат:

<p>Если Вам нужна помощь, пожалуйста, свяжитесь с нами</p>
<p>E-mail: <a href='mailto:service@example.com'>service@example.com</a></p>
<p>Телефон: <a href='tel:+7(555)30092019'>+7(555)30092019</a></p>
<p><a href='https://simpleone.ru/'>Перейти на страницу поддержки</a></p>
<p><a href='/auth/login-via'>Войти через&nbsp;<input type="image" height="17" src="/assets/img/logo-small.svg"></a></p> 

Проверка соединения

Выполнить вход на сервере и клиенте с использованием одной и той же учетной записи.
Проверьте, что учетная запись успешно работает на обеих системах.
В таблице Autoprovisioning Mapping (ain_autoprovisioning_mapping) появилась соответствующая запись.

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

Правила авторизации

Вы можете настроить правила авторизации для:

передачи ролей и групп,
добавления ролей и групп.

Правила авторизации могут передаваться как от клиента к серверу, так и от сервера к клиенту:

Передача от сервера к клиенту

Чтобы передавать роли и группы с сервера на клиент, настройте критерии пользователя (User Criteria) в разделе Auth → Authorization Rules.
На стороне клиента должен быть установлен флажок Get roles from trusted server.
Передача от клиента к серверу

Чтобы присваивать пользователям роли и группы со стороны клиента, настройте правила в поле Authorization Rules на форме Trusted Client.

Чтобы создать правило авторизации, выполните следующие шаги:

Перейдите в раздел Auth → Authorization Rule.
Нажмите New, чтобы создать новую запись, и заполните поля.
Нажмите Save или Save and exit, чтобы применить изменения.

Поля формы Authorization Rule

Поле	Обязательно	Описание
User Criteria	Да	Укажите пользовательский критерий, который будет применяться в текущем правиле авторизации.
Type	Да	Укажите, что должно происходить при авторизации пользователя, соответствующего указанному пользовательскому критерию. Доступные опции: Add groups – выберите, чтобы добавить авторизованного пользователя в определенные группы. Add roles – выберите, чтобы наделить авторизованного пользователя заданными ролями.
Groups	Да	Укажите группы, в которые будут добавлены авторизованные пользователи. Поле доступно, если в поле Type выбрано Add groups.
Roles	Да	Укажите роли, которые будут присвоены авторизованным пользователям. Поле доступно, если в поле Type выбрано Add roles.

Изменения правил авторизации

При изменении правил авторизации – редактировании списка ролей и групп, назначаемых при авторизации, данные о ролях и группах авторизованных пользователей также будет обновлена. Для этого, после изменении записи правил авторизации (Authorization rules) и при попытке авторизации пользователя, в системе создается запись задачи Auth Tasks на обновление списка ролей пользователя.

Auth Tasks

В таблице Auth Tasks (ain_auth_task) хранятся записи задач на создание и обновление ролей, групп и пользователей на стороне клиента. Каждая задача представляет собой скрипт, который запускается автоматически при следующей авторизации пользователя при помощи [Auth].

Записи создаются автоматически и доступны только для чтения.

Поля формы Auth Tasks

Поле	Обязательно	Описание
Name	Да	Название скрипта обновления ролей и групп пользователя.
From	Да	Домен, на котором были произведены изменения в составе ролей или групп, назначаемых пользователю при авторизации.
To	Да	Домен, пользователь которого авторизовался на сервере.
Parameters	Да	Обновленный список параметров, который должен быть передан авторизованному пользователю. Например, {"roles": [], "groups": [], "username": "admin", "userParam": {"email": "admin@email.com", "active": true, "company": "", "location": "", "last_name": "User", "department": "", "first_name": "Admin", "locked_out": false, "language_id": "156628684306541141", "timezone_id": "156076775207670452", "display_name": "Admin User", "date_format_id": "159836398504170273"}, "created_at": "2025-04-17 14:50:33", "expired_at": "2025-04-20 14:50:33", "request_id": "auth-req-id-81ff2ae3-0e8a-4f39-8764-40b8fc7eacc7", "server_name": "example.server.ru", "host_request": "stage003.dev.server.ru", "userAddedParam": {"photo": "", "is_override": "yes", "source_sys_id": "155931135900000001", "source_password_hash": "$2y$13$E1ZrwJdeJE/So5JC0Btmou9//jem7dkmTkR7s2xPCoDXpjW1kLJSS", "source_sys_created_at": "2019-09-30 00:00:00", "source_sys_created_by": []}} .
State	Да	Статус выполнения скрипта обновления ролей и групп авторизованного пользователя.
Result	Да	Результат выполнения задачи. Если в результате выполнения задачи запись пользователя балы создана или обновлена, в поле будет указан ID (sys_id) пользователя на целевом экземпляре и присвоенные роли и группы. Если в результате выполнения задачи был только обновлен список ролей и групп пользователя, в поле будет отражен только их актуальный состав для целевого пользователя.

Mapping Autoprovision

В таблице Mapping Autoprovision (ain_autoprovision) сохраняются записи о входе через [Auth], которые содержат информацию о том, с какой стороны (серверной или клиентской) был выполнен вход, ID пользователя, а также его роли и группы. Записи доступны только для чтения.

caution

Роли и группы, выданные другой стороной, не отображаются на форме.

Поля формы Mapping Autoprovision

Поле	Обязательно	Описание
From	Нет	Домен, с которого был произведен вход через [Auth].
To	Нет	Домен, на котором пользователь был авторизован при помощи [Auth].
Source user ID	Нет	ID пользователя на исходном экземпляре.
Created user ID	Нет	ID пользователя в системе, в которой пользователь был авторизован в результате.
Roles from server	Нет	Роли, которые назначены пользователю со стороны сервера.
Groups from server	Нет	Группы, которые назначены пользователю со стороны сервера.
Roles from client	Нет	Роли, которые назначены пользователю со стороны клиента.
Groups from client	Нет	Группы, которые назначены пользователю со стороны клиента.

Инструкция по настройке приложения [Auth]

Установка доверенных отношений между клиентом и сервером​

Инструкция по установке [Auth]​

Генерация ключей​

Добавление доверенного клиента​

Настройка с JSON Web Token​

Конечные точки​

Добавление доверенного сервера​

Настройка страницы авторизации​

Проверка соединения​

Правила авторизации​

Изменения правил авторизации​

Auth Tasks​

Mapping Autoprovision​