Dvoufázové ověření (2FA) lze pro jednotlivé uživatele zapnout nejen v aplikaci, ale také přes REST API. Tento článek popisuje endpointy pro zjištění stavu, vystavení QR kódu a pro zapnutí i vypnutí dvoufázového ověření.

⚠️ Zapnuté dvoufázové ověření se vztahuje i na volání REST API s HTTP autentizací. Každý požadavek daného uživatele pak musí obsahovat query parametr otp s aktuální hodnotou jednorázového hesla. Bez něj přestanou fungovat i dosud funkční integrace.

Nastavení dvoufázového ověření přímo v aplikaci popisuje dvoufaktorová autentizace.

Zjištění stavu

Zda má uživatel dvoufázové ověření zapnuté, zjistíte z detailu uživatele v elementu twoPhaseAuthEnabled:

GET /u/{username}.xml

<user> 
  <username>novak</username> 
  <twoPhaseAuthEnabled>false</twoPhaseAuthEnabled> 
</user>

Stejný element najdete i ve výpisu všech uživatelů na /u. Podporovány jsou obvyklé výstupní formáty.

Vystavení QR kódu

Pro zadaného uživatele vystaví QR kód s nově vygenerovaným privátním klíčem:

GET /u/{username}/qrcode-2fa.png

Odpovědí je obrázek ve formátu image/png (400 × 400 px). Privátní klíč v textové podobě najdete v HTTP hlavičce odpovědi Secret — tuto hodnotu budete potřebovat pro zapnutí ověření.

Příklad hlaviček odpovědi:

HTTP/1.1 200 OK 
Secret: C66NFUGRCLIB5DOM 
Content-Type: image/png

ℹ️ Příponu .png v URL uveďte, nebo místo ní pošlete hlavičku Accept: image/png. Bez jednoho z toho požadavek skončí chybou 404.

Pokud má uživatel dvoufázové ověření již aktivní, operace vrací stavový kód 403.

Zapnutí

PUT /u/{username}/enable-2fa?secret={secret}&otp={otp-code}

Parametry:

Parametr	Povinný	Popis
`username`	ano	Uživatelské jméno právě přihlášeného uživatele
`secret`	ano	Privátní klíč uživatele z hlavičky `Secret` při vystavení QR kódu
`otp`	ano	Jednorázové heslo vygenerované z privátního klíče

Ve formátu XML nebo JSON je vrácen příznak úspěchu operace success a zpráva message:

{ 
  "winstrom": { 
    "@version": "1.0", 
    "success": "true", 
    "message": "Dvoufázové ověření bylo úspěšně nastaveno." 
  } 
}

Server jednorázové heslo ověřuje proti zadanému privátnímu klíči. Pokud kód nesouhlasí, operace se neprovede a vrátí chybu Nesouhlasí kód pro dvoufázové ověření.

Vypnutí

PUT /u/{username}/disable-2fa?otp={otp-code}

Parametry:

Parametr	Povinný	Popis
`username`	ano	Uživatelské jméno právě přihlášeného uživatele
`otp`	ano	Jednorázové heslo

Výsledek:

<winstrom version="1.0"> 
  <success>true</success> 
  <message>Dvoufázové ověření bylo úspěšně vypnuto.</message> 
</winstrom>

Při chybném jednorázovém heslu operace vrací stavový kód 403.

Vypnutí administrátorem

Uživatel s oprávněním Měnit heslo uživatelům může vypnout dvoufázové ověření jinému uživateli, a to bez znalosti jeho jednorázového hesla:

PUT /u/disable-2fa?username={username}

Parametr username je povinný a určuje uživatele, kterému se má ověření vypnout. Bez potřebného oprávnění operace vrací stavový kód 403.

FAQ

Zapnul jsem 2FA a přestala mi fungovat integrace. Proč?

Dvoufázové ověření platí i pro REST API. Každý požadavek uživatele s HTTP autentizací musí nést query parametr otp s aktuálním jednorázovým heslem. Pro servisní účty proto zvažte, zda u nich dvoufázové ověření zapínat.

Uživatel ztratil přístup k aplikaci s jednorázovými hesly. Co dál?

Ověření mu vypne uživatel s oprávněním Měnit heslo uživatelům přes PUT /u/disable-2fa?username={username}. Poté si může nechat vystavit nový QR kód a ověření znovu zapnout.

Musím si privátní klíč uchovávat?

Klíč potřebujete pouze v okamžiku zapnutí ověření. Ukládejte jej bezpečně a nikdy jej neposílejte v URL, která se logují.

💡 V případě dotazů k aplikaci nás kontaktujte na podporaflexi@abra.eu případně prostřednictvím chat okna v pravém dolním rohu.

Související články

Dvoufázové ověření - API