Authorization via Keycloak (SSO)

Keycloak is OAuth2 authorization software. Read more in the Keycloak documentation.

With the integration module you can set up authorization of your employees via Keycloak.

OAuth2 is an authorization protocol that allows one service to grant permissions to access a user's resources on another service. User processing and all checks are performed by the authorization server. The authorization server can be a third-party application, such as Google, Gosuslugi (ESIA), etc., or a server with Keycloak software installed.

Setup on the Keycloak side

Actions n the Keycloak side:

• configure the integration user (Client);
• create Client Roles for mapping to departments in BILLmanager;
• assign roles to employee (user) profiles.

To configure Keycloak for integration with BILLmanager:

1. Log in to the system.
2. Select the realm from the side menu.
   To create a new realm, click Create realm.
   
3. In the side menu, enter Clients:
   
   
   1. Create a user for integration with BILLmanager. To do this, click Create client:
      1. on the General settings tab:
         1. Client type — select OpenID Connect.
         2. Client ID — specify the ID. This value will need to be specified in the BILLmanager settings as client ID.
         3. Click Next.
      2. on the Capability config tab:
         1. Client authentication — enable the option.
         2. Service accounts roles — enable the option.
         3. Click Next.
      3. on the Login settings tab:
         1. Root URL — specify the BILLmanager address in the format https://<billdomain>/billmgr.
         2. Click Save.
            
   2. Go to edit the created integration user. Click on the Client ID in the table:
      1. Create roles for mapping to departments in BILLmanager: go to the Roles tab → click Create role.
         Create as many roles as there are departments in your BILLmanager.
         
      2. Assign roles to the integration user (client) in the Keycloak system: go to Service accounts roles → click Assign role → set Filter by clients. Select:
         • view-users;
         • view-clients.
      3. Go to the Credentials tab → save the value in Client secret field.
4. In the side menu, go to the User section:
   1. Create user profiles Fill in the fields:
      1. Username;
      2. Email — if email was not specified in the profile on the Keycloak side, it will need to be specified when trying to authorize in BILLmanager.
   2. Assign roles to employees:
      1. Click on an employee's name to open their profile settings.
      2. Go to the Role mapping tab → click Assign role → set Filter by client.
      3. Select the required roles corresponding to the departments in BILLmanager.
         

Setup on the BILLmanager side

Installing the module

To install the module, enter Integration → Modules → Authorization via Keycloak → click Install.

Configuring the module

To open settings, enter Integration → Modules → Authorization via Keycloak → click :

1. Integration settings:
2. 1. Keycloak API URL — specify the address of REST API of the Keycloak system.
   2. Realm — specify the realm name in Keycloak.
   3. Client ID — specify the Client ID in Keycloak.
   4. Client UUID — specify the client UUID в Keycloak. You can get this data from the address bar when editing a client in Keycloak. The value is located between "clients/" and "/settings".
   5. Private key — specify the client secret in Keycloak. The required value can be found in Keycloak under Client → edit the client settings → Credentials tab.
   6. IP addresses list — specify a list of IP addresses from which you want to allow authorization via Keycloak.
      You can specify individual addresses - 123.45.67.89, mask addresses - 123.45.67.0/24, or a range of addresses - 123.45.67.89-123.45.67.98.
      For employees who have a Keycloak link, the addresses provided will also be used to restrict access to the platform.
   7. Synchronization frequency — specify the frequency of running the cron job to synchronize users. The default value is 0 2 * * * * (every day at two o'clock in the morning). If you clear the field, the task will not be executed.
      
3. Configure department and Client Role correspondence:
4. 1. Click Add.
   2. Department — select a department in BILLmanager.
   3. Client Role — select a role in Keycloak.
   4. Click Ок.
5. Click Ок to save settings.
6. To upload data to BILLmanager from Keycloack, click User synchronization.

Available actions with mapping settings:

• Edit — you can edit the Keycloack role to which a department is mapped in BILLmanager.
• Delete.

Enabling authorization

To enable authorization via Keycloak in BILLmanager, enter Provider → Providers → select a provider → click Edit → Registration and authorization methods → enable the option Keycloak.

After that, the Keycloak icon will be displayed on the authorization form in BILLmanager.

If allowed IP addresses are specified in the module settings, the Keyloack authorization icon will be displayed only when the page is opened from an allowed IP address.

How Keycloak works

Keycloak is only responsible for authorization in the system. User permissions and access management remain in BILLmanager. When editing user data in BILLmanager, the information is not uploaded to Keycloak.

Authorization of an employee in BILLmanager via Keycloak

Conditions:

• employee account (user) is created in Keycloak;
• employee account is mapped to a role in Keycloack (the role is set for user in Keycloack).

How it works:

1. An employee opens the authorization page in BILLmanager.
2. If allowed IP addresses are specified in the settings, BILLmanager checks the user's IP address. If the IP address is included in the list, a page opens with the option to authorize via Keycloack.
3. An employee clicks the icon of authorization through Keycloak.
4. The Keycloak authorization page opens, where the employee enters their Keycloak login and password.
5. Keycloak verifies the employee's credentials.
6. If the employee's credentials are entered correctly, Keycloak redirects the employee to BILLmanager.
7. BILLmanager checks if an employee account is available:
   1. if the employee's account does not exist in BILLmanager, it will be uploaded from Keycloak. The employee is then redirected to BILLmanager.
   2. if the account exists in BILLmanager, the employee will be redirected to BILLmanager;
   3. If the employee's account exists in BILLmanager and in Keycloak, but the employee has not previously logged in via Keycloak, this authorization method will be saved. The employee is redirected to BILLmanager;
   4. if the employee's credentials are entered incorrectly, an error message will be displayed on the Keycloak or BILLmanager authorization page.

Uploading a new employee account to BILLmanager from Keycloak

Conditions:

• employee account (user) is created in Keycloak;
• employee account is mapped to a role in Keycloak (clientRoles is set for user).

How it works:

1. BILLmanager requests a list of users from Keycloak. Data is uploaded when a synchronization task is started or when an attempt is made to authorize a Keycloak user who is not yet in the BILLmanager system.
2. BILLmanager selects new users.
3. BILLmanager creates new users with information from Keycloak. Access permissions are assigned according to the department specified in the mapping.

Uploading changes of employee accounts to BILLmanager from Keycloak

Changing an employee's account also counts as turning a user on and off in Keycloak.

Conditions:

• employee's user account was changed in Keycloak;
• employee account exists in BILLmanager;
• employee account was uploaded from Keycloak to BILLmanager.

How it works:

1. BILLmanager requests a list of users from Keycloak.
2. BILLmanager selects users with discrepancies.
3. BILLmanager modifies user data with the information from Keycloak.

More details

Log files of interaction between BILLmanager and the Keycloak integration module are written to files:

• /usr/local/mgr5/var/omkeycloak.log — requests to Keycloak: obtaining an authorization token, generating links to go to Keycloak, requesting roles, requesting user information;
• /usr/local/mgr5/var/billmgr.log — error information.