Certyfikat ePUAP dla systemu teleinformatycznego jak go uzyskać w 2025

Integracja systemu teleinformatycznego z platformą ePUAP wymaga certyfikatu ePUAP dla systemu teleinformatycznego bez niego brama komunikacyjna po prostu nie rozpozna Twojej aplikacji jako zaufanego nadawcy. Największa trudność nie polega na samym fakcie złożenia wniosku, lecz na zrozumieniu, dlaczego poszczególne pliki (CSR, magazyn pkcs12, certyfikat w formacie base64) muszą ze sobą współgrać w ściśle określonej kolejności. Poniższy przewodnik powstał na bazie oficjalnej dokumentacji ePUAP, w stanie wiedzy na 2025 rok, i opisuje procedurę krok po kroku z wyjaśnieniem mechanizmów kryptograficznych stojących za każdym etapem. Instrukcja dotyczy systemu „Legislator” jako przykładu integratora, ale schemat działa analogicznie dla każdego innego narzędzia komunikującego się z ePUAP.

• Kiedy potrzebujesz certyfikatu ePUAP i co on faktycznie robi
• Jak wygenerować CSR i magazyn store.p12 przed złożeniem wniosku
• Wniosek o certyfikat ePUAP krok po kroku w Strefie Urzędnika
• Import certyfikatu do magazynu pkcs12 komendą keytool
• Najczęstsze problemy i jak je rozwiązać

Kiedy potrzebujesz certyfikatu ePUAP i co on faktycznie robi

Certyfikat ePUAP dla systemu teleinformatycznego to nie jest dokument dla człowieka, lecz para kluczy kryptograficznych (publiczny i prywatny) opatrzona podpisem cyfrowym Ministerstwa Cyfryzacji, która pozwala platformie zweryfikować, że żądanie HTTP pochodzi od konkretnej, zarejestrowanej aplikacji. Bez tego certyfikatu ePUAP odrzuci każdą próbę wysłania pisma lub pobrania dokumentu nawet jeśli sama aplikacja działa bezbłędnie.

Potrzebują go integratorzy systemów obiegu dokumentów, producenci oprogramowania dla samorządów oraz firmy budujące mosty komunikacyjne między wewnętrznymi systemami klasy ERP, CRM czy legislacyjnymi (np. „Legislator”) a administracją publiczną. Wniosek składa osoba z uprawnieniami administratora konta ePUAP, ponieważ tylko administrator może podpisać formularz profilem zaufanym lub podpisem kwalifikowanym.

Mechanizm opiera się na kryptografii asymetrycznej: klucz prywatny pozostaje w Twoim magazynie store.p12 i nigdy go nie opuszcza, a klucz publiczny trafia do ePUAP w certyfikacie base64. Podczas każdego połączenia system podpisuje żądanie kluczem prywatnym, a platforma po stronie urzędu weryfikuje ten podpis kluczem publicznym z certyfikatu stąd wynika wymóg, by magazyn pkcs12 zawierał oba elementy razem. Jeżeli Twój system gubi się w parametrach technicznych, pierwszym sygnałem ostrzegawczym będzie właśnie brak takiego certyfikatu w konfiguracji integracji.

Jak wygenerować CSR i magazyn store.p12 przed złożeniem wniosku

Zanim w ogóle zalogujesz się do Strefy Urzędnika, musisz przygotować trzy rzeczy: plik CSR (Certificate Signing Request), magazyn certyfikatów w formacie pkcs12 (store.p12) oraz aktualny, publiczny adres IP serwera, na którym działa aplikacja. Te trzy elementy stanowią fundament całej procedury ePUAP podpisze tylko CSR pasujący do dostarczonego magazynu i wyśle certyfikat tylko na adres IP, który wskażesz we wniosku.

Generowanie klucza i CSR

CSR to plik tekstowy w formacie PEM, zawierający klucz publiczny oraz dane identyfikacyjne wnioskodawcy (nazwa systemu, organizacja, jednostka). Generuje się go najczęściej narzędziem keytool z pakietu JDK lub biblioteką OpenSSL, podając jako parametr ten sam magazyn store.p12, do którego później trafi gotowy certyfikat. Dzięki temu klucz publiczny z CSR i klucz prywatny w magazynie tworzą matematycznie spójną parę bez tego sparowania ePUAP nie będzie w stanie zweryfikować podpisu.

Przykładowa komenda OpenSSL generująca klucz prywatny 2048 bit i CSR w jednym kroku wygląda tak:

openssl req -new -newkey rsa:2048 -nodes -keyout klucz_priv.pem -out system.csr -subj "/C=PL/O=Nazwa firmy/CN=Legislator"

Aby następnie otrzymać magazyn store.p12 z kluczem prywatnym, możesz użyć:

openssl pkcs12 -export -in system.crt -inkey klucz_priv.pem -out store.p12 -name Legislator

W tym momencie jeszcze nie masz certyfikatu w miejsce system.crt wstaw tymczasowo pusty plik lub najpierw utwórz magazyn samego klucza prywatnego przez keytool -genkeypair i dopiero potem wygeneruj z niego CSR komendą keytool -certreq. Najważniejsze, by magazyn pkcs12 istniał i zawierał klucz prywatny, ponieważ import certyfikatu base64 w kolejnym kroku wymaga wskazania tego samego pliku.

Ustalenie publicznego adresu IP

ePUAP wymaga stałego, publicznego IP, z którego Twój system będzie się łączyć z bramą. Najszybszą metodą sprawdzenia bieżącego adresu jest wyszukanie frazy „what is my ip” w przeglądarce lub odwiedzenie strony whatismyipaddress.com. Alternatywnie, jeśli adres IP zarządza dostawcą chmury, sprawdź go w panelu administracyjnym serwera (AWS, Azure, OVH) albo w ustawieniach routera brzegowego.

W środowisku Windows możesz też użyć wiersza poleceń i połączyć wynik z zewnętrznym serwisem typu ipinfo.io, by upewnić się, że nie patrzysz na adres prywatny NAT. Bez stałego, publicznego adresu IP wniosek zostanie odrzucony na etapie weryfikacji, więc warto poświęcić na ten krok kilka dodatkowych minut.

Wniosek o certyfikat ePUAP krok po kroku w Strefie Urzędnika

Strefa Urzędnika to panel administracyjny ePUAP dostępny po zalogowaniu kontem posiadającym rolę administratora instytucji. To tam odbywa się cała procedura wnioskowa, podpisana profilem zaufanym lub kwalifikowanym formularz papierowy nie istnieje, co oznacza, że cały proces jest cyfrowy i śledzony w UPO.

Logowanie i nawigacja po formularzu

Po zalogowaniu do ePUAP wejdź w sekcję Udostępnianie usług, a następnie odszukaj pozycję Wydanie certyfikatu dla systemu zintegrowanego z ePUAP. System wyświetli listę dostępnych formularzy wybierz ten odpowiadający Twojemu typowi integracji (zazwyczaj oznaczony skrótem „WSC”) i kliknij przycisk Załatw sprawę, by uruchomić wniosek w kreatorze.

Czas wypełniania formularza to około 5 minut, o ile masz już przygotowane CSR i IP cały proces sprowadza się do wklejenia dwóch bloków tekstu i wpisania kilku identyfikatorów.

Wypełnianie pól wniosku

Pole Nazwa systemu teleinformatycznego przyjmuje dowolną etykietę (np. „Legislator”), która później widnieje w certyfikacie i ułatwia identyfikację po stronie ePUAP. W polu Adres domeny lub stały numer IP wpisz adres ustalonej wcześniej maszyny system nie akceptuje zakresów ani adresów prywatnych z klas 10.0.0.0/8, 192.168.0.0/16 czy 172.16.0.0/12.

Najważniejszym polem jest CSR do wystawienia certyfikatu. Wklej tam pełną zawartość pliku .csr wraz z nagłówkami -----BEGIN CERTIFICATE REQUEST----- i -----END CERTIFICATE REQUEST-----. Nagłówki nie są ozdobnikiem parser ePUAP odrzuci CSR bez nich, traktując go jako uszkodzony. Po wklejeniu system pokaże podgląd odczytanych pól (CN, O, C) jeśli wyświetlone dane różnią się od zamierzonych, przerwij i wygeneruj CSR ponownie z poprawnymi parametrami -subj.

Wysyłka i czas oczekiwania

Przed wysłaniem wniosek trzeba podpisać profilem zaufanym lub podpisem kwalifikowanym. Profil zaufany jest szybszy i wystarczający, o ile jesteś zalogowany jako administrator instytucji pozwala uniknąć kosztów kwalifikowanego podpisu elektronicznego. Po wysłaniu otrzymasz UPO (Urzędowe Poświadczenie Odbioru) i wniosek trafia do kolejki Ministerstwa Cyfryzacji.

Czas realizacji wynosi do 14 dni roboczych, choć w praktyce najczęściej mieści się w 5-7 dniach. Gotowy certyfikat ePUAP przychodzi w wiadomości e-mail na adres wskazany we wniosku plik ma nazwę certyfikat.txt i zawiera dane w formacie base64 z nagłówkami BEGIN CERTIFICATE. Jeśli po 14 dniach roboczych wiadomość nie nadeszła, sprawdź folder spam i skrzynkę administratora, a następnie otwórz nową sprawę w ePUAP z zapytaniem o status.

Import certyfikatu do magazynu pkcs12 komendą keytool

Po otrzymaniu pliku certyfikat.txt pozostaje ostatni krok techniczny: wgranie certyfikatu do tego samego magazynu store.p12, w którym wcześniej umieściłeś klucz prywatny. Bez tej operacji aplikacja nie będzie mogła podpisywać żądań do ePUAP, mimo że sam certyfikat został już wydany przez ministerstwo.

Komenda keytool -import

Narzędzie keytool dostarczane z JDK obsługuje magazyny pkcs12 i pozwala w jednym poleceniu zarówno dodać certyfikat, jak i zachować istniejący klucz prywatny. Poniższa komenda wczytuje certyfikat ePUAP do magazynu:

keytool -import -trustcacerts -alias Legislator -file C:Certyfikatycertyfikat.txt -keystore C:Certyfikatystore.p12 -storetype pkcs12

Parametr -alias musi być identyczny jak alias użyty przy tworzeniu magazynu jeśli klucz prywatny miał alias Legislator, a teraz wskażesz legislator, keytool zaimportuje certyfikat jako osobny wpis, a para klucz-certyfikat pozostanie rozbita. -storetype pkcs12 wymusza właściwy format magazynu bez tej flagi keytool domyślnie używa JKS, co w środowisku Java nowszym niż 9 generuje ostrzeżenia o deprecacji.

Po uruchomieniu komenda poprosi o hasło magazynu to samo, które ustaliłeś przy pierwszym tworzeniu store.p12. Jeśli je zgubisz, magazyn trzeba wygenerować od nowa wraz z nowym CSR, a poprzedni certyfikat unieważnić przez ePUAP.

Weryfikacja poprawności importu

Po imporcie uruchom keytool -list -keystore C:Certyfikatystore.p12 -storetype pkcs12 i sprawdź dwa elementy: alias musi wskazywać na wpis typu PrivateKeyEntry, a nie trustedCertEntry. Tylko PrivateKeyEntry oznacza, że magazyn zawiera oba komponenty: klucz prywatny i certyfikat ePUAP jako base64 w jednym rekordzie.

Drugim elementem weryfikacji jest test połączenia z bramą ePUAP większość systemów (w tym „Legislator”) posiada w panelu administracyjnym przycisk „Testuj połączenie z ePUAP”. Zielony status potwierdza, że certyfikat został rozpoznany i platforma przyjmuje podpisane żądania.

Najczęstsze problemy i jak je rozwiązać

Litówka w adresie IP to najczęstsza przyczyna odrzucenia wniosku system traktuje adres jako niezgodny z tym, z którego faktycznie przyjdzie żądanie. Zanim wyślesz formularz, skopiuj IP z dokładnie tego hosta, na którym uruchomiona jest aplikacja, i porównaj znak po znaku.

Drugą klasyczną pułapką jest wklejenie CSR bez nagłówków BEGIN/END albo przesłanie w polu CSR całego certyfikatu zamiast żądania. Jeżeli po imporcie w magazynie widnieją dwa osobne wpisy zamiast jednego PrivateKeyEntry, oznacza to, że alias się nie zgadza lub import trafił do innego magazynu niż ten, w którym znajduje się klucz prywatny.

Trzecim częstym błędem jest próba użycia certyfikatu bez klucza prywatnego aplikacja zgłasi wtedy błąd kryptograficzny „no private key found”. Pamiętaj, że plik certyfikat.txt nigdy nie zawiera klucza prywatnego; klucz ten generujesz sam i zostaje w Twoim magazynie pkcs12.

Stan wiedzy: 2025 rok. Procedura bazuje na oficjalnej dokumentacji ePUAP oraz wymaganiach technicznych Ministerstwa Cyfryzacji opublikowanych w BIP. Źródła: gov.pl/web/cyfryzacja/epuap, epuap.gov.pl (dokumentacja techniczna integratora), strona pomocy technicznej ePUAP oraz dokumenty RFC 7468 (format PEM) i RFC 7292 (format pkcs12).