Dvojfázové overenie (2FA) je možné pre jednotlivých používateľov zapnúť nielen v aplikácii, ale aj cez REST API. Tento článok popisuje endpointy na zistenie stavu, vystavenie QR kódu a na zapnutie i vypnutie dvojfázového overenia.

⚠️ Zapnuté dvojfázové overenie sa vzťahuje aj na volanie REST API s HTTP autentizáciou. Každá požiadavka daného používateľa musí potom obsahovať query parameter otp s aktuálnou hodnotou jednorazového hesla. Bez neho prestanú fungovať aj doteraz funkčné integrácie.

Nastavenie dvojfázového overenia priamo v aplikácii popisuje dvojfaktorová autentizácia.

Zistenie stavu

Či má používateľ dvojfázové overenie zapnuté, zistíte z detailu používateľa v elemente twoPhaseAuthEnabled:

GET /u/{username}.xml

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

Rovnaký element nájdete aj vo výpise všetkých používateľov na /u. Podporované sú obvyklé výstupné formáty.

Vystavenie QR kódu

Pre zadaného používateľa vystaví QR kód s novo vygenerovaným privátnym kľúčom:

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

Odpoveďou je obrázok vo formáte image/png (400 × 400 px). Privátny kľúč v textovej podobe nájdete v HTTP hlavičke odpovede Secret — túto hodnotu budete potrebovať na zapnutie overenia.

Príklad hlavičiek odpovede:

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

ℹ️ Príponu .png v URL uveďte, alebo namiesto nej odošlite hlavičku Accept: image/png. Bez jednej z týchto možností požiadavka skončí chybou 404.

Pokiaľ má používateľ dvojfázové overenie už aktívne, operácia vracia stavový kód 403.

Zapnutie

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

Parametre:

Parameter	Povinný	Popis
`username`	áno	Používateľské meno práve prihláseného používateľa
`secret`	áno	Privátny kľúč používateľa z hlavičky `Secret` pri vystavení QR kódu
`otp`	áno	Jednorazové heslo vygenerované z privátneho kľúča

Vo formáte XML alebo JSON je vrátený príznak úspechu operácie success a správa message:

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

Server jednorazové heslo overuje voči zadanému privátnemu kľúču. Pokiaľ kód nesúhlasí, operácia sa nevykoná a vráti chybu Nesouhlasí kód pro dvoufázové ověření.

Vypnutie

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

Parametre:

Parameter	Povinný	Popis
`username`	áno	Používateľské meno práve prihláseného používateľa
`otp`	áno	Jednorazové heslo

Výsledok:

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

Pri chybnom jednorazovom hesle operácia vracia stavový kód 403.

Vypnutie administrátorom

Používateľ s oprávnením Meniť heslo používateľom môže vypnúť dvojfázové overenie inému používateľovi, a to bez znalosti jeho jednorazového hesla:

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

Parameter username je povinný a určuje používateľa, ktorému sa má overenie vypnúť. Bez potrebného oprávnenia operácia vracia stavový kód 403.

FAQ

Zapol som 2FA a prestala mi fungovať integrácia. Prečo?

Dvojfázové overenie platí aj pre REST API. Každá požiadavka používateľa s HTTP autentizáciou musí niesť query parameter otp s aktuálnym jednorazovým heslom. Pre servisné účty preto zvážte, či u nich dvojfázové overenie zapínať.

Používateľ stratil prístup k aplikácii s jednorazovými heslami. Čo ďalej?

Overenie mu vypne používateľ s oprávnením Meniť heslo používateľom cez PUT /u/disable-2fa?username={username}. Potom si môže vystaviť nový QR kód a overenie znovu zapnúť.

Musím si privátny kľúč uchovávať?

Kľúč potrebujete iba v okamihu zapnutia overenia. Uchovávajte ho bezpečne a nikdy ho neposielajte v URL, ktoré sa logujú.

💡 V prípade otázok k aplikácii nás kontaktujte na podporaflexi@abra.eu prípadne prostredníctvom chatovacieho okna v pravom dolnom rohu.

Sorodni članki

Dvojfázové overenie – API