ABRA Flexi umožňuje použiť kontakty uložené v databáze na autentizáciu — typicky vtedy, keď chcete zákazníkom z adresára dať prihlásenie do vlastnej aplikácie alebo e-shopu bez toho, aby ste im zakladali používateľské účty vo Flexi. Cez REST API sa kontaktu najprv nastaví meno a heslo, potom sa dá overovať.
Nastavenie mena a hesla
Meno a heslo sa kontaktu nastavujú bežným importom do evidencie kontakt. Heslo je možné poslať dvoma spôsobmi.
Heslo v otvorenej podobe
Najjednoduchší variant — atribúty hash a salt zostanú prázdne:
PUT https://demo.flexibee.eu/c/demo/kontakt.xml
<?xml version="1.0"?>
<winstrom version="1.0">
<kontakt>
<id>1</id>
<username>jan</username>
<password hash="" salt="">heslo</password>
</kontakt>
</winstrom>
Heslo zaslané v otvorenej podobe ABRA Flexi uloží v bezpečnej forme pomocou hash funkcie. Pri čítaní kontaktu je vlastnosť password vždy prázdna — uložený hash sa cez API nevracia.
Heslo ako výsledok hash funkcie
Heslo je možné poslať už zahashované. V tomto prípade sú atribúty hash a salt povinné:
PUT https://demo.flexibee.eu/c/demo/kontakt.xml
<?xml version="1.0"?>
<winstrom version="1.0">
<kontakt>
<id>1</id>
<username>jan</username>
<password hash="sha256" salt="abcd">24b7f0b1ec27ba0dd0d0a4a2e1a3b5a7c9d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9</password>
</kontakt>
</winstrom>
Hodnota elementu password je výsledok hash funkcie aplikovanej na reťazec, ktorý vznikne spojením hodnoty salt, dvojbodky a hesla — teda salt + ":" + heslo. Výsledok sa zapisuje ako hexadecimálny reťazec malými písmenami. Pôvodné heslo v tomto prípade nie je potrebné zasielať.
💡 Poradie a dvojbodka sú podstatné. Pre heslo tajne a salt rovné abcd sa hashuje reťazec abcd:tajne — nie tajneabcd ani abcdtajne.
Podporované typy hash funkcií:
Hodnota atribútu | Poznámka |
| Predvolená funkcia na ukladanie hesiel poslaných v otvorenej podobe. |
| — |
| — |
| — |
| Najbezpečnejšia, ale zároveň výrazne najpomalšia metóda — je zámerne pomalá. |
⚠️ Iná hodnota atribútu hash skončí chybou 400 s kódom hashInvalid a hlásením Nepodporovaná hodnota atribútu hash.
Autentizácia kontaktu
Kontakt sa overí požiadavkou POST na akciu authenticate. Meno a heslo sa posielajú ako dáta formulára:
POST https://demo.flexibee.eu/c/demo/kontakt/1/authenticate
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
username=jan&password=heslo
Autentizácia funguje aj na všeobecnej URL kontaktov, teda bez uvedenia konkrétneho záznamu:
POST https://demo.flexibee.eu/c/demo/kontakt/authenticate
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
username=jan&password=heslo
Heslo sa do akcie authenticate posiela vždy v otvorenej podobe — aj vtedy, keď ste ho nastavovali už zahashované. Hash si ABRA Flexi vypočíta sama.
Výsledok
🚨 Výsledkom je vždy odpoveď s HTTP stavom 200 — a to aj pri neúspešnom overení. Úspech nikdy neposudzujte podľa stavového kódu, ale výhradne podľa vlastnosti success v tele odpovede.
Úspešná autentizácia:
<?xml version="1.0"?>
<winstrom version="1.0">
<success>true</success>
<message/>
</winstrom>
Neúspešná autentizácia:
<?xml version="1.0"?>
<winstrom version="1.0">
<success>false</success>
<message>Bylo zadáno chybné uživatelské jméno či heslo.</message>
</winstrom>