-

docs/integration.rst

@@ -336,3 +336,122 @@ ARTA Synergy генерирует событие в случае,
             }
         }
     }
+
+
+Способы авторизации в ARTA Synergy
+----------------------------------
+
+REST API ARTA Synergy доступно только авторизованным пользователям.
+Тип авторизации — `BASIC HTTP`.
+Методы API выполняются от имени того пользователя,
+который авторизован. Имеются следующие типы авторизации:
+
+Авторизация по логину и паролю
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Авторизация пользователя по его логину и паролю приемлема в тех случаях,
+когда приложение может знать текущий логин и пароль пользователя, например:
+
+* Приложение предоставляет альтернативный интерфейс
+  к некоторым модулям Synergy
+  (мобильное приложение, десктопный клиент для хранилища)
+* Приложение представляет собой `server-side` утилиту для синхронизации,
+  для которого создан выделенный пользователь,
+  и его логин и пароль хранятся в конфигурационном файле на сервере.
+
+Для реализации данного типа авторизации надо передать в запросе заголовок
+``Authorization`` со значением
+
+``"Basic " + Base64("login" + ":" + "password")``
+
+Например:
+
++--------------------+--------------------------------------+
+| Логин              | `Administrator`                      |
++--------------------+--------------------------------------+
+| Пароль             | `123456`                             |
++--------------------+--------------------------------------+
+| Значение заголовка | `Basic QWRtaW5pc3RyYXRvcjoxMjM0NTY=` |
++--------------------+--------------------------------------+
+
+Сессионная авторизация
+~~~~~~~~~~~~~~~~~~~~~~
+
+Сессионная авторизации используется для встроенных WEB-модулей.
+При cессионной авторизации также используется тип — `BASIC HTTP`,
+но в качестве логина пользователя необходимо использовать
+значение `$session` и в качестве пароля —
+полученное значение `sso_hash`.
+
+Таким образом заголовок `Authorization` должен иметь значение:
+
+`Basic ` + Base64(`$session:` + `sso_hash`)
+
+Например:
+
++---------------------+------------------------------------------------------+
+| Значение `sso_hash` | `D3RONfC52dtJO5XgDyn5qUMv`                           |
++---------------------+------------------------------------------------------+
+| Значение заголовка  | `Basic JHNlc3Npb246RDNST05mQzUyZHRKTzVYZ0R5bjVxVU12` |
++---------------------+------------------------------------------------------+
+
+Кроме того, получить параметры авторизации можно с помощью переменной
+окружения основного WEB-приложения Synergy:
+
+* `$CURRENT_USER` - представляет собой JSON-объект следующего вида:
+
+```xml
+{
+  "id": "Идентификатор текущего пользователя",
+  "sso_hash": "hash-сумма для идентификации пользователя",
+  "surname": "Фамилия текущего пользователя",
+  "name": "Имя текущего пользователя",
+  "patronymic": "Отчество текущего пользователя"
+}
+```
+
+### Авторизация по ключам {#integration.auth.keys}
+
+Модуль, который хочет авторизоваться от имени какого-либо пользователя таким способом,
+должен сгенерировать для него ключевую пару,
+обеспечив сохранность закрытого ключа.
+Затем модуль сохраняет получивший открытый ключ для пользователя в Synergy,
+используя следующий вызов API:
+
+`kz.arta.synergy.server.api.rest.person.PersonService#generateUserAuthKey`
+
+Этот вызов назначает ключ тому пользователю, от имени которого выполняется.
+
+Параметр `user_token_expire_interval` регулирует интервал устаревания ключей авторизации.
+Пример настройки интервала:
+
+```sql
+	insert into options (id, value) values ('user_token_expire_interval', '5256000'); -- 10 лет
+```
+
+> Интервал устаревания ключа указывается в минутах. Значение по умолчанию `0`, то есть если ранее для
+данного пользователя был сгенерирован другой ключ, то предыдущий автоматически становится недействительным.
+
+Создать ключ можно только для существующего WEB-модуля,
+так как для этого требуется идентификатор приложения.
+Если у вас нет необходимости разрабатывать WEB модуль,
+но есть необходимость в использовании авторизации по ключам,
+можно создать такой модуль на уровне БД и отключить его использование
+в административном приложении SynergyAdmin для всех элементов оргструктуры.
+
+Использование этого ключа для авторизации аналогично использованию сессионного ключа.
+Тип авторизации `Basic HTTP`,
+в качестве логина пользователя надо использовать строку «`$key`»,
+в качестве пароля — полученный с помощью API ключ.
+
+Таким образом заголовок `Authorization` должен иметь значение:
+
+`Basic ` + Base64(`$key:` + `значение_ключа`)
+
+Например:
+
++---------------------+----------------------------------------------------------------------------------------------------------------------+
+| Значение ключа      | `MS03Y2Q0ZGU3YS0zYjRkLTQ2NjgtYWIyOC0zZDI1YzgxZGNmOGZfMjAxMy0xMC0zMSAxNzo0Mg==`                                       |
++---------------------+----------------------------------------------------------------------------------------------------------------------+
+| Значение заголовка  | `Basic JGtleTpNUzAzWTJRMFpHVTNZUzB6WWpSa0xUUTJOamd0WVdJeU9DMHpaREkxWXpneFpHTm1PR1pmTWpBeE15MHhNQzB6TVNBeE56bzBNZz09` |
++---------------------+----------------------------------------------------------------------------------------------------------------------+