.. _Integration_Common_Authentication:

Аутентификация и авторизация
############################

Выполнение запросов к API Продукта требует аутентификации и авторизации пользователя.

Механизм аутентификации основан на `JSON Web Tokens (JWT) <https://jwt.io/>`_.
Он заключается в получении и последующей передаче токена в HTTP-заголовке ``Authorization`` каждого запроса.

Механизм авторизации основан на системе разрешений пользователей.

Получение токена
****************

| Получение токена выполняется по логину и паролю. 
| Запрос: ``POST /token``
| HTTP-заголовки:

.. code-block::

    Content-Type: application/json
    Accept: application/json

Тело запроса:

.. code-block:: JSON

    {
        "Username": "логин",
        "Password": "пароль"
    }

В случае успешного выполнения запроса возвращается JSON, который содержит токен:

.. code-block:: JSON
    :emphasize-lines: 2

    {
        "access_token": "eyJh ... vnuE",                    // токен
        "expires_in": 86400,                                // срок действия токена в секундах
        "userId": "13",                                     // идентификатор пользователя
        "userName": "krabov@domain.com",                    // логин пользователя
        "displayName": "Эдуард Крабов",                     // отображаемое имя пользователя
        "roles": "[\"acceptor\",\"rejector\",...,\"user\"]" // набор разрешений, назначенных пользователю
    }

Передача токена
***************

Для выполнения прочих запросов к API нужно передавать токен в HTTP-заголовке ``Authorization``:

.. code-block::
    
    Authorization: Bearer access_token

где ``access_token`` – полученный на предыдущем шаге токен.

.. _Integration_Common_Authentication_TokenCachingAndUpdate:

Кеширование и обновление токена
*******************************

| Полученный токен нужно закешировать и использовать повторно для последующих запросов к API.
| Токен может стать невалидным. Это может произойти, если:

* закончился срок действия токена: в этом случае сервис в ответ на очередной запрос вернет статус 401 (``Unauthorized``);
* учетная запись была удалена либо был изменен пароль: в этом случае сервис в ответ на очередной запрос также вернет статус 401 (``Unauthorized``);
* был изменен набор разрешений пользователя: в этом случае сервис в ответ на очередной запрос вернет статус 403 (``Forbidden``).

При получении одного из статусов 401 (``Unauthorized``) или 403 (``Forbidden``) токен нужно запросить повторно.

Если повторный запрос токена завершен со статусом 401 (``Unauthorized``), то учетные данные невалидны. В этом случае следует использовать другие учетные данные.

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

.. warning::
    Не кешируйте токен в долговременном хранилище. Это не имеет смысла, так как токен имеет срок действия.
    Не кешируйте токен во внешнем хранилище в открытом виде. Это может привести к несанкционированному доступу к данным, в том числе к содержимому документов и паролям.
    Используйте шифрование, если по какой-то причине токен нужно закешировать во внешнем хранилище.

Шифрование токена
*****************

Токен - это зашифрованная строка, содержащая учетные данные пользователя.
После получения токена в заголовке запроса API Продукта пытается расшифровать его.

Ключ для расшифровки токена задается в файле конфигурации хоста ``appSettings.json`` для каждого HTTP-сервиса, в поле ``Jwt.Key``.
В поставке Продукта все API используют один и тот же ключ по умолчанию.

.. warning::
    
    Не используйте ключ по умолчанию для шифрования токенов и не передавайте ключ третьим лицам.
    Это может привести к несанкционированному доступу к данным, в том числе к содержимому документов и паролям.
    Меняйте ключ сразу после развертывания HTTP-сервисов.

Использование единого токена для всех API
=========================================

Все API Продукта могут использовать один и тот же ключ для шифрования токенов.

В этом случае токен, полученный в одном сервисе, подойдет для использования в другом сервисе, если в другом сервисе есть учетная запись пользователя с таким же именем.

.. _Integration_Common_Authentication_Permissions:

Разрешения пользователей
************************

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

Если разрешение не назначено пользователю или набор разрешений пользователя был изменен, то сервис в ответ на очередной запрос вернет статус 403 (``Forbidden``).
Если разрешение было удалено из набора разрешений пользователя, то в этом случае для доступа к выбранному ресурсу следует использовать другую учетную запись.

.. _Integration_Common_Authentication_DefaultAccounts:

Учетные записи по умолчанию
***************************

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

* администратор:
  
  * логин: ``admin@domain.com``
  * пароль: ``1234aA``

* пользователь:

  * логин: ``user@domain.com``
  * пароль: ``1234aA``

Учетная запись администратора имеет доступ к настройкам, но не имеет доступа к основному функционалу API.
Учетная запись пользователя, наоборот, не имеет доступа к настройкам, но имеет доступ к основному функционалу API.

.. warning::
    Не используйте учетные записи и пароли по умолчанию в продуктивной среде.
    Это может привести к несанкционированному доступу к данным, в том числе к содержимому документов и паролям.
    Используйте свои учетные записи и пароли.

.. note::
    Учетная запись пользователя может осутствовать в некоторых HTTP-сервисах.
    В этом случае для доступа к API от имени учетной записи по умолчанию следует использовать учетную запись администратора.