Implementation of the National Node for the SNRWB application at GUNB, based on building a gateway that integrates Keycloak with the National Node.
The General Office of Building Control (GUNB) is a central government administration body in Poland that has existed for over 80 years. It carries out tasks related to architectural and construction administration and building supervision, and provides support to the Chief Inspector of Building Control (GINB). It currently employs over 3,000 people across the various building control authorities.
GUNB acts as the higher-level authority in relation to voivodes and the Voivodeship Inspectors of Building Control (WINB), supervises the activities of the building administration and building control authorities, and is responsible for construction products placed on the market. It maintains a number of different registers.
The second entity with which close cooperation was required is the Central IT Center (COI), a government body responsible for digitisation in Poland. Its tasks include developing and operating public administration systems, e-services, national data sets and critical systems. Among them are the National Node/Login.gov.pl and ePUAP. It employs over 1,000 people.
I wondered how to share our experience and present the topic of integration with the National Electronic Identification Node, also known as Login.gov.pl, so that the result would be a text of value to people in business management.
Isn’t it a challenge to describe business value and competence in a task that consists mainly of technical, specialist work? How do you show that the developers’ work, usually incomprehensible to others, was this time a difficult experience for them too? How do you put it in plain language?
I leave it to you to judge whether it worked. The text is short, and it will come in handy if your software is to be integrated with the Node and you are responsible for it. 🤨
What useful knowledge can you expect? The agenda is as follows:
Before I start talking about the problems and their solutions (how we coped 😉), a few introductory sentences.
First, it is worth paying attention to the naming, which will help when searching for information online. The following names are in use:
Where does the National Node fit on the map of government systems? You surely know the ePUAP trusted profile. It is a good anchor for your thoughts, because ePUAP is part of the Node’s infrastructure.
In general, the aim is for various applications offering public services (e.g. state e-services) to be available in a consistent way. An application integrated with the Node can use well-secured user identification through ePUAP, but also through online banking, the mObywatel app, the e-ID card or a qualified certificate. It is quite convenient and easy to understand.
Moreover, a public entity, such as a local government unit, a government agency or a public administration office, is obliged to integrate with the National Node. This applies even if it only gives employees of its local units access to its systems.
When you start the integration process as the owner of an IT system, first prepare for some formalities and for going through many stages. The whole connection may even take several months, but a timeframe of a month is achievable too.
In the first step, the Integrator, that is you (yes, you need to get to know and get used to many different terms), submits an application to the Ministry of Digital Affairs for access to the test environment. A software house preparing the system, or the vendor of the software you are integrating, can do this on your behalf. It can also be someone from the IT department.
You will receive certificates for access to the so-called simulator and a work schedule. After you finish the trials on the simulator, you must carry out a series of formal tests. Passing them ends with COI (the Central IT Center, mentioned at the very beginning of the article) handing over a report and giving its consent to the integration.
With the consent in hand, you apply for access to… the integration environment (a more serious test environment). So still not production! 🤨
Incidentally, such a rigorous procedure is dictated by security concerns: at a deeper level of communication, government systems will not cooperate with software that behaves strangely.
The test access application requires a qualified signature. Then you wait to be contacted. A COI employee will provide access to the certificates needed for a test connection to the National Node, compliant with the SAML 2.0 protocol.
You start the integration work and, once it is done, you notify COI that you are ready for formal integration tests. They are carried out according to the scenarios you receive, in close cooperation with COI. In the end you will receive a report.
When everything has gone well, the next step is to submit another application to the Ministry, this time to connect to the National Node itself (that is, the production environment). You attach the report. After a positive reply from the Minister of Digital Affairs himself, it is time for the launch work. Once the connection is established, certificates are needed, which you have to purchase yourself.
To sum up: the whole connection process rests on going through 3 access stages: the simulator, the test integration environment and the actual production environment of the National Node.
All right, it does not look bad. The description fit on one page 😉 You have been through worse problems in life, so this is a topic you can handle…
Absolutely! However, you will benefit from being aware of a few things. Here is a report straight from the battlefield: our own experience! Whether you are reading this from a business or management position, or you are a technical person, you will find valuable information to prepare you for the integration and help you get through it with dry feet.
Documentation
The Ministry provides many technical documents, and reading and understanding them is absolutely necessary, both for submitting the applications correctly and obtaining the certificates, and for direct contact with COI.
During the technical work many different problems will arise, and solving them requires help from COI staff. You must understand what they write and describe your situation efficiently, using, for example, the terminology from the Ministry’s documentation as well as the documentation of the SAML 2.0 standard.
By showing COI staff that you have done your own homework, you make them more willing to help you.
Note: a great deal of knowledge can also be found on discussion forums (e.g. 4Programmers). However, this information may not be entirely reliable or up to date, so look at the dates and the experience of the people writing.
ChatGPT or other LLMs specialised in programming will help with implementing the SAML 2.0 protocol. However, they will most likely hallucinate when it comes to the National Node itself.
Contractor competence
Integrations with government systems are a challenge for many different reasons, especially from a technical point of view.
One of the first examples confirming this is the limited availability of information online. This runs against developers’ habits these days. Developers work at a high level of abstraction (often close to the business level). All the hard pieces of code have been written by someone else, there are excellent sources of information where almost every problem is described. Building an application means reusing proven patterns after finding them. The challenges are mainly understanding the business problem, choosing the right building blocks, deciding on the application architecture + knowing the standards for designing them.
With integration with the National Node, the situation is that some paths and pieces of code are already described and well trodden, but sometimes they lead astray, and a significant part of the solution has to be discovered on your own, along with working through launch problems. This requires a good understanding of the demanding SAML 2.0 protocol, other network protocols, and cryptography and security issues. Building a solution that is not fully secure but works with the National Node is a likely scenario.
An additional difficulty is the dependence on diagnostic information that is not available right away. The developers’ fluency in the areas mentioned in the previous paragraph will reduce the email ping-pong that takes place while clarifying problems among all the parties. It will also reduce the frustration that goes with it.
It is also worth noting that if you change the contractor midway, the new one will spend time getting up to speed on the topic. Possibly also on obtaining access for a new test environment (it must be reported to COI).
In other words, from the very start you need a contractor who knows application authentication and authorisation well, has broad experience in networking, understands encryption protocols and can draw conclusions from feedback.
At the same time, the technical people should have a range of soft skills that allows efficient contact with COI, avoids unnecessary tension and ends in a conflict-free resolution of problems.
Time
You already know that integration with the National Node is a complex process. Many people take part in it, more or less depending on how responsibilities are divided. Each additional person is additional overhead, because they must familiarise themselves with the documentation and know what is expected of them and what is going on. All of this takes time and affects both the costs incurred and the final deadline of the implementation.
In our cooperation with GUNB we also adopted the rule that most email communication with COI goes to everyone involved in the National Node implementation. The advantages of this approach are:
The downside is having to read messages that could otherwise be skipped, and more stress. There is a trade-off, so decide for yourself.
Another element worth attention is planning the application development schedule so that the work on its integration with the National Node starts as early as possible, and the production launch happens well before the acceptance protocols are signed. The risk of the originally planned integration time stretching several times over is significant.
While delivering the SNRWB application for GUNB, we had to implement the integration with the National Node quickly. The deadlines resulting from the tender specification (SIWZ) were very tight.
For this we used the Keycloak platform, a popular tool for user authentication and authorisation. Thanks to it, we managed to launch SSO (Single Sign-On) in a very short time, allowing users to log in easily and conveniently.
This gave us a lot of freedom in choosing the programming language, because the integration gateway was naturally a separate application. We chose Python/Django because the path was partly well trodden, we know this pairing well, and for the high security and maturity of the Django framework itself.
Note that in every specific case the key is to understand your own needs and situation and to choose the way of implementing the integration accordingly.
It does not necessarily have to be based on a separate application, although in our opinion the SAML 2.0 protocol itself favours this. Is your system distributed? Do you already use SSO? Or perhaps you do not want to modify old code? In that case it is worth implementing the integration in a similar way to how it was done in our case.
We also earned the recognition of the client, who observed how efficient the integration process was.
4 weeks
2 people