Spôsoby autentizácie

HTTP autentizácia
JSON autentizácia
SAMLv2*
OpenID*

* Podporované iba na lokálnej inštalácii. Dostupnosť obmedzená licenciou ABRA Flexi. Konfiguruje sa vo webovom rozhraní servera na adrese /admin/auth-settings.

HTTP autentizácia

Jednoduchá HTTP autentizácia je pôvodný spôsob overovania používateľov pri prihlasovaní do webového rozhrania ABRA Flexi WUI. Zároveň je to aj jedna z možností autentizácie používateľov REST API. Stačí s každou HTTP požiadavkou posielať autentizačnú hlavičku. Pokiaľ hlavičku neuvediete, dôjde k presmerovaniu na prihlasovací formulár, prípadne bude vrátený status 401 Authorization required (požiadavka na HTTP autentizáciu).

Volanie REST API sa snažíme detegovať a naďalej ponúkať HTTP autentizáciu. Ak by detekcia zlyhala, alebo bude potrebné riadiť spôsob autentizácie, je možné využiť parameter ?auth=http (viď parametre URL).

Ukážka komunikácie s jednoduchou HTTP autentizáciou pomocou príkazu curl:

curl -L -v -u winstrom:winstrom 'https://demo.flexibee.eu:5434/c/demo/adresar.xml?detail=custom:kod&limit=1'

⋮ * Server auth using Basic with user 'winstrom' > GET /c/demo/adresar.xml?detail=custom:kod&limit=1 HTTP/1.1 > Host: demo.flexibee.eu:5434> Authorization: Basic d2luc3Ryb206d2luc3Ryb20= > User-Agent: curl/7.54.1 > Accept: */* > < HTTP/1.1 200 OK < Cache-Control: private, max-age=0, no-cache < Set-Cookie: lang=cs;Version=1 < Vary: Accept < Content-Type: application/xml < Content-Length: 150 < Via: 1.1.loadbal-fra-1.c.flexibee.eu <      755  AAA

Pre ukážku autentizácie v PHP viď reálne príklady seriálu API.

Jednoduchú HTTP autentizáciu je možné zasielať aj priamo v URL adrese, tá môže vyzerať napríklad takto: "https://jmeno:heslo@adresa_serveru:5434/c/firma/evidence". Ako URL adresu zostaviť opisuje náš iný návod.

Dvojfázové overovanie

V prípade aktívneho dvojfázového overovania musí byť HTTP autentizácia doplnená query parametrom otp s aktuálnou hodnotou jednorazového hesla, a to pri každej požiadavke:

curl -L -v -u winstrom:winstrom 'https://demo.flexibee.eu:5434/c/demo/adresar.xml?detail=custom:kod&limit=1&otp={otp-code}'

Zapnutie a vypnutie overenia cez API popisuje dvojfázové overenie.

JSON autentizácia (autentizačné sedenie)

Ak chcete overiť ABRA Flexi a využívať vytvorenú autentizáciu aj pre ďalšie volania, použite API na získanie autentizačného tokenu:

POST /login-logout/login.json

Pozn.: Metóda poskytuje výsledok iba vo formáte JSON, preto v dotaze správne špecifikujte požadovaný formát.

Volanie musí obsahovať prihlasovacie údaje. Server prijíma tak raw dáta (JSON), ako aj formulárové dáta (application/x-www-form-urlencoded):

`username`	Používateľské meno
`password`	Používateľské heslo
`otp`	Jednorazové heslo (ak je vyžadované)

Príklad volania (raw dáta):

{    "username": "novak",    "password": "heslo"}

Úspešná autentizácia

Výsledkom je príznak úspechu success=true a autentizačný token authSessionId. Odpoveď ďalej obsahuje refreshToken na obnovenie sedenia a csrfToken:

{
  "success": true,
  "authSessionId": "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
  "refreshToken": "4f133f49-ba39-4203-a05a-52fe1c3be244:c42cf011-e439-4d9d-b8c4-780579c20c3e",
  "csrfToken": "f30ad42d-e30b-4bf8-91f2-96fdde02cf70"
}

Neúspešná autentizácia

Neúspešnú autentizáciu signalizuje príznak success=false s upresňujúcim popisom v reťazci errors.reason:

{    "success": false,    "errors": {        "reason": "Bylo zad\u00e1no chybn\u00e9 u\u017eivatelsk\u00e9 jm\u00e9no \u010di heslo."    }}

Možnosti využitia autentizačného tokenu

Získanú autentizáciu je možné odovzdávať v dotazoch tromi spôsobmi:

Cookie: authSessionId: 00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff
HTTP hlavička: X-authSessionId: 00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff
URL query ?authSessionId=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff

Pozor: Pri variante v URL query budú autentizačné údaje logované na serveri ABRA Flexi.

Aby ste udržali token platný, je potrebné udržiavať spojenie pomocou občasného volania GET /login-logout/session-keep-alive.js. My ju voláme každých 60 sekúnd, ale malo by stačiť aj raz za 30 minút.

Ak budete chcieť využiť refreshToken, tak je potrebné ho poslať ako cookie požiadavkou GET /login-logout/check, tým získate nové authSessionId.

Pomocou API je tiež možné vykonávať odhlasovanie používateľov.

Umiestnenie prihlasovacieho formulára na svoje stránky

Ak potrebujete umiestniť prihlasovanie na svoje stránky, inšpirujte sa týmto HTML:

<form action="https://demo.flexibee.eu:5434/login-logout/login.html" method="POST"> 
Jméno: <input type="text" name="username" value=""/>
<br/> 
Heslo: <input type="password" name="password"/>
<br/> 
<input type="submit" name="submit" value="Přihlásit"/> 
</form>

Je tiež možné pridať parameter returnUrl a určiť adresu, na ktorú má byť používateľ presmerovaný. Ak používate OTP, je potrebné pridať ešte parameter otp. Pri použití SSO (OpenID alebo SAMLv2) nie je možné túto metódu použiť.

Reset zabudnutého hesla

Používateľ s vyplneným e-mailom si môže na serveri s nakonfigurovaným SMTP nechať poslať e-mailom resetovací token, pomocou ktorého je možné zmeniť heslo.

Odoslanie e-mailu

PUT /password-reset/send-email

Telo požiadavky vo formáte JSON obsahuje jedinú položku email s adresou používateľa.

ℹ️ Z bezpečnostných dôvodov systém nevráti chybu, ak zadanému e-mailu nezodpovedá žiadny záznam.

Overenie tokenu a zmena hesla

PUT /password-reset/set-password

Telo požiadavky vo formáte JSON obsahuje tieto položky:


`resetToken`	Token, ktorý používateľ dostal e-mailom
`password`	Nové heslo. Musí spĺňať požiadavky na minimálnu silu hesla.

Ak v požiadavke neuvediete password, iba sa skontroluje platnosť tokenu — úspech vracia 200, neplatný token 400.

Sorodni članki

Autentifikácia