OAuth authorization module

OAuth (Open Authorization) is a way to authorize through a third-party service. The user allows the application to use their credentials, for example, name and email. The account password is not passed. Access to data is granted according to special 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, but you can use another plugin.

Authorization takes place in two stages. The user sends data to the external service, for example name and email. The service generates a temporary authorization code and sends it to BILLmanager. Then BILLmanager exchanges the received data for profile information. Main steps:

1. The user selects sign-in through an OAuth service (for example, Yandex) on the BILLmanager authorization page.
2. BILLmanager redirects the user to the third-party service authorization page.
3. The user authenticates in the third-party service.
4. After a successful sign-in, 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.

The user can unlink a previously linked OAuth account in the settings (tab Client → User settings → External authorization services). When an active OAuth method is disabled, the system requests confirmation of the current BILLmanager password. This is a security measure that prevents accidental or unauthorized disabling of the external sign-in method.

Module structure

The module consists of the following components:

1. The plugin description XML file xml/billmgr_mod_omyandex.xml registers the authorization method in the system and defines the UI 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 on the provider settings page that lets you enable or disable sign-in through 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 parameters form;
      • socnetwork — the "Social networks" tab in the user profile;
      • yandex_status — the field lets you link or unlink a Yandex account;
      • yandex_signup — the link for linking an account.
2. 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 — creates a URL for redirecting the user to the external authorization page;
     Command call example

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

     • state — an arbitrary string for identifying the user for whom the token is requested;
     • response_type — the confirmation code request type. The value for Authorization Code Flow will always be code;
     • return_url — the URL where the user will be redirected after authorization in the external system.
   • get_user_data — exchanges the code for a token and requests user data.
     
     Command call example

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

     • code — the code received from the external system after user authorization. BILLmanager uses it to request user data from the external system;
     • return_url — the URL where the user will be redirected after authorization in the external system.

   Required parameters:

   • firstname — the user's first name;
   • lastname — the user's last name;
   • realname — the full name (for example, "Ivan Ivanov");
   • email — email address;
   • id — the unique user ID in the external system.
   The file name must start 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 dropped during installation.
3. Authorization method icons. The 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 the Yandex side

To configure authorization on the Yandex ID side:

1. Go to the Yandex OAuth application registration page.
2. Specify:
   1. Service name and contact email.
   2. Application platforms: Web service.
   3. Redirect URI : https://example.com/billmgr?func=oauth.save.userdata&network=yandex
   4. Requested permissions:
      1. Access to email address.
      2. Access to login, first name, last name, and gender.
3. Save the received CLIENT_ID and CLIENT_SECRET and specify them in oauth/omyandex.py.

For more details about configuration on the Yandex side, see the Yandex ID documentation.

Integration on the BILLmanager side

To configure authorization on the BILLmanager side:

1. Connect to the server with the platform over SSH. For more details about SSH connection, see the article Workstation setup.
2. Install the required 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 /usr/local/mgr5/src/ directory:
   

   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