Integration of the B2B platform on Bitrix with the Keycloak authorization system
In this article, I will talk about integration with Keycloak, a popular open source access management (IAM) product. Many companies use it to organize single sign-on (SSO) into their systems, which simplifies employee access to all applications. We already had experience working with client authorization on 1C-Bitrix: Site Management (BUS), but integration with the “king” of open source IAMs is a new challenge for us. In the article I will share what difficulties we encountered and why there is still no ready-made Keycloak integration module for Bitrix.
Client task
Our client is a leading global manufacturer of heating and ventilation systems, represented in more than 60 countries. The company decided to create an online store for its partners and for this we proposed using our B2B platform, built on the basis of 1C-Bitrix: Site Management (BUS). It helps automate sales processes and reduce costs.
However, the customer was not satisfied with standard authorization on the platform, since the company was already using a single sign-on (SSO) system through Keycloak for all its applications.
This is convenient: to log in to several applications at once, you only need to enter your login/password once.
Among the customer’s systems there was nothing on Bitrix, so there was no ready-made solution for integrating the B2B platform with Keycloak. In the process of implementing the platform, the developers had to go through and test several options.
Finding a solution
The Bitrix App Store does not have a ready-made integration module with Keycloak. This is because a universal approach for redirects, authentication, user creation and deletion is difficult to achieve – each system may have its own unique requirements.
We have previously worked with Keycloak and CRM Bitrix24, modifying the social services module for logging in through Keycloak. However, in this project, the client required deeper integration, without intermediaries in the form of social networks. Therefore, standard solutions were not suitable.
Initially, the idea was to connect 1C-Bitrix through the OpenID Connect (OIDC) module for Apache, which the customer used for other systems. But after several attempts, we realized that the module did not provide the necessary functionality with the platform, and decided to develop our own solution based on the Keycloak API and our platform API.
How the integration of Keycloak and 1C-Bitrix was implemented
We have implemented authorization through Keycloak using the OpenID Connect protocol. The main goal is to make the authorization process invisible to the user so that the transition between systems is smooth.
So that users do not feel the transition between systems, everything was done using hidden redirects.
To do this, from the very beginning we decided on the link to which we will redirect the user. Any link for interaction with keycloak is built according to the following principle:
auth – used to start the user authentication process;
logout – used to log the user out of the system;
token – used to receive, update or revoke tokens;
userinfo – used to obtain information about the user.
The GET parameters
response_type – response code that we expect in the response. Usually this code for the authorization code.
scope – the access area in which we want to work. Usually includes openid and may include other areas such as profile or email.
client_id – Client ID that is used for authentication.
redirect_uri – The URI to which Keycloak will redirect the user after authentication with the authorization code. redirect_uri must be encoded in percent-encoding format. You can put an authentication handler in this link.
All permanent parameters have been moved to the module settings and are specified during the initial integration setup.
If the settings are empty, then authorization will not work.
When a user visits the site, instead of an authorization form, he gets to a link like this:
Then it is identified on the Keycloak side.
If a user is authorized in the company’s Unified Personal Account (UPA), but his Keycloak profile does not allow him access to the B2B platform, then he will not be able to access it.
If the user is authorized in the ELC, then he is immediately redirected to the link redirect_uriwhere the GET parameters are passed code (authorization code).
By using code you can't get user information, but you can get access_token. This is necessary for the following reasons:
Code transmitted through the user's browser and can be intercepted. Therefore, it does not provide direct access to user resources. Access_token is transmitted in a secure manner.
Code is only valid for a short time and is intended for one-time use only to obtain access_token.
Once authenticated, the user is redirected back with an authorization code, which is then exchanged for access_token on the application server. This allows the application server to receive tokens securely, without the risk of leaking them through the browser.
Using the code as an access token would be insecure as it would make man-in-the-middle attacks easier. Therefore, after receiving the authorization code, the application makes a separate request to the Keycloak server to exchange the code for access_token.
In the handler we check for the presence of the parameter code. If it exists, then knowing it you can get it access_token. To do this, we make a request to Keycloak for a URL like:
The following parameters are passed in the body:
grant_type – the authorization type used, to obtain an access_token the value must be authorization_code;
code – authorization code received in the previous step;
client_id – client identifier used for authentication. It must match what was registered in Keycloak;
client_secret – client secret key;
redirect_uri – The URI to which keycloak will redirect the user.
If successful, the response comes access_tokenwhich is a JSON Web Token (JWT). It contains the data needed to interact with the API securely. Knowing access_token we get user information from Keycloak to log into Bitrix. To do this, you need to create a URL like:
Next, you need to authorize using a Bearer token, the value of which will be access_token. To do this, add the line to the request:
Authorization: Bearer YOUR_ACCESS_TOKEN
If successful, the handler will receive a response in JSON with information about the user:
Based on the data contained in the response, it is possible to determine whether a given user exists in the BUS (on a b2b platform). If not, then you can create it and immediately deactivate it so that the administrator can independently decide on its further configuration. Before activation, the user will see a “stub” indicating that the account is under verification.
As you can see, there is no password in the JSON with user information; it is generated on the B2B platform side. The password is a long randomly generated string. Thus, the platform can only be accessed through Keycloak. If the broker restricts a user’s access to any application, then he will not be able to log into it even if he has valid credentials.
If the user is found, he is automatically authorized on the platform.
Logging out of your account also occurs via a link created on the backend. When you click on the “Log out of account” button, you are logged out of your B2B platform account, then the user is redirected to Keycloak, where he logs out automatically.
The registration and password recovery functionality was not implemented – Keycloak is entirely responsible for this.
Please note that logging into the administrative part of 1C-BUS through a standard authorization form is also possible. This feature is required so that exchange with 1C remains available and runs without problems.
Individual scenarios and support
Our integration module is not universal – its logic, redirects and user creation depend on specific business processes and requirements. Each company may require your own improvements.
That's all. I will be happy to answer questions, ask in the comments! Or share your experience, it’s also interesting! 😉
And if you are a business and are looking for a solution for secure access control in your systems and want to integrate Keycloak with Bitrix – we are ready to help. We have experience implementing Keycloak as a full-time authorization broker. We will consider your tasks, offer a solution and provide support throughout the entire project.
