Błąd uwierzytelnienia w KSeF: statusy 415, 450 i 460 krok po kroku

Komunikat „błąd uwierzytelnienia użytkownika” to jeden z najczęstszych problemów przy podłączaniu programu albo sklepu do KSeF. Sam komunikat niewiele mówi. KSeF zwraca jednak konkretny status uwierzytelnienia z krótkim opisem przyczyny i to on wskazuje, co naprawić. W praktyce wystarczy rozróżnić trzy przypadki: brak uprawnień, problem z tokenem i problem z certyfikatem.

Jak przebiega uwierzytelnienie w API KSeF

Błąd może pojawić się na każdym z tych etapów. Jeśli program zwleka z odesłaniem odpowiedzi dłużej niż 10 minut, dostanie wyjątek 21111, nieprawidłowe wyzwanie autoryzacyjne. Statusy opisane niżej pojawiają się w trzecim kroku.

Status 415: uwierzytelnianie zakończone niepowodzeniem, brak uprawnień

Podpis i token są poprawne, ale osoba albo podmiot nie ma żadnych uprawnień w kontekście, w którym się loguje. Typowy przypadek: księgowa loguje się swoim certyfikatem w kontekście NIP klienta, a klient nie nadał jej uprawnień. Rozwiązanie jest po stronie właściciela firmy. Jak to zrobić, opisałem w tekstach o nadawaniu uprawnień w KSeF i uprawnieniach dla biura rachunkowego.

Status 450: błędny token

• Nieprawidłowy token albo nieprawidłowe kodowanie i szyfrowanie tokena: program źle przygotował dane. To błąd integracji, nie użytkownika.
• Token nieaktywny albo unieważniony: token został wyłączony w KSeF albo stracił ważność razem z uprawnieniami osoby, która go wygenerowała.
• Nieprawidłowy czas tokena: zegar serwera odbiega od czasu KSeF albo program użył starego znacznika czasu.
• Token nie może być użyty w kontekście: token wygenerowano dla innego NIP-u niż ten, w którym program próbuje się zalogować.

Więcej o tym, jak działa token i kiedy wygasa, piszę w tekście o tokenie KSeF.

Status 460: problem z certyfikatem

KSeF odrzuca certyfikat, gdy jest nieważny, odwołany, zawieszony, ma niezaufany łańcuch albo jest po prostu niepoprawny. Najczęściej chodzi o certyfikat, który wygasł, albo o pomyłkę między certyfikatem do uwierzytelnienia a certyfikatem do trybu offline. Jak je rozróżnić i odnowić, wyjaśniam w tekście o certyfikatach KSeF.

Rzadsze statusy: 425, 470 i 480

• 425: uwierzytelnienie unieważnione przez użytkownika razem z powiązanymi refresh tokenami. Trzeba zalogować się od nowa.
• 470: próba użycia metod autoryzacyjnych osoby zmarłej.
• 480: uwierzytelnienie zablokowane z powodu podejrzenia incydentu bezpieczeństwa. Wymaga kontaktu z Ministerstwem Finansów przez formularz zgłoszeniowy.

Kolejność sprawdzania przy błędzie uwierzytelnienia

1. 1.Odczytaj status i opis z odpowiedzi KSeF, nie z komunikatu programu.
2. 2.Sprawdź, w jakim kontekście (NIP) program się loguje i czy ten NIP jest właściwy.
3. 3.Sprawdź uprawnienia osoby lub tokena w tym kontekście.
4. 4.Sprawdź ważność certyfikatu albo tokena i zegar serwera.

Jak bezpiecznie przetestować logowanie

Każdą zmianę w logowaniu, np. nowy certyfikat albo nowy token, warto najpierw sprawdzić na środowisku testowym KSeF, gdzie można używać certyfikatów samopodpisanych i losowych NIP-ów. Dopiero potem przełącza się konfigurację na produkcję. Dobra integracja zapisuje przy każdym logowaniu status i opis z odpowiedzi KSeF, więc przy kolejnym błędzie widać od razu, czy chodzi o uprawnienia (415), token (450) czy certyfikat (460). Różnice między środowiskami opisałem w tekście o środowisku testowym KSeF.

Źródło: uwierzytelnianie w dokumentacji API KSeF 2.0.