• Backend i API
  • OTP w API bez błędów - ważność, limity prób i TOTP

OTP w API bez błędów - ważność, limity prób i TOTP

21 listopada 2026

Telefon z tarczą ochronną, obok kropki symbolizujące hasło i liczby, które mogą być Twoim kodem OTP.

Osoba wpisuje kod z SMS-a, ale ekran logowania nadal go odrzuca albo pozwala próbować bez końca. Kod OTP zwykle rozwiązuje takie wyzwanie, o ile backend pilnuje jego ważności, ponownego użycia i limitu prób; sam sześciocyfrowy ciąg nie zabezpiecza całego procesu.

Darmowe API do weryfikacji OTP. Zapewnia bezpieczne logowanie, chroniąc Twoje dane. Idealne dla stron i aplikacji mobilnych.

OTP działa bezpiecznie tylko jako część kontrolowanego przepływu

  • OTP to kod jednorazowy, ale SMS, e-mail i aplikacja TOTP działają inaczej.
  • Backend powinien unieważnić kod po użyciu, pilnować czasu ważności i ograniczać błędne próby.
  • Ponowne wysłanie najlepiej tworzy nowy kod i unieważnia poprzedni.
  • Hash kodu nie wystarczy, jeśli atakujący może odgadywać go bez ograniczeń.
  • TOTP wymaga ochrony sekretu, z którego serwer i aplikacja generują kody.

Kod OTP w API może pochodzić z trzech różnych mechanizmów

Na ekranie każdy wygląda podobnie: krótki kod do przepisania. W backendzie rozróżnienie jest zasadnicze, bo od niego zależy, czy serwer przechowuje pojedynczy kod, czy sekret pozwalający odtwarzać kolejne kody.

Kod wysłany e-mailem lub SMS-em backend generuje dla konkretnego wyzwania i wysyła przez dostawcę wiadomości. TOTP tworzy aplikacja uwierzytelniająca na podstawie współdzielonego sekretu i czasu. HOTP opiera się na liczniku, który przesuwa się przy kolejnych użyciach.

Standard RFC 6238 opisuje TOTP jako wariant HOTP zależny od czasu i rekomenduje domyślny krok 30 sekund. To nie oznacza, że kod musi być akceptowany wyłącznie przez dokładnie 30 sekund: serwer może dopuścić ograniczone okno tolerancji, ale im szersze, tym dłużej przechwycony kod może pozostać użyteczny.

Praktyczny wybór: kod e-mail/SMS pasuje do weryfikacji adresu lub numeru i prostych scenariuszy logowania. TOTP jest lepszym wyborem dla dodatkowego składnika, gdy użytkownik skonfiguruje aplikację. Żaden z tych kodów nie jest odporny na phishing, więc przy kontach wymagających ochrony przed podszywaniem się trzeba rozważyć metody odporne na phishing, takie jak passkeys.

Jednorazowość wymaga atomowej weryfikacji po stronie serwera

Dwa równoległe żądania potrafią przejść przez prostą kontrolę „kod poprawny?”, zanim którekolwiek zapisze jego zużycie. W efekcie ten sam OTP może zostać zaakceptowany dwa razy, choć interfejs sugeruje jednorazowe użycie.

W przepływie e-mail lub SMS rekord wyzwania powinien łączyć kod z celem, na przykład konkretnym kontem i operacją. Po poprawnej weryfikacji backend powinien atomowo oznaczyć kod jako zużyty i dopiero wtedy wydać sesję albo zezwolić na zmianę hasła. Operacja atomowa sprawia, że równoległe żądania nie mogą oba skutecznie zużyć tego samego rekordu.

Przy ponownej wysyłce nowy kod powinien zastąpić poprzedni. Jeśli poprzedni nadal działa, kilka wiadomości z różnymi kodami tworzy niejasny stan, a użytkownik może przypadkiem potwierdzić starszy. OWASP Cheat Sheet dotyczący MFA zaleca krótki czas życia, pojedyncze użycie, limity prób oraz unieważnienie kodu po potwierdzeniu.

Uważam, że to właśnie atomowe zużycie odróżnia poprawną implementację od pozornie działającego formularza. Kod może zostać wpisany prawidłowo, a mimo to proces zawiedzie, jeśli równoległe żądania zmienią kolejność jego sprawdzenia i unieważnienia.

Limit prób musi obejmować całe konto, nie tylko jedną sesję

Krótki kod ma małą przestrzeń możliwych wartości, dlatego brak limitu prób zamienia formularz w punkt do zgadywania. Ograniczenie wyłącznie na pojedynczej sesji łatwo ominąć, uruchamiając kolejne sesje lub równoległe żądania.

RFC 4226 opisuje ograniczanie prób dla HOTP i podkreśla, że blokady lub opóźnienia muszą działać między sesjami, aby utrudnić równoległe zgadywanie. W praktyce API może łączyć licznik błędów dla konta z limitami dla adresu IP, urządzenia i wysyłki wiadomości. Sam limit IP bywa niewystarczający, a sam limit konta może ułatwić napastnikowi blokowanie dostępu prawowitej osobie.

Przy odpowiedzi API rozdziel błędny kod, kod wygasły i przekroczony limit tak, by nie ujawniać niepotrzebnie, czy dany adres e-mail jest zarejestrowany. Interfejs powinien natomiast jasno podpowiadać, czy można spróbować ponownie, czy trzeba rozpocząć nową weryfikację.

Przypadek Możliwa przyczyna Co zrobić
Kod działa na jednym ekranie, ale na drugim nie Równoległe żądania albo nieaktualny kod po ponownej wysyłce Unieważniaj poprzedni kod przy resend i zużywaj poprawny rekord atomowo
Kod TOTP stale jest odrzucany Rozjazd czasu między urządzeniem a serwerem lub zbyt wąskie okno tolerancji Sprawdź synchronizację czasu i konfigurację kroku; nie poszerzaj okna bez potrzeby
Wysyłka SMS gwałtownie rośnie Endpoint wysyłki można wywoływać bez skutecznego limitu Dodaj limity wysyłek oraz opóźnienie ponownego żądania, monitoruj koszty
Po poprawnym kodzie użytkownik ponownie może użyć tego samego Brak trwałego oznaczenia kodu jako zużytego albo wyścig żądań Połącz weryfikację i zużycie w operacji atomowej

Hash OTP ogranicza wyciek, ale nie zatrzyma zgadywania

Przechowywanie kodu w postaci jawnej w bazie i logach jest złym domyślnym wyborem. Sam hash też nie daje takiej ochrony jak przy długim haśle: dla sześciu cyfr istnieje zaledwie około miliona możliwych wartości, więc ujawniony hash można szybko przeszukać offline.

OWASP wskazuje, że haszowanie kodów nadal pomaga ograniczyć przypadkowe ujawnienie w bazie, logach czy narzędziach diagnostycznych, ale nie zapewnia silnej odporności na takie odgadywanie. Dlatego potrzebne są równocześnie krótki czas ważności, limit prób i brak kodów w logach.

Przy TOTP problem wygląda inaczej: serwer musi przechować sekret, aby sprawdzić kod generowany przez aplikację. Nie można go zastąpić hashem, bo backend potrzebuje oryginalnego sekretu do obliczeń. Sekret należy więc chronić jak poświadczenie, na przykład szyfrować i ograniczyć dostęp do klucza; kodu TOTP nie zapisuje się jako jednorazowego rekordu do ponownego użycia.

Wybór metody zależy od tego, co potwierdza kod

Wysyłanie kodu i weryfikacja drugiego składnika wyglądają podobnie w API, ale służą innym celom. Właściwa decyzja zaczyna się od pytania, czy użytkownik potwierdza kontrolę nad adresem lub numerem, czy ma dodatkowo zabezpieczyć logowanie.

  • Potwierdzenie adresu e-mail: wygeneruj losowy kod powiązany z adresem i celem, ustaw wygaśnięcie, unieważnij po użyciu.
  • Potwierdzenie numeru telefonu: zastosuj analogiczny przepływ, ale ogranicz częstotliwość wysyłki, aby endpoint nie stał się źródłem kosztów ani nadużyć.
  • Drugi składnik logowania: rozważ TOTP zamiast SMS, jeśli akceptujesz etap konfiguracji i bezpieczne przechowywanie sekretu.
  • Ochrona przed phishingiem: OTP nie wystarczy, jeśli kod można przechwycić i natychmiast przekazać fałszywej stronie; rozważ passkeys lub klucze bezpieczeństwa.

Jeśli kod zatwierdza zmianę adresu, reset hasła albo inną wrażliwą operację, przypisz go do tej konkretnej czynności i nie pozwalaj użyć go w innym przepływie. Taki prosty podział ogranicza ryzyko, że ważny kod z jednego ekranu stanie się przepustką do zupełnie innej akcji.

Dobry przepływ OTP nie kończy się na poprawnym kodzie

Wdrożenie jest kompletne dopiero wtedy, gdy obejmuje również awarie, ponowne wysłanie i odzyskiwanie dostępu. Jeśli użytkownik straci telefon z aplikacją TOTP, słaby mechanizm odzyskiwania może obejść całą ochronę, którą miało zapewnić logowanie kodem.

Przed publikacją API sprawdź, czy kody znikają z logów, czy resend unieważnia poprzedni kod, czy limit prób działa między sesjami oraz czy kilka równoczesnych weryfikacji nie zużyje tego samego OTP. Jeśli wdrażasz jednorazowy kod z wiadomości, potraktuj go jako krótkotrwałe wyzwanie powiązane z jedną operacją; jeśli wdrażasz TOTP, zacznij od ochrony sekretu i obsługi rozjazdu czasu.

FAQ - Najczęstsze pytania

Kod SMS lub e-mail generuje backend dla konkretnego wyzwania i operacji, a następnie wysyła go przez dostawcę wiadomości. TOTP powstaje w aplikacji na podstawie współdzielonego sekretu i czasu, zwykle w kroku 30 sekund, natomiast HOTP wykorzystuje licznik. TOTP wymaga więc bezpiecznego przechowywania sekretu po stronie serwera.

Weryfikację kodu i oznaczenie rekordu jako zużytego należy wykonać atomowo. Dzięki temu równoległe żądania nie zaakceptują tego samego kodu przed zapisaniem jego zużycia. Przy ponownym wysłaniu nowy kod powinien zastąpić poprzedni i unieważnić jego ważność.

Dla sześciu cyfr istnieje około miliona możliwych wartości, dlatego ujawniony hash można szybko przeszukać offline. Hash ogranicza skutki przypadkowego wycieku z bazy lub logów, ale nie zatrzymuje zgadywania kodu. Potrzebne są również krótki czas ważności, limit prób i zakaz zapisywania kodów w logach.

Najpierw sprawdź synchronizację czasu między urządzeniem a serwerem oraz konfigurację kroku generowania kodu. Backend może dopuścić ograniczone okno tolerancji, ale nie należy poszerzać go bez potrzeby, ponieważ przechwycony kod będzie wtedy dłużej użyteczny.
Oceń artykuł

Średnia: 0.0 / 5 · 0 ocen

Tagi

otp totp hotp mfa passkeys

Udostępnij artykuł

Komentarze (0)
Dodaj komentarz