Integracja

Zintegrowaliśmy system SNRWB z Węzłem Krajowym

Wdrożenie Węzła Krajowego dla aplikacji SNRWB w GUNB oparte o stworzenie bramki integrującej Keycloak-a z Węzłem Krajowym.

KLIENT

Główny Urząd Nadzoru Budowlanego (GUNB) to centralny organ administracji rządowej w Polsce, istniejący od ponad 80 lat. Wykonuje zadania związane z administracją architektoniczno-budowlaną i nadzorem budowlanym, zapewnia obsługę Głównego Inspektora Nadzoru Budowlanego (GINB). Obecne zatrudnienie to ponad 3 tysiące osób w różnych organach nadzoru budowlanego. 

GUNB pełni funkcję organu wyższego stopnia w stosunku do wojewodów i Wojewódzkich Inspektorów Nadzoru Budowlanego (WINB), kontroluje działanie organów administracji budowlanej i nadzoru budowlanego, oraz jest odpowiedzialny za wyroby budowlane wprowadzone do obrotu. Prowadzi szereg różnego rodzaju rejestrów.  

PARTNER

Drugim podmiotem, z którym wymagana była ścisła współpraca, jest Centralny Ośrodek Informatyki (COI) – rządowy organ zajmujący się cyfryzacją w Polsce. Wśród swoich zadań ma rozwój i obsługę systemów administracji publicznej, e-usług, państwowych zbiorów danych i systemów krytycznych. Wśród nich jest Węzeł Krajowy/Login.gov.pl i ePUAP. Zatrudnia ponad 1000 osób. 

Co ciekawego znajdziesz w artykule?

Zastanawiałem się, jak przekazać nasze doświadczenia i ująć temat integracji z Węzłem Krajowym Identyfikacji Elektronicznej, zwanym też Login.gov.pl, tak, aby powstał tekst wartościowy dla osób z obszaru zarządzania biznesem.  

Czyż nie jest wyzwaniem opisywanie wartości biznesowych i kompetencji w realizacji zadania, które składa się głównie z prac technicznych i specjalistycznych? Jak pokazać, że i tak zazwyczaj niezrozumiałe działania programistów były tym razem dla nich niełatwym doświadczeniem? Jak to ująć zrozumiałym językiem? 

Ocenę czy, to się udało pozostawiam Tobie. Tekst jest krótki, a przyda Ci się, jeśli Twoje oprogramowanie ma zostać zintegrowane z WK i jesteś za to odpowiedzialny/na. 🤨 

Jakiej przydatnej wiedzy możesz się spodziewać? Agenda wygląda następująco:   

Czym jest Węzeł Krajowy zwany też Login.gov.pl 

Zanim zacznę mówić o problemach, ich rozwiązaniach (jak sobie daliśmy radę 😉), kilka zdań wprowadzających.  

Po pierwsze warto zwrócić uwagę na nazewnictwo, co przyda się przy wyszukiwaniu informacji w sieci. Funkcjonują nazwy: 

  • Węzeł Krajowy (WK) – bardzo często spotykana w dokumentacji i na forach 
  • Login.gov.pl – tak się np. nazwa domena internetowa, jest to bardziej nazwa marketingowa dla końcowych użytkowników
  • Krajowy Węzeł Identyfikacji Elektronicznej (KWIE) lub Krajowy Węzeł Tożsamości (KWT) – cóż, to też się spotka 😉  

Gdzie umieścić Węzeł Krajowy na mapie systemów rządowych? Na pewno znasz profil zaufany ePUAP. Jest to dobry punkt zakotwiczenia myśli, bowiem ePUAP to część infrastruktury Węzła. 

Ogólnie chodzi o to, aby różne aplikacje z usługami publicznymi (np. państwowe e-Usługi) były dostępne w spójny sposób. Aplikacja zintegrowana z Węzłem może korzystać z dobrze zabezpieczonej identyfikacji użytkownika przez właśnie m.in. ePUAP, ale też bankowość elektroniczną, aplikację mObywatel, e-dowód, czy certyfikat kwalifikowany. Jest to całkiem wygodne i zrozumiałe.  

Co więcej, podmiot publiczny, taki jak na przykład jednostka samorządu terytorialnego, agencje rządowe, urzędy administracji publicznej, ma obowiązek integracji z Węzłem Krajowym. Jest tak nawet w przypadku, jeśli udostępnia dostęp do swoich systemów dla pracowników jednostek terenowych. 

Jak przebiega proces integracji z WK? 

Gdy zaczynasz, jako właściciel systemu informatycznego proces integracji, po pierwsze przygotuj się na trochę formalności i przebrnięcie przez wiele etapów. Całość podłączenia może nawet potrwać do kilku miesięcy, ale termin miesiąca też jest osiągalny.   

W pierwszym kroku Integrator, czyli Ty (tak, tak – trzeba poznać i przyzwyczaić się do wielu różnych określeń) składa wniosek do Ministerstwa Cyfryzacji o dostęp do środowiska testowego. Może to w Twoim imieniu robić np. software house, który przygotowuje system lub producent oprogramowania, które integrujesz. Może to też być ktoś z działu IT.  

Otrzymasz certyfikaty dostępu do tzw. symulatora oraz harmonogram prac. Po zakończeniu prób na symulatorze musisz wykonać szereg formalnych testów, a ich pozytywne przejście kończy się przekazaniem raportu przez COI (czyli Centralny Ośrodek Informatyki, wspomniany na samym początku artykułu) i wydaniem zgody na integrację.  

Mając w ręku zgodę składasz wniosek o dostęp do… środowiska integracyjnego (czyli takiego poważniejszego testowego). A więc jeszcze nie produkcyjnego! 🤨 

Na marginesie dodam, że tak rygorystyczna procedura podyktowana jest względami bezpieczeństwa – systemy rządowe na głębszym poziomie komunikacji nie będą współpracować z jakimś dziwnie zachowującym się oprogramowaniem. 

Do wniosku o dostęp testowy potrzebujesz podpisu kwalifikowanego. Następnie czekasz na kontakt. Pracownik COI przekaże dostęp do certyfikatów potrzebnych do testowego połączenia z WK, zgodnego z protokołem SAML 2.0.  

Rozpoczynasz prace integracyjne i po ich zakończeniu informujesz COI o gotowości do przeprowadzenia formalnych testów integracyjnych. Odbywają się one według otrzymanych scenariuszy przy ścisłej współpracy z COI. Finalnie otrzymasz raport. 

Gdy wszystko się udało, następnym krokiem będzie złożenie kolejnego wniosku do Ministerstwa – tym razem już o przyłączenie do samego Węzła Krajowego (czyli środowiska produkcyjnego). Załączasz raport. Po pozytywnej odpowiedzi od samego Ministra Cyfryzacji, pora na prace uruchomieniowe. Po nawiązania połączenia potrzebne są certyfikaty, które musisz zakupić we własnym zakresie.  

Podsumowując: cały proces podłączenia opiera się na przejściu przez 3 etapy dostępowe: symulatora, środowiska integracyjnego testowego i właściwego środowiska produkcyjnego Węzła Krajowego.  

Integracja z WK nie jest prosta – uwaga na pułapki 

No dobrze, nie wygląda to źle. Opis zmieścił się na jednej stronie 😉 Nie przez takie problemy, jako osoba mająca sporo doświadczenia w życiu, przechodziłeś/łaś, więc temat do ogarnięcia…  

Jak najbardziej! Jednakże przyda Ci się świadomość paru spraw. Oto przekaz prosto z placu boju – nasze własne doświadczenia! Niezależnie od tego, czy czytasz to z pozycji biznesowej, zarządczej, czy też jesteś osobą techniczną – znajdziesz cenne informacje, przygotowujące do integracji i ułatwiające przejście przez nią suchą stopą. 

Dokumentacja 

Ministerstwo udostępnia sporo różnego rodzaju dokumentów technicznych, których przeczytanie i zrozumienie jest absolutnie potrzebne zarówno do poprawnego złożenia wniosków, zdobycia certyfikatów jak i przy bezpośrednim kontakcie z COI.  

W trakcie prac technicznych pojawi się wiele różnych problemów, których rozwiązanie wymaga pomocy ze strony pracowników COI. Musisz rozumieć, co napiszą i sprawnie opisywać swoją sytuację, używając na przykład terminologii z dokumentacji Ministerstwa, jak również dokumentacji standardu SAML 2.0.  

Pokazując pracownikom COI, że Twoja własna praca domowa została odrobiona, sprawisz że chętniej Ci pomogą.  

Uwaga: bardzo dużo wiedzy można znaleźć też na forach dyskusyjnych (np. 4Programmers). Natomiast mogą być to informacje nie do końca pewne, czy aktualne. Patrz więc na daty i doświadczenie osób piszących.  

ChatGPT, czy inne modele LLM wyspecjalizowane w programowaniu, pomogą w zakresie implementacji protokołu SAML 2.0. Będą natomiast najprawdopodobniej halucynować jeśli chodzi o sam Węzeł Krajowy. 

Kompetencje wykonawcy 

Integracje z systemami państwowymi to wyzwanie z wielu różnych powodów. Z technicznego punktu widzenia szczególnie.  

Jednym z pierwszych przykładów na potwierdzenie tej tezy, jest ograniczona dostępność informacji w sieci. Stoi to w opozycji do przyzwyczajeń programistów w obecnych czasach. Deweloperzy działają bowiem na wysokim poziomie abstrakcji (często bliskim biznesowego). Wszystkie trudne kawałki kodu zostały napisane przez kogoś innego, istnieją świetne źródła informacji, gdzie prawie każdy problem jest opisany. Tworzenie aplikacji polega na powielaniu pewnych sprawdzonych wzorców po ich wcześniejszym wyszukaniu. Wyzwania, to głównie zrozumienie problemu biznesowego, wybranie odpowiednich cegiełek, ustalenie architektury  aplikacji + znajomość standardów ich projektowania.  

W przypadku integracji z WK sytuacja wygląda tak, że są już po części opisane, przetarte ścieżki oraz kawałki kodu, ale czasem prowadzą na manowce i znaczącą część rozwiązania trzeba odkryć samemu oraz przebrnąć przez problemy uruchomieniowe. Potrzebne jest do tego dobre zrozumienie niełatwego protokołu SAML 2.0, innych protokołów sieciowych, zagadnień kryptograficznych i związanych z bezpieczeństwem. Stworzenie rozwiązania, które nie jest w pełni bezpieczne, ale działa z WK, jest prawdopodobnym scenariuszem 

Dodatkową trudnością jest uzależnienie od informacji diagnostycznych, które nie są dostępne od ręki. Sprawność poruszania się programistów po wspomnianych w poprzednim akapicie dziedzinach, ograniczy ping-pong mailowy odbywający się przy wyjaśnianiu problemów pomiędzy wszystkimi aktorami. Ograniczy też towarzyszącą temu frustrację.  

Warto też zwrócić uwagę na to, że jeśli zmienisz wykonawcę w trakcie, nowy poświęci czas na wdrożenie się w temat. Być może też o uzyskanie dostępu dla nowego środowiska testowego (musi zostać zgłoszone do COI).  

Innymi słowy potrzebujesz od samego początku wykonawcy, który dobrze zna się na sprawach autentykacji i autoryzacji aplikacji, ma szerokie doświadczenie w sprawach sieciowych, rozumie protokoły szyfrowania, potrafi wyciągać wnioski z informacji zwrotnych.  

Jednocześnie osoby techniczne powinny posiadać zakres kompetencji miękkich, pozwalający na sprawny kontakt z COI, który nie doprowadzi do niepotrzebnych napięć i zakończy się bezkonfliktowym rozwiązaniem problemów. 

Czas 

Już wiesz, że integracja z WK to złożony proces. Uczestniczy w nim wiele osób. W zależności od podziału kompetencji może być ich więcej lub mniej. Każda dodatkowa osoba to dodatkowy narzut, bo sama musi zapoznać się z dokumentacją, a także wiedzieć, czego się od niej oczekuje i co się dzieje. To wszystko zajmuje czas i wpływa zarówno na poniesione koszty, jak i ostateczny termin realizacji wdrożenia. 

Przy naszej współpracy z GUNB przyjęliśmy też zasadę, że większość mailowej  komunikacji z COI otrzymują wszyscy zaangażowani w proces wdrożenia WK. Zalety takiego podejścia to: 

  • Dostępność kontekstu aktualnej sytuacji – nie trzeba przekazywać dodatkowych informacji w obrębie całego zespołu (brak dodatkowych maili, tłumaczeń, spotkań)
  • Transparentność – a więc lepsza informacja dla Ciebie, czyli Zamawiającego (Integratora), co się właściwie dzieje i dlaczego wystąpiły potencjalne problemy
  • Skrócenie procesu integracji – gdy wszyscy dostają maila, pojawia się zjawisko zwiększonej mobilizacji  
  • Ktoś z zespołu może zwrócić uwagę na popełniane błędy 

Wadą jest konieczność czytania wiadomości, które w sprzyjających okolicznościach mogłoby być pominięte, większy stres. Coś za coś, zdecyduj sam.   

Jeszcze jednym elementem, na jaki warto zwrócić uwagę, jest takie przygotowanie harmonogramu powstawania aplikacji, aby prace nad jego integracją z WK rozpoczęły się możliwie szybko, a produkcyjne uruchomienie nastąpiło znacznie wcześniej, niż podpisanie protokołów odbioru. Ryzyko kilkukrotnego wydłużenia pierwotnie przewidzianego czasu integracji jest znaczące. 

ROZWIĄZANIE

W ramach realizacji aplikacji SNRWB dla GUNB musieliśmy szybko wdrożyć integrację z Węzłem Krajowym. Terminy wynikające z SIWZ były bardzo napięte. 

W tym celu wykorzystaliśmy platformę  Keycloak – popularne narzędzie do obsługi autentykacji i autoryzacji użytkowników. Dzięki temu, w bardzo krótkim czasie udało się uruchomić funkcję SSO (Single Sign-On) umożliwiającą użytkownikom łatwe i wygodne logowanie.

Mieliśmy więc dużą dowolność w wyborze języka programowania, ponieważ w naturalny sposób bramka integrująca była osobną aplikacją. Wybór padł na Python/Django z uwagi na częściowe przetarcie ścieżek, dobrą znajomość tego tandemu, wysokie bezpieczeństwo i dojrzałość samego frameworka Django.  

Zwróć uwagę na to, że w każdym konkretnym przypadku kluczowe jest zrozumienie własnych potrzeb/sytuacji i dobranie sposobu implementacji integracji.  

Niekoniecznie musi być ona oparta o osobną aplikację, choć naszym zdaniem sam protokół SAML 2.0 temu sprzyja. Czy Twój system jest rozproszony? Korzystasz już z SSO? A może nie chcesz wchodzić w modyfikację starego kodu? Wtedy warto zrealizować integrację w podobny sposób, jak to zostało zrobione w naszym przypadku.    

REZULTATY

Projekt zakończył się pełnym sukcesem

Dodatkowo zyskaliśmy uznanie klienta, który obserwował sprawność procesu integracji.

10

Ekspresowa implementacja samej aplikacji bramki

4

Przejście przez wszystkie etapy integracji

40+

Wysłanych maili do Centralnego Ośrodka Informatyki (COI)

Technologie

  • Python/Diango
  • SAML 2.0
  • Keycloak 
  • Docker

Czas trwania

4 tygodnie

Zespół

2 osoby

Skontaktuj się z nami

Napisz