Модуль OAuth авторизации

OAuth (Open Authorization) — способ авторизации через сторонний сервис. Пользователь разрешает приложению использовать свои учётные данные — например, имя и email. При этом пароль от аккаунта не передаётся. Доступ к данным осуществляется по специальным правилам, которые поддерживает и приложение, и сервис. В BILLmanager реализован Authorization Code Flow из спецификации OAuth 2.0.

Логика работы

Модуль позволяет BILLmanager работать с внешними плагинами для Oauth. В статье в качестве примера используется интеграция с Яндекс — https://github.com/ISPsystemLLC/billmanager/tree/master/oauth/yandex , однако вы можете использовать другой плагин.

Авторизация происходит в два этапа. Пользователь отправляет внешнему сервису данные: например, имя и email. Сервис генерирует временный код авторизации и передаёт его BILLmanager. Затем BILLmanager обменивает полученные данные на информацию о профиле. Основные шаги:

1. Пользователь выбирает вход через OAuth-сервис (например, Яндекс) на странице авторизации BILLmanager.
2. BILLmanager перенаправляет пользователя на страницу авторизации стороннего сервиса.
3. Пользователь проходит аутентификацию в стороннем сервисе.
4. После успешного входа сервис перенаправляет пользователя обратно в BILLmanager с временным кодом авторизации.
5. BILLmanager:
   1. обменивает полученный временный код на токен доступа.
   2. запрашивает данные профиля пользователя.

Структура модуля

Модуль состоит из следующих компонентов:

1. XML-файл описания плагина xml/billmgr_mod_omyandex.xml — регистрирует метод авторизации в системе и определяет элементы интерфейса для настройки:
   1. Регистрация плагина:
      

      <plugin name="yandex">
          <group>oauth</group>
       </plugin>

      • plugin — элемент, регистрирующий модуль в системе;
      • name="yandex" — внутреннее имя метода авторизации;
      • group="oauth" — указывает, что модуль относится к группе OAuth-провайдера.
   2. Метаданные:
      Настройки провайдера

      <metadata name="project.edit" type="form" mgr="billmgr">
        <form>
          <page name="auth">
            <field name="auth_method_yandex" after="custom_methods">
              <input type="toggle" name="auth_method_yandex"/>
            </field>
          </page>
        </form>
      </metadata>

      • Настройка добавляет переключатель (toggle) на странице настроек провайдера, позволяющий включить или отключить вход через Яндекс.
      Параметры пользователя

      <metadata name="usrparam" type="form">
        <form>
          <page name="socnetwork">
            <field name="yandex_status">
              <input type="checkbox" name="yandex_status">
                <if value="on" hide="yandex_signup"/>
                <if value="off" hide="yandex_status"/>
              </input>
            </field>
            <field name="yandex_signup">
              <link name="yandex_signup_link" target="_self" referrer="yes"/>
            </field>
          </page>
        </form>
      </metadata>

      • usrparam — форма параметров пользователя;
      • socnetwork— вкладка «Социальные сети» в профиле пользователя;
      • yandex_status — поле позволяет привязать или отвязать аккаунт Яндекс;
      • yandex_signup — ссылка для привязки аккаунта.
2. Python-скрипт oauth/omyandex.py — реализует логику взаимодействия с OAuth-провайдером. Должен уметь обрабатывать команды :
   • make_url — формирует URL для перенаправления пользователя на страницу внешней авторизации;
     Пример вызова команды

     oauth/omyandex --command make_url --state {state} --response_type code --return_url {url}

     • state — произвольная строка для идентификации пользователя, для которого запрашивается токен;
     • response_type — тип запроса кода подтверждения. Значение для Authorization Code Flow всегда будет code;
     • return_url — URL-адрес, куда будет перенаправлен пользователь после авторизации во внешней системе.
   • get_user_data — выполняет обмен кода на токен и запрашивает данные пользователя.
     
     Пример вызова команды

     oauth/omyandex --command get_user_data --code {code} --return_url {url}

     • code — код, полученный от внешней системы после авторизации пользователя. Используется BILLmanager для запроса данных о пользователе из внешней системы;
     • return_url — URL-адрес, куда будет перенаправлен пользователь после авторизации во внешней системе.

   Обязательные параметры:

   • firstname — имя пользователя;
   • lastname — фамилия пользователя;
   • realname — полное имя (например, "Иван Иванов");
   • email — email-адрес;
   • id — уникальный идентификатор пользователя из внешней системы.
   Имя файла должно начинаться с префикса om, а оставшаяся часть имени должна соответствовать внутреннему названию метода авторизации из XML-файла. Расширение .py отбрасывается при установке.
3. Иконки методов авторизации. Файлы размещаются в директориях тем оформления. Имя файла совпадает с внутренним названием метода авторизации из XML-файла. Поддерживается формат .svg.
   • dist/skins/common/img/yandex.svg
   • dist/skins/dragon/default/yandex.svg

Пример реализации модуля

Интеграция на стороне Яндекс

Чтобы настроить авторизацию на стороне Яндекс ID:

1. Перейдите на страницу регистрации приложений Яндекс OAuth.
2. Укажите:
   1. Имя сервиса и Почту для связи.
   2. Платформы приложения: Веб-сервис.
   3. Redirect URI : https://example.com/billmgr?func=oauth.save.userdata&network=yandex
   4. Запрашиваемые права:
      1. Доступ к электронному адресу.
      2. Доступ к логину, имени, фамилии и полу.
3. Сохраните полученные CLIENT_ID и CLIENT_SECRET и укажите их в oauth/omyandex.py.

Подробнее о настройке на стороне Яндекс см. в документации Яндекс ID.

Пример настроек

Интеграция на стороне BILLmanager

Чтобы настроить авторизацию на стороне BILLmanager:

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.
2. Установите необходимые пакеты разработки : 
   
   Ubuntu, Astra Linux

   apt install coremanager-dev billmanager-corporate-dev billmanager-plugin-python-libs

   или
   AlmaLinux

   yum install coremanager-devel billmanager-corporate-devel billmanager-plugin-python-libs

   Репозитории подключаются автоматически при установке платформы.
3. Поместите файлы модуля в директорию /usr/local/mgr5/src/:
   

   cp -r /путь/к/вашему/модулю /usr/local/mgr5/src/yandex

   • /путь/к/вашему/модулю — путь к вашему модулю;
   • yandex — название модуля OAuth.
4. Перейдите в директорию проекта:
   

   cd /usr/local/mgr5/src/yandex

   • yandex — название модуля OAuth.
5. Соберите и установите модуль:
   

   make install

Пример страницы авторизации с установленными модулями Яндекс, VK, Google