Jak dodać uwierzytelnianie dwuskładnikowe (2FA) do aplikacji

Aby dodać uwierzytelnianie dwuskładnikowe (2FA) do aplikacji, pozwól użytkownikom połączyć aplikację uwierzytelniającą przez zeskanowanie kodu QR, poproś o sześciocyfrowy kod, który ona pokazuje, po haśle, i dopiero gdy ten kod się zgadza, utwórz pełną sesję po stronie serwera. Każdemu użytkownikowi przy włączaniu daj jednorazowe kody zapasowe, ogranicz liczbę prób zgadnięcia kodu i wymagaj hasła oraz aktualnego kodu, zanim będzie można wyłączyć 2FA. Jeśli korzystasz z hostowanego dostawcy uwierzytelniania, włącz jego wbudowaną opcję wieloskładnikową zamiast budować własną.

Ten poradnik przechodzi przez wybory, dokładny przebieg, prompty dla asystenta do budowania i błędy, przez które 2FA wygląda na obecne, ale nic nie robi. Jeśli to nowe pojęcie, zacznij od czym jest uwierzytelnianie dwuskładnikowe.

Zanim zaczniesz: potrzebne działające logowanie

2FA działa na bazie istniejącego logowania. Najpierw potrzebujesz jednego z poniższych:

• Własnego logowania z użytkownikami i zahaszowanymi hasłami w bazie danych aplikacji.
• Hostowanego dostawcy uwierzytelniania, który zarządza użytkownikami za Ciebie.

Jeśli jeszcze nie masz żadnego, zacznij od jak dodać logowanie do aplikacji. Dalsza część zakłada, że krok z hasłem już działa.

Wybierz drugi składnik

TOTP to skrót od time-based one-time password, czyli standard (RFC 6238), z którego korzystają aplikacje uwierzytelniające. Serwer i telefon użytkownika dzielą sekret; każde z nich generuje ten sam krótki kod na podstawie sekretu i bieżącego czasu, zwykle zmieniający się co 30 sekund. Nie potrzeba połączenia z siecią ani dostawcy SMS.

Klucze dostępu zastępują lub uzupełniają hasła kluczem kryptograficznym przechowywanym na urządzeniu użytkownika. Są silniejsze, ale trudniejsze do zbudowania samodzielnie, więc wiele aplikacji zaczyna od TOTP, a klucze dodaje później lub pobiera od dostawcy uwierzytelniania.

Zbudować samemu czy włączyć?

Sprawdź aktualną dokumentację dostawcy, które składniki obsługuje i w których planach. W obu przypadkach nigdy nie pisz sam matematyki generowania kodów; użyj powszechnie stosowanej biblioteki.

Najpierw ustal politykę

Odpowiedz na te pytania przed promptem, bo zmieniają projekt:

1. Kto musi z tego korzystać? Opcjonalnie dla wszystkich, wymagane dla administratorów i personelu, albo wymagane dla wszystkich. Wymaganie tego od każdego z uprawnieniami administratora jest częste. Zobacz kontrolę dostępu opartą na rolach.
2. Jak często użytkownicy wpisują kod? Przy każdym logowaniu albo raz na urządzenie na 30 dni („zapamiętaj to urządzenie”).
3. Które działania wymagają świeżej weryfikacji? Dobrymi kandydatami są zmiana adresu e-mail, danych do wypłat i wyłączenie 2FA. Nazywa się to step-up authentication.
4. Jak wygląda procedura przy zgubionym telefonie? Kody zapasowe oraz ręczna ścieżka awaryjna, którą jesteś gotów prowadzić.

Krok po kroku: 2FA z kodami TOTP we własnym logowaniu

1. Zapisz właściwe pola

Każdy użytkownik potrzebuje: informacji, czy 2FA jest włączone, sekretu TOTP (szyfrowanego w spoczynku, nie jako zwykły tekst), czasu włączenia oraz listy kodów zapasowych zapisanych jako hasze, tak jak hasła. Dodaj miejsce na liczenie nieudanych prób.

2. Rejestracja

1. Użytkownik otwiera Ustawienia i klika Włącz uwierzytelnianie dwuskładnikowe.
2. Serwer generuje nowy sekret i zwraca go jako kod QR oraz wersję tekstową dla osób, które nie mogą zeskanować.
3. Użytkownik skanuje kod w aplikacji uwierzytelniającej i wpisuje aktualny kod.
4. Serwer sprawdza kod. Dopiero jeśli jest poprawny, zapisuje sekret i oznacza 2FA jako włączone.
5. Aplikacja pokazuje 8–10 kodów zapasowych jednorazowo i prosi użytkownika o ich zapisanie.

Krok 4 ma znaczenie: włączenie 2FA przed potwierdzeniem kodu blokuje każdego, którego skanowanie się nie udało.

3. Logowanie z drugim krokiem

1. Użytkownik wysyła e-mail i hasło. Serwer je sprawdza.
2. Jeśli 2FA jest włączone, serwer nie tworzy pełnej sesji. Zamiast tego tworzy krótkotrwały stan „drugi składnik oczekuje”.
3. Aplikacja pokazuje ekran kodu. Serwer sprawdza kod, dopuszczając niewielkie okno na rozjechanie zegarów.
4. Dopiero teraz serwer wydaje właściwą sesję.

Każda chroniona trasa i endpoint API muszą odrzucać stan oczekiwania. Ekran 2FA, który tylko ukrywa strony w przeglądarce, można ominąć, wywołując API bezpośrednio.

4. Limity i alerty

Sześciocyfrowy kod ma milion kombinacji, więc bez limitów da się go odgadnąć. Ogranicz liczbę prób, zablokuj drugi krok na pewien czas po wielokrotnych błędach i wyślij użytkownikowi e-mail, gdy to się zdarzy. Zobacz czym jest limit żądań (rate limiting) oraz wysyłanie e-maili z aplikacji.

5. Odzyskiwanie i wyłączanie

• Kod zapasowy działa jeden raz, a potem jest usuwany.
• Wyłączenie 2FA wymaga hasła i aktualnego kodu lub kodu zapasowego.
• Ponowne wygenerowanie kodów zapasowych unieważnia poprzedni zestaw.
• Wyślij e-mail użytkownikowi za każdym razem, gdy 2FA zostanie włączone lub wyłączone.

Prompty dla asystenta do budowania

Zacznij od podstawowego przebiegu:

Dodaj opcjonalne uwierzytelnianie dwuskładnikowe z aplikacjami uwierzytelniającymi (TOTP) do naszego istniejącego logowania e-mail i hasło. Użyj znanej biblioteki TOTP, nie pisz algorytmu samodzielnie. W Ustawieniach pokaż kod QR i tekstowy sekret, a 2FA włączaj dopiero po wpisaniu przez użytkownika poprawnego kodu. Przechowuj sekret zaszyfrowany i nigdy nie pokazuj go ponownie po konfiguracji. Pokaż 10 jednorazowych kodów zapasowych raz i zapisz je zahaszowane.

Potem egzekwowanie, gdzie wygenerowany kod najczęściej zawodzi:

Egzekwuj 2FA po stronie serwera. Po poprawnym haśle użytkownicy z włączonym 2FA dostają krótkotrwały stan oczekiwania, a nie pełną sesję. Każda chroniona strona i trasa API musi odrzucać stan oczekiwania. Ogranicz próby kodu do 5, potem zablokuj drugi krok na 15 minut i wyślij użytkownikowi e-mail.

Następnie polityka:

Wymagaj 2FA dla kont administratorów: administrator bez 2FA jest kierowany do konfiguracji i nie może wejść do panelu, dopóki jej nie ukończy. Wymagaj hasła i aktualnego kodu, aby wyłączyć 2FA lub zmienić e-mail konta. Wysyłaj użytkownikowi e-mail, gdy 2FA zostanie włączone lub wyłączone.

Na koniec poproś agenta o wyjaśnienie tego, co zbudował:

Wypisz każdą trasę, która sprawdza ukończenie drugiego składnika, gdzie są przechowywane sekret TOTP i kody zapasowe oraz jak są chronione.

Częste błędy

• Sesja wydana po haśle. Najpoważniejszy błąd. Jeśli pełna sesja istnieje przed sprawdzeniem kodu, 2FA jest tylko dekoracją. Sprawdź, wywołując chronione API po samym kroku z hasłem.
• Brak limitu prób. Nieograniczona liczba zgadywań sprawia, że kod da się złamać siłowo.
• Sekrety lub kody zapasowe jako zwykły tekst. Wyciek bazy oddaje wtedy drugi składnik wszystkich.
• Włączanie przed weryfikacją. Użytkownicy, którzy źle zeskanowali kod, zostają zablokowani przy następnym logowaniu.
• Brak ścieżki odzyskiwania. Każdy zgubiony telefon staje się zgłoszeniem do wsparcia albo utraconym klientem.
• Łatwe wyłączenie. Jeśli skradziona sesja może wyłączyć 2FA bez kodu, ochrona przestaje działać.
• Kody w logach. Upewnij się, że kody i sekrety nigdy nie pojawiają się w logach serwera ani w komunikatach błędów.
• Sprawdzanie tylko na stronie logowania. Reset hasła, logowanie linkiem magicznym i każde logowanie społecznościowe także muszą respektować 2FA, inaczej staną się obejściem.

Lista kontroli testów

• Rejestracja kończy się dopiero po poprawnym kodzie
• Logowanie z poprawnym hasłem, ale bez kodu nie daje dostępu do żadnej chronionej strony ani API
• Błędny kod jest odrzucany; wielokrotne błędy uruchamiają blokadę i e-mail
• Kod sprzed kilku minut jest odrzucany
• Każdy kod zapasowy działa dokładnie raz
• Wyłączenie 2FA wymaga hasła i aktualnego kodu
• Reset hasła nie omija 2FA
• Administratorzy bez 2FA nie mogą wejść na strony administracyjne (jeśli jest to wymagane)
• Sekrety i kody zapasowe są zaszyfrowane lub zahaszowane w bazie danych
• Żadne kody ani sekrety nie pojawiają się w logach

Przed startem przejdź też pełną listę kontrolną bezpieczeństwa dla aplikacji zbudowanych z AI.

Dodawanie 2FA w Mythex

Mythex nie zawiera wbudowanego systemu logowania dla końcowych użytkowników Twojej aplikacji, więc 2FA jest częścią tego podejścia do uwierzytelniania, które wybierzesz: własnego logowania e-mail i hasło z bazą danych projektu albo hostowanego dostawcy z obsługą wieloskładnikowości. Opisujesz, czego chcesz, w czacie, używając promptów jak powyższe, a klucze dostawcy trafiają do sekretów projektu (przez /secrets, ustawienia projektu lub kartę sekretów, którą pokazuje agent), a nie do pola wiadomości. Przepis w dokumentacji Dodaj logowanie do aplikacji zawiera gotowy prompt startowy, a Bezpieczeństwo aplikacji, które budujesz opisuje nawyki dotyczące kluczy i uprawnień. Gdy agent skończy, przetestuj każdą pozycję z listy kontrolnej w podglądzie, zanim opublikujesz.

Pytania