Uwierzytelnianie dwuetapowe i wieloskładnikowe (2FA/MFA)

FoxIDs obsługuje zarówno prosty tryb dwuetapowy, jak i zaawansowany tryb wieloskładnikowy w metodzie uwierzytelniania logowania.

• Tryb dwuetapowy: Advanced multi-factor jest wyłączone (domyślnie).
• Tryb wieloskładnikowy: Advanced multi-factor jest włączone.

Używaj trybu dwuetapowego, gdy wystarcza jeden dodatkowy czynnik. Używaj trybu wieloskładnikowego, gdy potrzebujesz uporządkowanego łańcucha MFA albo chcesz używać metod uwierzytelniania jako kroków MFA.

Pojęcia

Uwierzytelnianie dwuetapowe (2FA) i wieloskładnikowe (MFA) dodają jeden lub więcej kroków weryfikacji po podstawowym logowaniu.

• 2FA: logowanie podstawowe plus jeden dodatkowy czynnik.
• MFA: logowanie podstawowe plus jeden lub więcej uporządkowanych dodatkowych czynników.

Obsługiwane czynniki

FoxIDs obsługuje wbudowane czynniki oraz metody uwierzytelniania jako elementy MFA.

Czynnik	Typ	Wartość AMR
Kod SMS	Wbudowany	sms
Kod e-mail	Wbudowany	email
Kod authenticator app	Wbudowany	otp
Recovery code	Wbudowany (authenticator app)	otp
Metoda uwierzytelniania (OIDC, SAML 2.0, TrackLink)	Element konfigurowalny	Skonfigurowane AMR albo nazwa metody/profilu, jeśli pole jest puste

Możesz używać dowolnej kompatybilnej authenticator app, na przykład Google Authenticator, Microsoft Authenticator, Authy i innych aplikacji TOTP.

Kiedy MFA jest wymagane

MFA jest wyzwalane, gdy zachodzi jeden z poniższych warunków:

• Użytkownik ma włączone Require multi-factor (2FA/MFA).
• Metoda uwierzytelniania logowania ma włączone Require multi-factor (2FA/MFA).
• Aplikacja wywołująca żąda MFA z ACR urn:foxids:mfa.

Wymagania MFA obowiązują w obu trybach. Jeśli Advanced multi-factor jest wyłączone, wymaganie spełnia prosty flow dwuetapowy.

Jeśli wraz z urn:foxids:mfa są żądane określone wartości ACR, wymagane są tylko pasujące wartości ACR.

Tryb dwuetapowy (Advanced multi-factor jest wyłączone)

W tym trybie wbudowane opcje dwuetapowe są konfigurowane bezpośrednio:

• Authenticator app
• SMS
• E-mail

Aby skonfigurować tryb dwuetapowy:

1. Otwórz kartę Authentication.
2. Kliknij metodę uwierzytelniania logowania Login, aby ją edytować.
3. Kliknij Show advanced.
4. Przejdź do sekcji Multi-factor.
5. Pozostaw Advanced multi-factor wyłączone i skonfiguruj opcje Authenticator app, SMS i E-mail.

Nazwa authenticator app wyświetlana użytkownikom może zostać skonfigurowana. Domyślnie używana jest nazwa tenanta.

Czynniki SMS i e-mail wymagają danych kontaktowych użytkownika. Mogą one zostać podane jako identyfikatory użytkownika lub claims (phone_number i email).

Zachowanie wyboru typu dwuetapowego

W trybie dwuetapowym FoxIDs preferuje już zarejestrowaną authenticator app. Jeśli żadna authenticator app nie jest zarejestrowana, SMS ma pierwszeństwo przed e-mailem, gdy oba są dostępne.

SMS dwuetapowy włączony i użytkownik ma numer telefonu	E-mail dwuetapowy włączony i użytkownik ma e-mail	Użytkownik ma zarejestrowaną authenticator app	Możliwe typy dwuetapowe	Wybrany typ dwuetapowy
false	false	false	Konfiguracja authenticator app	Konfiguracja authenticator app
false	false	true	Authenticator app	Authenticator app
true	false	false	SMS z opcjonalną konfiguracją authenticator app po weryfikacji SMS	SMS
true	false	true	SMS i authenticator app	Authenticator app
false	true	false	E-mail z opcjonalną konfiguracją authenticator app po weryfikacji e-mail	E-mail
false	true	true	E-mail i authenticator app	Authenticator app
true	true	false	SMS i e-mail z opcjonalną konfiguracją authenticator app po weryfikacji SMS lub e-mail	SMS
true	true	true	SMS, e-mail i authenticator app	Authenticator app

Powiadamianie API o rejestracji aplikacji uwierzytelniającej

Metoda uwierzytelniania logowania może natychmiast powiadomić backend po zarejestrowaniu przez użytkownika nowej aplikacji uwierzytelniającej. Powiadomienie jest opcjonalne i dotyczy tylko nowych rejestracji, a nie późniejszych logowań za pomocą aplikacji.

Aby skonfigurować powiadomienie:

1. Otwórz kartę Authentication.
2. Kliknij metodę uwierzytelniania Login, aby ją edytować.
3. Kliknij Show advanced.
4. Przejdź do sekcji Multi-factor.
5. W trybie dwuskładnikowym włącz Notify an API when an authenticator app is registered poniżej wbudowanych opcji składników. W zaawansowanym trybie wieloskładnikowym włącz tę opcję w elemencie MFA Authenticator app.
6. Skonfiguruj bazowy adres URL API i sekret API.

FoxIDs zapisuje rejestrację aplikacji uwierzytelniającej lokalnie przed wywołaniem API i zapisuje ślad Authenticator app registration saved locally; external notification pending. Następnie API jest wywoływane synchronicznie. Logowanie jest kontynuowane tylko wtedy, gdy API zwróci status HTTP 200 OK. Jeśli wywołanie się nie powiedzie lub zwróci inny status, FoxIDs usuwa nową rejestrację i wyświetla stronę błędu. Istniejące rejestracje nie są zmieniane.

Pomyślna rejestracja jest zapisywana w dzienniku audytu po zwróceniu przez API 200 OK. Jeśli powiadomienie jest wyłączone, wpis audytu jest zapisywany natychmiast po lokalnym zapisaniu rejestracji.

Request do API powiadomień

Jeśli skonfigurowany bazowy adres URL to https://backend.example/authenticator, FoxIDs wysyła request HTTP POST do:

https://backend.example/authenticator/notification

FoxIDs Cloud wywołuje Twoje API z adresu IP 57.128.60.142.

Adres(y) IP mogą ulec zmianie lub zostać rozszerzone.

Request używa HTTP Basic authentication:

• Nazwa użytkownika: authenticator_app
• Hasło: skonfigurowany sekret API

Request JSON zawiera:

{
  "type": "registered",
  "registration_id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "user_id": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "email": "user@example.com",
  "phone": "+4512345678",
  "username": "user@example.com"
}

type identyfikuje powiadomienie. Obsługiwany typ registered oznacza, że zarejestrowano nową aplikację uwierzytelniającą. registration_id to trwały unikalny identyfikator nowej rejestracji. API może użyć go jako klucza idempotencji. user_id to stabilny techniczny identyfikator użytkownika FoxIDs. email, phone i username są dołączane, gdy mają wartość. Sekret aplikacji uwierzytelniającej i kod odzyskiwania nigdy nie są wysyłane.

API powinno zaakceptować powiadomienie i zwrócić 200 OK, gdy tylko wymagane prace synchroniczne zostaną zakończone. Dalsza obsługa kolejki lub dystrybucja do innych deployments należy do backendu.

Zarządzanie rejestracjami aplikacji uwierzytelniających

Administratorzy mogą wyświetlać i pojedynczo usuwać rejestracje aplikacji uwierzytelniających użytkownika w Internal Users → edycja użytkownika → Advanced → Two-factor. Rejestracje są identyfikowane przez trwałe ID oraz, w przypadku nowych rejestracji, czas rejestracji. Podczas rejestracji użytkownik nie podaje nazwy wyświetlanej.

Aby listować, odczytywać, tworzyć, aktualizować, usuwać lub synchronizować rejestracje przez Control API, zobacz Control API - użytkownicy i aplikacje uwierzytelniające. Przewodnik dokumentuje endpointy, zasób request, bezpieczeństwo, odpowiedzi błędów i zachowanie notification w jednym miejscu.

Tryb wieloskładnikowy (Advanced multi-factor jest włączone)

Gdy Advanced multi-factor jest włączone, MFA jest konfigurowane jako uporządkowana lista maksymalnie 5 elementów MFA.

Można skonfigurować tylko jeden element MFA Authenticator app. Użytkownik może mieć do pięciu rejestracji aplikacji uwierzytelniających dla tego elementu. Wszystkie rejestracje są alternatywami do ukończenia tego samego elementu MFA: FoxIDs sprawdza przesłany kod względem zarejestrowanych aplikacji i akceptuje pierwsze dopasowanie. Monit rejestracji podczas logowania tworzy rejestrację tylko wtedy, gdy użytkownik nie ma żadnej; nie dodaje kolejnej, gdy rejestracja już istnieje. Nazwa aplikacji uwierzytelniającej i opcjonalne API powiadomień o rejestracji są konfigurowane w elemencie MFA Authenticator app.

Aby skonfigurować tryb wieloskładnikowy:

1. Otwórz kartę Authentication.
2. Kliknij metodę uwierzytelniania logowania Login, aby ją edytować.
3. Kliknij Show advanced.
4. Przejdź do sekcji Multi-factor.
5. Włącz Advanced multi-factor i skonfiguruj uporządkowane elementy MFA.

Obsługiwane typy elementów MFA:

• Wbudowane:
  • SMS
  • E-mail
  • Authenticator app
• Metoda uwierzytelniania:
  • OpenID Connect
  • SAML 2.0
  • TrackLink

Zasady konfiguracji:

• Wbudowane typy elementów można skonfigurować tylko raz każdy.
• Elementy typu metoda uwierzytelniania można skonfigurować wiele razy, na przykład z różnymi profilami.
• Elementy są wykonywane w kolejności listy.
• Możesz dodawać, usuwać i zmieniać kolejność elementów.

Zachowanie AMR i ACR elementów MFA

Każdy ukończony element MFA wnosi wartości claims AMR do sesji.

• Wbudowane wartości AMR są stałe:
  • SMS: sms
  • E-mail: email
  • Authenticator app i recovery code: otp
• Element MFA typu metoda uwierzytelniania:
  • Można skonfigurować opcjonalne niestandardowe AMR.
  • Jeśli AMR jest puste, używana jest nazwa metody uwierzytelniania albo profilu.

Żądane wartości ACR są dopasowywane do wartości AMR elementów MFA w następującym formacie:

• urn:foxids:<amr>
• Przykład: urn:foxids:link

urn:foxids:mfa to ogólny wymóg MFA, a FoxIDs dodaje AMR mfa, gdy MFA zostanie ukończone.

Wybór i łańcuchowanie elementów MFA

• Jeśli żądane są określone wartości ACR, jeden z pasujących elementów MFA musi zostać ukończony.
• Jeśli żądane jest tylko ogólne MFA, wymaganie może spełnić dowolny dostępny skonfigurowany element MFA.
• Jeśli istnieje więcej niż jeden kwalifikujący się element MFA i FoxIDs nie może wybrać go automatycznie, wyświetlany jest interfejs wyboru.
• Jeśli authenticator app jest skonfigurowana i już zarejestrowana, FoxIDs preferuje ją przy ogólnych żądaniach MFA.
• Jeśli wybrana zostanie konfiguracja authenticator app, a aplikacja nie jest jeszcze zarejestrowana, flow konfiguracji może być kontynuowane po wybranym kroku SMS, e-mail lub metodzie uwierzytelniania.
• Jeśli skonfigurowana jest tylko authenticator app, konfiguracja może rozpocząć się od razu po logowaniu pierwszym czynnikiem.

Strona MFA dla metody uwierzytelniania z opcjonalną rejestracją authenticator app i możliwością wyboru innego elementu MFA.

Strona MFA SMS z opcjonalną rejestracją authenticator app i możliwością wyboru innego elementu MFA.

Strona MFA e-mail, na której konfigurujesz authenticator app, z możliwością wyboru innego elementu MFA.

Strona MFA dla authenticator app z możliwością wyboru innego elementu MFA.

Metody uwierzytelniania używane jako elementy MFA

Metody uwierzytelniania (OIDC, SAML 2.0, TrackLink) mogą być używane jako elementy MFA zgodnie z następującymi zasadami:

• Wartości ACR specyficzne dla MFA nie są przekazywane do żądania metody uwierzytelniania MFA.
• Odpowiedź metody uwierzytelniania musi zawierać wymaganą wartość AMR dla wybranego elementu MFA.
• Wartość AMR jest zwykle dodawana w claim transform, jeśli zwrócona tożsamość odpowiada oczekiwanej tożsamości. Zobacz przykład claim transform.
• Jeśli wymagana wartość AMR nie zostanie zwrócona, logowanie kończy się niepowodzeniem.
• Po pomyślnej walidacji FoxIDs dodaje AMR mfa do wynikowej sesji.

Żądanie MFA z aplikacji

Aplikacje mogą żądać MFA zarówno w OpenID Connect, jak i w SAML 2.0.

Jeśli żądane są określone wartości ACR, ale nie są skonfigurowane na elementach MFA w wybranej metodzie uwierzytelniania logowania, uwierzytelnianie zakończy się niepowodzeniem.

OpenID Connect

Użyj acr_values:

• Ogólne MFA: acr_values=urn:foxids:mfa
• Ogólne MFA i określona metoda: acr_values=urn:foxids:mfa urn:foxids:link

SAML 2.0

Użyj RequestedAuthnContext.AuthnContextClassRef:

• Ogólne MFA: dołącz urn:foxids:mfa
• Ogólne MFA i określona metoda: dołącz urn:foxids:mfa oraz określone wartości, takie jak urn:foxids:link

Zachowanie sesji

FoxIDs waliduje wymagane wartości AMR względem bieżącej sesji logowania.

• Nowe logowanie: sesja jest tworzona po spełnieniu wszystkich wymagań.
• Step-up login: istniejąca sesja jest aktualizowana po spełnieniu wszystkich dodatkowych wymagań MFA.
• Ponowne użycie sesji: jeśli sesja już spełnia wymagane wartości AMR, FoxIDs używa jej ponownie i nie prosi użytkownika o ponowne logowanie.

Rozwiązywanie problemów

Typowe przyczyny błędów MFA:

• Żądane wartości ACR nie są skonfigurowane jako elementy MFA w metodzie uwierzytelniania logowania.
• Metoda uwierzytelniania używana jako MFA nie zwraca wymaganej wartości AMR.
• Obecnie nie ma żadnego skonfigurowanego elementu MFA dostępnego dla użytkownika, na przykład dlatego, że brakuje danych telefonu lub e-mail dla SMS albo e-mail.

Powiązana dokumentacja

• Wchodzenie do gry i wykrywanie serwera macierzystego
• Użytkownicy wewnętrzni
• Metody uwierzytelniania
• Przekształcenia roszczeń i zadania związane z roszczeniami
• Rozszerzony interfejs użytkownika