Dvoufaktorova autentizace

Dvoufaktorova autentizace (2FA) pridava dalsi vrstvu zabezpeceni, ktera vyzaduje, aby uzivatele overili svou identitu dodatecnym kodem.

Podporovane metody

Metoda	Popis	Doporuceni
Autentikacni aplikace	TOTP kod z Google/Microsoft Authenticator	Doporuceno - nejbezpecnejsi
E-mail	6mistny kod zaslany e-mailem	Zaloha pro uzivatele bez smartphonu

Doporucena metoda

Autentikacni aplikace (Google Authenticator, Microsoft Authenticator, Authy) je nejbezpecnejsi a nejpohodlnejsi metoda:

Funguje offline
Kody se generuji lokalne
Zadne cekani na SMS/e-mail
Zdarma (na rozdil od SMS)

Jak funguje autentikacni aplikace (TOTP)

TOTP (Time-based One-Time Password) generuje 6mistne kody, ktere se meni kazdych 30 sekund:

Uzivatel si aktivuje 2FA naskenovanim QR kodu
Aplikace (Google/Microsoft Authenticator) vygeneruje tajny klic
Pri prihlaseni uzivatel zada aktualni 6mistny kod z aplikace
Server overi kod podle sdileneho tajneho klice

Vyhody oproti SMS/E-mailu:

Funguje bez internetoveho pripojeni
Okamzita dostupnost kodu
Zadne naklady na odesilani
Vyssí bezpecnost (bez rizika SIM swap utoku)

2FA v Authorization Code Flow (doporuceno)

Pri pouziti Authorization Code Flow (doporuceny zpusob integrace) je 2FA automaticky soucasti prihlasovacího procesu. Vase aplikace se o 2FA nemusi starat:

Uzivatel je presmerovan na prihlasovaci stranku SSO
Zada e-mail a heslo
Pokud ma povolene 2FA:
- Autentikator: Zada kod z aplikace (bez cekani)
- E-mail: Obdrzi kod na e-mail a zada ho
Po uspesnem overeni pokracuje zpet do vasi aplikace

Neni potreba zadna specialni implementace - vse probiha na strane SSO.

2FA v Resource Owner Password Grant (legacy)

Nedoporucovana metoda

Resource Owner Password Grant je zastaraly a nedoporucovany zpusob autentizace. OAuth 2.0 Security Best Current Practice tento flow explicitne nedoporucuje z bezpecnostnich duvodu.

Pouzivejte pouze pro:

Migrace ze starsich systemu
Legacy aplikace, ktere nelze upgradovat

Pro nove integrace vzdy pouzijte Authorization Code Flow (nebo s PKCE pro SPA/mobilni aplikace).

Pri pouziti Resource Owner Password Grant musi vase aplikace 2FA resit manualne, protoze neexistuje UI pro presmerovani uzivatele.

2FA flow pro Password Grant

Kdyz je 2FA povoleno a uzivatel se pokusi prihlasit:

┌──────────┐         ┌──────────┐         ┌──────────┐
│ Uzivatel │         │ Vase App │         │ Klubero  │
│          │         │          │         │   SSO    │
└────┬─────┘         └────┬─────┘         └────┬─────┘
     │                    │                    │
     │ 1. Prihlaseni      │                    │
     │    email/heslo     │                    │
     │ ──────────────────►│                    │
     │                    │                    │
     │                    │ 2. POST /token     │
     │                    │ ──────────────────►│
     │                    │                    │
     │                    │ 3. Chyba:          │
     │                    │    mfa_required    │
     │                    │ ◄──────────────────│
     │                    │                    │
     │ 4. Zobrazi 2FA     │                    │
     │    vstup           │                    │
     │ ◄──────────────────│                    │
     │                    │                    │

Pro Autentikator: Uzivatel primo zada kod z aplikace.

Pro E-mail: Aplikace musi nejprve pozadat o odeslani kodu.

Detekce pozadavku 2FA

Pri pouziti Resource Owner Password flow a povolenem 2FA:

Token pozadavek:

curl -X POST https://your-sso-domain.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=my-app" \
  -d "client_secret=my-secret" \
  -d "username=user@example.com" \
  -d "password=userpassword" \
  -d "scope=openid profile"

Odpoved vyzadujici 2FA:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "mfa_required",
  "error_description": "Two-factor authentication required.",
  "mfa_method": "Authenticator"
}

Pole mfa_method urcuje, jakou metodu uzivatel pouziva:

Authenticator - uzivatel pouziva autentikacni aplikaci
Email - uzivatel pouziva e-mailove overeni

Overeni kodu z autentikatoru

Pro uzivatele s metodou Authenticator neni potreba odesilat zadny kod - uzivatel ho vidi primo v aplikaci.

Endpoint: POST /api/twofactor/verify

curl -X POST https://your-sso-domain.com/api/twofactor/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "123456",
    "purpose": "Login"
  }'

Overeni pres e-mail (odeslani kodu)

Pro uzivatele s metodou Email je nutne nejprve pozadat o odeslani kodu.

Krok 1: Odeslani overovacího kodu

Endpoint: POST /api/twofactor/send-code-login

curl -X POST https://your-sso-domain.com/api/twofactor/send-code-login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "purpose": "Login"
  }'

Odpoved:

{
  "success": true,
  "method": "Email",
  "expiresAt": "2024-01-01T12:10:00Z"
}

Krok 2: Overeni kodu

Endpoint: POST /api/twofactor/verify

curl -X POST https://your-sso-domain.com/api/twofactor/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "123456",
    "purpose": "Login"
  }'

Uspesna odpoved:

{
  "success": true,
  "message": "Verification successful."
}

Po uspesnem overeni opakujte puvodni autentizacni pozadavek.

Zalozni kody

Uzivatele obdrzi 3 zalozni kody pri povoleni 2FA. Tyto kody jsou jednorazove a slouzi pro pripady, kdy primarni metoda neni dostupna (napr. ztrata telefonu).

Overeni zalozniho kodu:

curl -X POST https://your-sso-domain.com/api/twofactor/verify-recovery \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "recoveryCode": "ABC12345"
  }'

Dulezite

Kazdy zalozni kod lze pouzit pouze jednou. Po pouziti je automaticky zneplatnen.

Vlastnosti overovaciho kodu

Autentikator (TOTP)

Vlastnost	Hodnota
Format	6 cislic
Zivotnost	30 sekund
Tolerance	±30 sekund (pro synchronizacni rozdily)
Algoritmus	HMAC-SHA1 (RFC 6238)

E-mail

Vlastnost	Hodnota
Format	6 cislic (000000-999999)
Zivotnost	10 minut
Max pokusu	5 neuspesnych pokusu pred zneplatnenim
Doruceni	E-mail

Chybove kody 2FA

Chyba	Popis	Akce
`mfa_required`	Vyzadovano 2FA overeni	Zobrazit vstup pro kod
`invalid_code`	Kod neodpovida	Zkuste znovu (omezeny pocet pokusu)
`code_expired`	Kod vypršel	Pozadejte o novy kod (jen e-mail)
`too_many_attempts`	Prekrocen max. pocet pokusu	Pozadejte o novy kod
`mfa_not_enabled`	Uzivatel nema povolene 2FA	Pokracujte bez 2FA

Kompatibilni aplikace

Autentikacni metoda TOTP je kompatibilni se vsemi standardnimi autentikatory:

Google Authenticator (Android, iOS)
Microsoft Authenticator (Android, iOS)
Authy (Android, iOS, Desktop)
1Password (integrováno)
Bitwarden (integrováno)
Jakakoli aplikace podporujici RFC 6238 TOTP

Podporovane metody​

Jak funguje autentikacni aplikace (TOTP)​

2FA v Authorization Code Flow (doporuceno)​

2FA v Resource Owner Password Grant (legacy)​

2FA flow pro Password Grant​

Detekce pozadavku 2FA​

Overeni kodu z autentikatoru​

Overeni pres e-mail (odeslani kodu)​

Krok 1: Odeslani overovacího kodu​

Krok 2: Overeni kodu​

Zalozni kody​

Vlastnosti overovaciho kodu​

Autentikator (TOTP)​

E-mail​

Chybove kody 2FA​

Kompatibilni aplikace​