JWT - co to jest? Definicja pojęcia KSeF
Co to jest JWT?
JWT (JSON Web Token) to standard tokenów używanych do bezpiecznej komunikacji między systemami. Token JWT to zaszyfrowany ciąg znaków, który zawiera informacje o użytkowniku i jego uprawnieniach.
W kontekście KSeF API 2.0, tokeny JWT są używane do autoryzacji - czyli potwierdzenia, że masz prawo wykonywać określone operacje w systemie (np. wysyłać faktury, pobierać dokumenty).
KSeF używa dwóch typów tokenów JWT: accessToken (token dostępowy) - służy do autoryzacji operacji i ma krótki czas ważności (kilkanaście minut), oraz refreshToken (token odświeżający) - służy do odświeżania accessToken bez ponownego logowania i ma dłuższy czas ważności (do 7 dni).
Jak działają tokeny JWT w KSeF?
Proces wygląda następująco: 1) Logujesz się do KSeF (używając Profilu Zaufanego, podpisu kwalifikowanego lub certyfikatu), 2) System KSeF wydaje Ci parę tokenów: accessToken i refreshToken, 3) Przy każdym wywołaniu API wysyłasz accessToken w nagłówku żądania, 4) System sprawdza token i jeśli jest ważny, wykonuje operację, 5) Gdy accessToken wygaśnie, używasz refreshToken do uzyskania nowego accessToken bez ponownego logowania.
accessToken vs refreshToken
accessToken (token dostępowy) - ma krótki czas ważności (kilkanaście minut), jest wymagany przy każdym wywołaniu API, zawiera informacje o uprawnieniach użytkownika. refreshToken (token odświeżający) - ma dłuższy czas ważności (do 7 dni), służy tylko do odświeżania accessToken, nie jest używany bezpośrednio do autoryzacji operacji. Taki podział zwiększa bezpieczeństwo - nawet jeśli ktoś przechwyci accessToken, będzie ważny tylko przez krótki czas.
Dlaczego tokeny wygasają?
Tokeny mają ograniczony czas ważności ze względów bezpieczeństwa. Jeśli ktoś nieuprawniony przechwyci Twój token, będzie mógł go używać tylko przez krótki czas. Dodatkowo, jeśli zmienisz hasło lub uprawnienia, wygasłe tokeny nie będą już działać. W KSeF API 2.0 możesz odświeżać tokeny bez ponownego logowania, więc nie jest to uciążliwe.
FAQ
Jak długo ważny jest token JWT w KSeF?
accessToken jest ważny przez kilkanaście minut (dokładny czas jest podany w tokenie). refreshToken jest ważny do 7 dni. Gdy accessToken wygaśnie, możesz użyć refreshToken do uzyskania nowego accessToken bez ponownego logowania.
Co zrobić, gdy token wygaśnie?
Jeśli masz ważny refreshToken, użyj go do odświeżenia accessToken. Jeśli refreshToken też wygasł, musisz zalogować się ponownie do KSeF (używając Profilu Zaufanego, podpisu kwalifikowanego lub certyfikatu). Programy księgowe zintegrowane z KSeF zwykle automatycznie odświeżają tokeny, więc nie musisz się tym martwić.
Czy tokeny JWT są bezpieczne?
Tak, tokeny JWT są bezpieczne, ponieważ: są podpisywane cyfrowo, więc nie można ich sfałszować, mają ograniczony czas ważności, zawierają informacje o uprawnieniach, więc system może sprawdzić, czy masz prawo do wykonania operacji. Ważne jest, aby nie udostępniać tokenów osobom trzecim i przechowywać je bezpiecznie.
Czy muszę rozumieć JWT, żeby korzystać z KSeF?
Nie, jeśli korzystasz z Aplikacji Podatnika KSeF (portalu webowego) lub programu księgowego zintegrowanego z KSeF, tokeny są zarządzane automatycznie. Wiedza o JWT jest potrzebna tylko programistom, którzy bezpośrednio integrują systemy z KSeF API.