Wokół KSeF 2.0 narosło sporo nieporozumień: jedni szukają „uprawnień w certyfikacie”, inni traktują MCU jak osobny system bez związku z KSeF. W praktyce logika jest prosta – ale wymaga właściwego modelu logicznego, odmiennego od tokenów zakresie uprawnień.

Kluczowa zasada: uprawnienia pochodzą od osoby (usera). Certyfikat tylko identyfikuje osobę.

1) Skąd pochodzą uprawnienia w KSeF

W KSeF uprawnienia są przypisane do osoby w relacji do konkretnego NIP. To oznacza, że decyzja o dostępie zawsze wynika z tego, jakie prawa ma dana osoba do podmiotu.

  • Osoba może mieć uprawnienia do jednego lub wielu NIP-ów.
  • Uprawnienia mogą obejmować m.in. podgląd, pobieranie, wystawianie, administrację dostępem.
  • Certyfikat nie przechowuje ról. Zmiana certyfikatu nie zmienia Twoich praw – bo prawa są „na osobie”.
Schemat decyzji autoryzacyjnej
CERTYFIKAT KSeF (osobisty)
↓
OSOBA (user)
↓
UPRAWNIENIA (osoba ↔ NIP)
↓
OPERACJE API / DOSTĘP DO FAKTUR

2) Czym jest MCU i co tam faktycznie robisz

MCU (Moduł Certyfikatów i Uprawnień) to miejsce, gdzie zarządzasz mechanizmem dostępu: wnioskujesz o certyfikat oraz – w okresie przejściowym – możesz także generować tokeny.

Wniosek o certyfikat w MCU – co dzieje się „po kolei”

  1. Podajesz nazwę certyfikatu/klucza (dla swojej organizacji / integracji).
  2. Podajesz hasło do klucza prywatnego.
  3. MCU generuje klucz prywatny i udostępnia plik .key do pobrania.
  4. Po zakończeniu procesu otrzymujesz certyfikat publiczny (np. .pem/.crt).
Praktycznie: plik .key generuje MCU, a hasło nadajesz w MCU podczas wnioskowania. Ten komplet (certyfikat + .key + hasło) umożliwia uwierzytelnienie Twojej osoby w API.

3) Co jest potrzebne do autoryzacji przez API (wariant certyfikatowy)

Minimalny zestaw, który musi mieć zespół wdrożeniowy / integracja:

  • Certyfikat publiczny KSeF: .pem lub .crt
  • Klucz prywatny z MCU: .key
  • Hasło do klucza – ustawione w MCU podczas wnioskowania
Najczęstszy błąd: traktowanie certyfikatu jako „firmowego uprawnienia”. Certyfikat jest osobisty i działa tylko w imieniu osoby, do której jest przypisany.

4) Jak to wygląda w praktyce wdrożenia u Klienta

Jeżeli integracja ma działać stabilnie, trzeba dopilnować dwóch rzeczy:

  • Osoba, na którą jest certyfikat, musi mieć właściwe uprawnienia do danego NIP.
  • Pliki .key i certyfikat muszą być przechowywane bezpiecznie (hasło nie może „zginąć”).

Rekomendacja operacyjna (bez ryzyka przestoju)

Certyfikat ma określony okres ważności. W praktyce warto planować wymianę z wyprzedzeniem (rolling replace), aby nowy certyfikat wdrożyć zanim stary przestanie być akceptowany.

Konstatując powyższe: „Certyfikat identyfikuje osobę. Uprawnienia nadawane są na osobie. KSeF po certyfikacie rozpoznaje usera i dopiero wtedy pobiera jego prawa do NIP.”

5) Schemat wdrożenia certyfikatów dla integracji API (plan przejścia)

Cel: przejść z integracji tokenowych na integracje certyfikatowe w sposób kontrolowany, bez ryzyka przestoju i z cykliczną wymianą certyfikatów przed końcem ważności.

Rolling refresh (wdrożenie i cykliczna wymiana)

🔄 Rolling refresh – pętla wdrożeniowo-utrzymaniowa
Etap 1: Start na tokenach
Najpierw wdrażamy tokeny (z przypisanymi uprawnieniami) jako szybki sposób uruchomienia integracji.
Etap 2: Ustalenie osób do certyfikatów
Z Klientem ustalamy osoby, które będą „tożsamością integracji” (np. osoba z IT).
Etap 3: Migracja tokeny ➜ certyfikaty (do końca 2026)
Migrację wykonujemy sukcesywnie (rolling). Tokeny pozostają jako plan B w trakcie przełączeń, a integracje przechodzą na certyfikaty bez przestojów.
Etap 4: Rozwiązania oparte o certyfikaty
Rozwijamy AkceptujFaktury.pl oraz Integrator KSeF do Symfonii w oparciu o certyfikaty (model docelowy KSeF 2.0).
Etap 5: Planowanie wymiany przed końcem ważności
Ustalamy termin wymiany certyfikatu z wyprzedzeniem (np. ~11–12 miesięcy od wydania), zanim miną 2 lata ważności.
Etap 6: Podmiana w integracjach
Podmieniamy certyfikaty w konfiguracji integracji, wykonujemy test, przełączamy ruch i utrzymujemy krótki overlap (bez przestoju).
Etap 7: Następny termin i cykliczność
Ustawiamy kolejny termin aktualizacji certyfikatów u Klienta i wracamy do pętli (rolling refresh).
Uwaga praktyczna: certyfikat jest osobisty (przypisany do osoby), więc kluczowe jest, aby wskazana osoba miała właściwe uprawnienia do NIP. Certyfikat tylko identyfikuje osobę — uprawnienia są pobierane z usera.

6) Co jeśli osoba „od certyfikatu” już nie pracuje w firmie?

Ważne: certyfikat jest osobisty (przypisany do osoby). Jeśli ta osoba odchodzi, integracja w jej imieniu jest ryzykiem i wymaga formalnej zmiany po stronie Klienta.

Procedura „offboarding” (krok po kroku)

  1. Zgłoszenie do IT / Administratora KSeF – natychmiast po informacji o odejściu osoby.
  2. Cofnięcie uprawnień osoby w KSeF (relacja osoba ↔ NIP): podgląd/wystawianie/administracja – zgodnie z zakresem.
  3. Unieważnienie certyfikatu tej osoby w MCU (jeżeli był wykorzystywany w integracji API).
  4. Rotacja materiałów integracji:
    • usunięcie/wycofanie używanego .key i certyfikatu z serwerów integracji,
    • audyt, gdzie był wgrany certyfikat (produkcyjne instancje, backupy, środowiska testowe).
  5. Wskazanie nowej osoby „dla integracji” (najczęściej IT / administrator techniczny) i nadanie jej wymaganych uprawnień do NIP.
  6. Wygenerowanie nowego certyfikatu w MCU:
    • MCU generuje nowy .key,
    • hasło jest ustawiane w MCU,
    • pobieramy certyfikat .pem/.crt.
  7. Podmiana certyfikatu w integracjach (overlap / test / przełączenie ruchu) i ustawienie nowego terminu „rolling refresh”.
Rekomendacja wdrożeniowa: wybierajcie w organizacji stałą rolę techniczną (IT/administrator), a nie osobę „przypadkową”. Minimalizuje to ryzyko przestoju przy rotacji pracowników.