OAuth authorization module

OAuth (Open Authorization) is a third-party service authorization method. The user authorizes the application to use their credentials, such as their name and email address. However, the account password is not shared. Access to data is subject to specific rules supported by both the application and the service. BILLmanager implements the Authorization Code Flow from the OAuth 2.0 specification.

How it works

The module allows BILLmanager to work with external plugins for Oauth. The article uses integration with Yandex as an example — https://github.com/ISPsystemLLC/billmanager/tree/master/oauth/yandex, but you can use a different plugin.
Authorization takes place in two stages. The user sends data to an external service, such as their name and email address. The service generates a temporary authorization code and sends it back to BILLmanager. BILLmanager then exchanges the received data for profile information. Main steps:

1. The user selects to log in via an OAuth service (e.g., Yandex) on the BILLmanager authorization page.
2. BILLmanager redirects the user to the third-party service's authorization page.
3. The user authenticates with the third-party service.
4. After successful login, the service redirects the user back to BILLmanager with a temporary authorization code.
5. BILLmanager:
   1. exchanges the received temporary code for an access token.
   2. requests the user's profile data.

Module structure

The module consists of the following components:

1. The XML file describing the plugin xml/billmgr_mod_omyandex.xml that registers the authorization method in the system and defines the interface elements for configuration:
   1. Plugin registration:
      

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

      • plugin — element that registers the module in the system;
      • name="yandex" — internal name of the authorization method;
      • group="oauth" — indicates that the module belongs to the OAuth provider group.
   2. Metadata:
      
      Provider settings

      <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>

      • The setting adds a toggle switch to the provider settings page, allowing you to enable or disable login via Yandex.
      User parameters

      <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 — user parameter form;
      • socnetwork — Social Networks tab in the user profile;
      • yandex_status — this field allows you to link or unlink your Yandex account;
      • yandex_signup — link for binding your account.
2. The Python script oauth/omyandex.py implements the logic for interacting with the OAuth provider. It must be able to process the following commands:
   • make_url — generates a URL to redirect the user to an external authorization page;
     Example of a command call

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

     • state — an arbitrary string to identify the user for whom the token is requested;
     • response_type —  confirmation code request type. The value for Authorization Code Flow will always be code;
     • return_url — the URL address to which the user will be redirected after authorization in the external system.
   • get_user_data —  exchanges the code for a token and requests user data.
     Example of a command call

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

     • code —  code received from an external system after user authorization. Used by BILLmanager to request user data from an external system;
     • return_url — the URL address to which the user will be redirected after authorization in the external system.

   Required parameters:

   • firstname — username;
   • lastname — user's last name;
   • realname — ull name (e.g., "John Doe");
   • email — email address;
   • id — unique user identifier from an external system.
   Filename must begin with the prefix om, and the rest of the name must match the internal name of the authorization method from the XML file. The .py extension is discarded during installation.
3. Authorization method icons. Files are placed in theme directories. The file name matches the internal name of the authorization method from the XML file. The .svg format is supported.
   • dist/skins/common/img/yandex.svg
   • dist/skins/dragon/default/yandex.svg

Module implementation example

Integration on Yandex side

To set up authorization on side of the Yandex ID:

1. Go to the Yandex OAuth application registration page.
2. Please specify:
   
   1. Service name and Email address.
   2. Platforms: Web services.
   3. Redirect URI : https://example.com/billmgr?func=oauth.save.userdata&network=yandex
   4. Data access:
      1. Access to email address.
      2. Access to username, first name and surname, gender.
3. Save the CLIENT_ID and CLIENT_SECRET you received and specify them in oauth/omyandex.py.

For more information about settings on the Yandex side, see Yandex ID documentation.

BILLmanager integration

To set up authorization on BILLmanager:

1. Connect to the server with the platform via SSH. For more information about connecting via SSH, see Workstation setup.
2. Install the necessary development packages:
   
   Ubuntu, Astra Linux

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

   or
   AlmaLinux

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

   Repositories are connected automatically when the platform is installed.
3. Place the module files in the directory /usr/local/mgr5/src/:
   

   cp -r /path/to/your/module /usr/local/mgr5/src/yandex

   • /path/to/your/module — path to your module;
   • yandex — OAuth module name.
4. Go to the project directory:
   

   cd /usr/local/mgr5/src/yandex

   • yandex  — OAuth module name.
5. Build and install the module:
   

   make install