Dvoufaktorová autentizace

Dvoufaktorová autentizace (2FA) přidává další vrstvu zabezpečení, která vyžaduje, aby uživatelé ověřili svou identitu dodatečným kódem.

Nejdůležitější informace

Při standardní integraci přes Authorization Code Flow (+ PKCE) vaše aplikace 2FA neimplementuje vůbec. Celý proces dvoufaktorového ověření řeší Klubero SSO na své hostované přihlašovací stránce.

2FA v Authorization Code Flow

Při použití Authorization Code Flow (doporučený a jediný podporovaný způsob integrace pro aplikace třetích stran) je 2FA automaticky součástí přihlašovacího procesu na straně SSO. Vaše aplikace se o 2FA nemusí starat:

1. Uživatel je přesměrován na přihlašovací stránku Klubero SSO
2. Zadá e-mail a heslo (nebo použije externího poskytovatele / magic link)
3. Pokud má povolené 2FA, dokončí ověření přímo na obrazovce SSO:
   • Autentikátor: zadá aktuální kód z aplikace
   • E-mail: obdrží kód e-mailem a zadá ho
   • případně použije záložní kód
4. Teprve po úspěšném dokončení 2FA je vaší aplikaci předán autorizační kód (code) na registrované redirect_uri

Vaše aplikace tedy obdrží autorizační kód až po dokončení celého přihlášení včetně 2FA. Není potřeba žádná speciální implementace, žádné dodatečné endpointy ani zpracování stavů typu "vyžadováno 2FA" — vše probíhá na straně Klubero SSO.

info

Protože 2FA probíhá kompletně na hostované přihlašovací stránce SSO, výsledek je pro vaši aplikaci vždy stejný jako u běžného přihlášení: buď dostanete autorizační kód (přihlášení proběhlo úspěšně), nebo je uživatel přesměrován zpět s chybou OAuth. Podrobnosti k chybám najdete v řešení problémů.

Podporované metody

Metoda	Popis	Doporučení
Autentikační aplikace	TOTP kód z Google/Microsoft Authenticator	Doporučeno – nejbezpečnější
E-mail	6místný kód zaslaný e-mailem	Záloha pro uživatele bez smartphonu

Volbu i nastavení těchto metod provádí uživatel ve svém profilu na straně Klubero SSO. Z pohledu integrující aplikace jde o interní chování přihlašovací stránky.

Doporučená metoda

Autentikační aplikace (Google Authenticator, Microsoft Authenticator, Authy) je nejbezpečnější a nejpohodlnější metoda:

• Funguje offline
• Kódy se generují lokálně
• Žádné čekání na e-mail
• Zdarma

Jak funguje autentikační aplikace (TOTP)

TOTP (Time-based One-Time Password) generuje 6místné kódy, které se mění každých 30 sekund:

1. Uživatel si aktivuje 2FA naskenováním QR kódu ve svém profilu
2. Aplikace (Google/Microsoft Authenticator) uloží sdílený tajný klíč
3. Při přihlášení uživatel zadá aktuální 6místný kód z aplikace
4. Klubero SSO ověří kód podle sdíleného tajného klíče

Autentikátor je kompatibilní se všemi standardními aplikacemi podporujícími RFC 6238 TOTP (Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden a další).

---

Správa 2FA přes REST API (M2M)

Pro serverovou (machine-to-machine) integraci nabízí Klubero SSO endpointy pro správu nastavení 2FA uživatelů. Tyto endpointy jsou volitelné a slouží například administračním nástrojům na straně vaší aplikace — nejsou součástí přihlašovacího flow.

Autorizace

Všechny endpointy pro správu 2FA vyžadují access token získaný přes client_credentials se scope api. Uživatelské tokeny (získané přes Authorization Code Flow) tyto endpointy volat nemohou.

Ve všech příkladech je {guid} GUID uživatele. JSON používá camelCase a výčtové hodnoty (enums) se serializují jako čísla.

Číselné hodnoty metody 2FA

Metoda 2FA (TwoFactorMethodType) se v API předává a vrací jako číslo:

Hodnota	Metoda
2	E-mail
3	Autentikátor (TOTP)

Zjištění stavu 2FA

Endpoint: GET /api/twofactor/{guid}/status

curl https://your-sso-domain.com/api/twofactor/USER_GUID/status \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN"

Odpověď:

{
  "enabled": true,
  "primaryMethod": 3
}

Pole primaryMethod je číslo (2 = E-mail, 3 = Autentikátor) nebo null, pokud uživatel nemá 2FA povolené.

Povolení 2FA

Endpoint: POST /api/twofactor/{guid}/enable

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/enable \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "method": 3 }'

Odpověď:

{
  "enabled": true,
  "recoveryCodes": ["ABC12345", "DEF67890", "GHI11213"]
}

Pole recoveryCodes obsahuje jednorázové záložní kódy, které si uživatel musí bezpečně uložit.

Zakázání 2FA

Endpoint: POST /api/twofactor/{guid}/disable

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/disable \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN"

Odeslání kódu

Endpoint: POST /api/twofactor/{guid}/send-code

Odešle ověřovací kód zvolenou metodou. Pole method i purpose jsou čísla.

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/send-code \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "method": 2, "purpose": 1 }'

Vygenerování nových záložních kódů

Endpoint: POST /api/twofactor/{guid}/recovery-codes

curl -X POST https://your-sso-domain.com/api/twofactor/USER_GUID/recovery-codes \
  -H "Authorization: Bearer M2M_ACCESS_TOKEN"

Odpověď:

{
  "recoveryCodes": ["ABC12345", "DEF67890", "GHI11213"]
}

Záložní kódy

Každý záložní kód lze použít pouze jednou. Po vygenerování nové sady jsou předchozí kódy zneplatněny.

Vlastnosti ověřovacího kódu

Autentikátor (TOTP)

Vlastnost	Hodnota
Formát	6 číslic
Životnost	30 sekund
Tolerance	±30 sekund (pro synchronizační rozdíly)
Algoritmus	HMAC-SHA1 (RFC 6238)

E-mail

Vlastnost	Hodnota
Formát	6 číslic (000000–999999)
Životnost	10 minut
Doručení	E-mail

Kompatibilní aplikace

Autentikační metoda TOTP je kompatibilní se všemi standardními autentikátory:

• Google Authenticator (Android, iOS)
• Microsoft Authenticator (Android, iOS)
• Authy (Android, iOS, Desktop)
• 1Password (integrováno)
• Bitwarden (integrováno)
• Jakákoli aplikace podporující RFC 6238 TOTP