.. _spec_server_authentication:

Аутентификация пользователей
=============================

Введение
----------------------
Аутентификация — это процесс проверки подлинности пользователя или объекта, который пытается получить доступ к системе
или ресурсу. Аутентификация подтверждает, что пользователь является тем, за кого себя выдает, и предоставляет доступ на
основе предъявленных учетных данных.

После успешной аутентификации, сервер формирует :ref:`spec_server_authentication_token`, который
возвращается клиенту в Cookie :ref:`access_token<spec_server_authentication_token_ast>`.

HTTP-запрос, содержащий Cookie ``access_token`` c валидным токеном, считается аутентифицированным.

Для различных :ref:`точек доступа<uri_endpoint_reference>` системы Global доступны разные типы аутентификации.

**Frontend приложений Global**

- :ref:`Form<spec_server_authentication_form>`
- :ref:`OpenID<spec_server_authentication_openid>`
- :ref:`Proxy<spec_server_authentication_proxy>`


**Backend приложений Global и HTTP сервисы**

- :ref:`Basic<spec_server_authentication_basic>`
- :ref:`Bearer<spec_server_authentication_bearer>`
- :ref:`Proxy<spec_server_authentication_proxy>`


.. _spec_server_authentication_token:

Аутентификационный токен
----------------------------
Аутентификационный токен – это, по сути, цифровой "билет", который подтверждает личность пользователя при доступе к
системе. Он выдается системой после успешной аутентификации и позволяет избежать повторного ввода
логина и пароля при каждом обращении.

Токен аутентификации является строкой в формате: ``{тип}_{тело}``.

Где:

- ``{тип}`` — Тип токена.
- ``{тело}`` — Тело токена: :term:`хэш` или :term:`JWT`.

Типы токенов
~~~~~~~~~~~~~~~~
Тип токена определяет место валидации и алгоритм обработки содержимого токена.

.. note::

  За сервером приложений зарезервированы имена типов, начинающиеся с символа ``a``.

В текущей версии, сервер приложений формирует токены с типами:

.. _spec_server_authentication_token_ast:

- ``ast`` — Application Server Token

  Токен формируется сервером приложений после входа в систему Global с использованием имени пользователя и пароля.
  Токен возвращается клиенту в Cookie ``access_token``, привязанной к подмножеству адресов ``http[s]://{global.server}/{DATABASE}/``.
  Эта Cookie автоматически присоединяется ко всем запросам по адресам ``http[s]://{global.server}/{DATABASE}/``,
  выполняемым из браузера, аутентифицированного в системе Global.

  .. note::
    Токены ``ast`` устаревают через 48 часов после создания и автоматически обновляются через 12 часов, при работе
    пользователя с системой.

Валидация токенов других типов выполняется в :term:`GTK`, вызовом :java:meth:`CoreAuthProvider.loginBearer()`.

Типы аутентификации
----------------------

.. _spec_server_authentication_form:

Form
~~~~~~~~~~~~~~~~~~
Аутентификация выполняется сервером Global на основе учётных данных, переданных через форму входа в систему Global.

- При обращении к серверу Global, не аутентифицированный браузер пользователя направляется на страницу входа.
- Пользователь вводит свои имя и пароль в поля формы входа в систему Global .
- По нажатию кнопки "Вход" учётные данные передаются на сервер Global через тело HTTP POST запроса.
- Сервер выполняет проверку учётных данных в соответствии с :xsd:class:`настройками для базы данных<Configuration.Databases.Database.AuthenticationType>` в конфигурации сервера.
- В случае успешного завершения проверки учётных данных и перенаправляет браузер на запрашиваемый ресурс.

Адрес формы входа: ``http[s]://{global.server}/login/login.html``.

.. code-block:: xml
    :caption: global3.config.xml

    <security>
        <authenticators>
            <form/>
        </authenticators>
    </security>

Аутентификация через форму входа является умолчательным способом аутентификации и не требует явного включения в
конфигурации сервера. Секция ``<authenticators/>`` может отсутствовать.

.. note::
    Если в конфигурации указаны OpenId-провайдеры, аутентификация через форму входа по умолчанию отключается. При этом
    сама форма входа, без полей ввода логина и пароля, остаётся доступной. Нажатие кнопки "Вход" направляет браузер на
    адрес сервиса идентификации по умолчанию.

.. seealso::
    :xsd:class:`Configuration.Security.Authenticators.Form`

.. _spec_server_authentication_openid:

OpenID
~~~~~~~~~~~~~~~~~~
Аутентификация выполняется в стороннем сервисе, провайдере идентификации, взаимодействие с которым производится по протоколу `OpenID Connect<https://openid.net/developers/specs/>`__.

Примеры провайдеров идентификации: Azure Active Directory, Keycloak.

- При обращении к серверу Global, сервер формирует сеансовый ключ и направляет браузер пользователя на страницу провайдера идентификации.
- Пользователь сообщает свои учётные данные провайдеру идентификации (имя и пароль, цифровой ключ и т.д, в зависимости от провайдера).
- В случае успешного завершения проверки учётных данных, провайдер идентификации направляет браузер пользователя обратно, на сервер Global.
- Сервер Global, по сеансовому ключу, запрашивает у провайдера идентификации данные пользователя и токены доступа.
- В случае успешного получения данных пользователя от провайдера идентификации, сервер Global вызывает метод :java:meth:`CoreAuthProvider.loginOpenId()`,
  для сопоставления имени пользователя провайдера идентификации с пользователем системы Global, и перенаправляет браузер на запрашиваемый ресурс.

.. code-block:: xml
    :caption: global3.config.xml для Keycloak

    <security>
        <authenticators>
            <openId name="dev-test">
                <provider url="https://auth.g-sys.ru/realms/dev-test"/>
                <client id="<YOUR_ID_HERE>"
                        secret="<YOUR_SECRET_HERE>"
                        authMethod="post"
                        scopes="email,profile">
                </client>
            </openId>
        </authenticators>
    </security>

.. note::
    В конфигурации может быть указано несколько провайдеров идентификации OpenID Connect. В этом случае, провайдером по
    умолчанию будет являться первый или тот, у которого установлен атрибут ``<openId default="true"/>``.

Адрес провайдера на сервере Global: ``http[s]://{global.server}/login/openid/{name}``.

  ``{name}`` — это значение атрибута ``<openId name="dev-test"/>`` или имя сервера
  из атрибута ``<provider url="https://auth.g-sys.ru/realms/dev-test"/>``, если ``name`` не указано.

.. note::
    Если в конфигурации указано несколько провайдеров идентификации, для обращения к конкретному, требуется направить
    браузер по адресу этого провайдера.

При получении сервером Global не аутентифицированного запроса на корневой адрес ``http[s]://{global.server}/``, логика
работы зависит от свойства :xsd:attr:`Configuration.Security.Authenticators.OpenId.autoLogin`.

- true — выполнится перенаправление браузера на сервис идентификации по умолчанию.
- false — выполнится перенаправление браузера форму входа в систему Global ``http[s]://{global.server}/login/login.html``.

.. seealso::
    :xsd:class:`Configuration.Security.Authenticators.OpenId`

.. _spec_server_authentication_proxy:

Proxy
~~~~~~~~~~~~~~~~~~
Аутентификация пользователя с помощью прокси-сервера, через который проходят все запросы к серверу Global.

- При обращении к серверу Global, запрос проходит через прокси-сервер, где выполняется аутентификация средствами прокси
  или внешнего сервиса идентификации.
- После успешной аутентификации, прокси добавляет к HTTP-запросу заголовки:

  - ``X-Remote-User`` — имя пользователя.
  - ``X-Proxy-Token`` — аутентификационный токен прокси-сервера.

- Прокси направляет запрос к сервер приложений Global, по адресу содержащему имя решения ``http[s]://server.domain/{SOLUTION}/``.
- Сервер Global проверяет заголовки и вызывает метод :java:meth:`CoreAuthProvider.loginRemote()` для проверки токена
  прокси-сервера и получения списка привилегий пользователя.
- Если токен прокси-сервера валиден, пользователь считается аутентифицированным. Сервер Global разрешает доступ к запрашиваемому ресурсу.

.. code-block:: xml
    :caption: global3.config.xml

    <security>
        <authenticators>
            <proxy/>
        </authenticators>
    </security>

.. seealso::
    :xsd:class:`Configuration.Security.Authenticators.Proxy`

.. _spec_server_authentication_basic:

Basic
~~~~~~~~~~~~~~~~~~
Аутентификация выполняется сервером Global на основе учётных данных переданных через http-заголовок ``Authorization``.

Клиент должен передать в запросе:

- Имя пользователя
- Пароль
- Имя базы

Имя пользователя и пароль передаются через HTTP-заголовок:

- ``Authorization`` со значенеим ``Basic {Base64Cred}``

где: ``{Base64Cred}`` — строка ``user:password``, кодированная в `Base64`.

Имя базы может быть передано через (в порядке приоритета):

- Сегмент строки адреса. Пример: ``http://server/{DATABASE}/``
- HTTP-заголовок ``Database`` со значением ``{DATABASE}``
- HTTP-параметр ``Database`` со значением ``{DATABASE}``. Пример: ``http://server/?Database={DATABASE}``

где ``{DATABASE}`` — имя базы данных.

.. note::
    Если имя базы не передано ни одним из описанных способов, будет произведена попытка аутентификации с использованием
    имени базы по-умолчанию. База по умолчанию определяется из конфигурационного файла `global3.config.xml` (в порядке приоритета).

    - Значение атрибута ``<databases defaultDb="{alias}"/>``
    - Значение атрибута ``<database alias="DATABASE"/>`` первой базы в списке конфигураций ``<databases/>``

Проверка учётных данных для Postgres решения выполняется в :term:`GTK`, вызовом :java:type:`CoreAuthProvider.login()`.

.. _spec_server_authentication_bearer:

Bearer
~~~~~~~~~~~~~~~~~~
Аутентификация выполняется сервером Global на основе токена, переданного через http-заголовок ``Authorization``.

Клиент должен передать в запросе:

- :term:`Токен аутентификации`
- Имя базы

Токен аутентификации передаётся через HTTP-заголовок:

- ``Authorization`` со значением ``Bearer {Token}``

где: ``{Token}`` — строка с токеном аутентификации.

.. note::
    Токен может быть передан одним из способами:

    - Через cookie с именем ``access_token``
    - Через параметр с именем ``access_token``

Имя базы может быть передано через (в порядке приоритета):

- Сегмент строки адреса. Пример: ``http://server/{DATABASE}/``
- HTTP-заголовок ``Database`` со значением ``{DATABASE}``
- HTTP-параметр ``Database`` со значением ``{DATABASE}``. Пример: ``http://server/?Database={DATABASE}``

где ``{DATABASE}`` — имя базы данных.

.. note::
    Если имя базы не передано ни одним из описанных способов, будет произведена попытка аутентификации с использованием
    имени базы по-умолчанию. База по умолчанию определяется из конфигурационного файла `global3.config.xml` (в порядке приоритета).

    - Значение атрибута ``<databases defaultDb="{alias}"/>``
    - Значение атрибута ``<database alias="DATABASE"/>`` первой базы в списке конфигураций ``<databases/>``

Проверка токена для Postgres решения выполняется в :term:`GTK`, вызовом :java:type:`CoreAuthProvider.loginBearer()`.

Конфигурирование
----------------------
Определение перечня доступных способов аутентификации, для входа в приложения Global, производится в конфигурационном
файле сервера :ref:`global3.config.xml<global3_config_xsd>`, в разделе :xsd:class:`Configuration.Security.Authenticators`.

.. code-block:: xml
    :caption: global3.config.xml

    <security>
        <authenticators>
            <openId name="dev-test" default="true">
                <provider url="https://auth.g-sys.ru/realms/dev-test"/>
                <client id="<YOUR_ID_HERE>"
                        secret="<YOUR_SECRET_HERE>"
                        authMethod="post"
                        scopes="email,profile">
                </client>
            </openId>
        </authenticators>
    </security>