Инструкция по настройке приложения [Auth]
Установка доверенных отношений между клиентом и сервером
Приложение [Auth] используется для установки безопасных и доверенных отношений между клиентом и сервером. Это позволяет пользователям осуществлять аутентификацию и авторизацию в защищенных средах, передавая роли и права доступа между различными системами. В данной инструкции описаны шаги по настройке ключей и доверенных связей между клиентом и сервером.
Предварительные требования
Перед началом настройки убедитесь, что у вас есть следующие компоненты:
- Сервер: Система, которая будет выступать в роли сервера.
- Клиент: Система, которая будет выступать в роли клиента.
- Доменные имена серверной и клиентской сторон.
- Доступ к интерфейсу [Auth] на каждой из сторон (клиент/сервер). Для доступа требуется роль admin.
Общие рекомендации
- Безопасность: Убедитесь, что все ключи и сертификаты безопасно хранятся и недоступны для посторонних лиц.
- Проверка доменных имен: Убедитесь, что доменные имена клиента и сервера правильно введены для успешной настройки доверительных отношений.
- Логи: В случае возникновения ошибок, проверьте журналы (
logs) для подробного описания проблемы.
Инструкция по установке [Auth]
- Установите приложение [Auth] на обеих сторонах (на серверной и клиентской системах).
- После установки войдите в агентский интерфейс приложения для последующей настройки.
Генерация ключей
Пропустите этот этап, если на каждой из сторон уже есть своя пара ключей.
-
Установите приложение [Auth] на обеих сторонах (на серверной и клиентской).
-
На сервере:
- Перейдите в навигаторе в Auth → Crypto Keys.
- Нажмите Generate new pair. В результате страница обновится и на форме появятся две записи ключей – открытый и закрытый.
-
Повторите действие 2 на экземпляре клиента.
-
Произведите обмен открытыми ключами между сервером и клиентом. Для этого добавьте записи созданных открытых/public ключей на оба экземпляра:
- На сервере создайте запись ключа в Auth → Crypto Keys и скопируйте в поля записи соответствующие данные открытого/public ключа, созданного на экземпляре клиента, и сохраните запись.
- На экземпляре клиента создайте запись ключа в 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 | Да | Укажите тип авторизации. Доступные опции:
|
| 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.
Добавление доверенного сервера
Действие выполняется на стороне клиента:
- Перейдите в раздел 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'>Войти через <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 | Да | Укажите, что должно происходить при авторизации пользователя, соответствующего указанному пользовательскому критерию. Доступные опции:
|
| 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 | Да | Результат выполнения задачи.
|
Mapping Autoprovision
В таблице Mapping Autoprovision (ain_autoprovision) сохраняются записи о входе через [Auth], которые содержат информацию о том, с какой стороны (серверной или клиентской) был выполнен вход, ID пользователя, а также его роли и группы. Записи доступны только для чтения.
Роли и группы, выданные другой стороной, не отображаются на форме.
Поля формы 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 | Нет | Группы, которые назначены пользователю со сторо ны клиента. |