ABRA Flexi umožňuje použít kontakty uložené v databázi k autentizaci — typicky když chcete zákazníkům z adresáře dát přihlášení do vlastní aplikace nebo e-shopu, aniž byste jim zakládali uživatelské účty do Flexi. Přes REST API se kontaktu nejdřív nastaví jméno a heslo, potom se dá ověřovat.
Nastavení jména a hesla
Jméno a heslo se kontaktu nastavují běžným importem do evidence kontakt. Heslo lze poslat dvěma způsoby.
Heslo v otevřené podobě
Nejjednodušší varianta — atributy hash a salt zůstanou prázdné:
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 otevřené podobě ABRA Flexi uloží v bezpečné formě pomocí hash funkce. Při čtení kontaktu je vlastnost password vždy prázdná — uložený hash se přes API nevrací.
Heslo jako výsledek hash funkce
Heslo je možné poslat už zahashované. V tomto případě jsou atributy 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ýsledek hash funkce aplikované na řetězec, který vznikne spojením hodnoty salt, dvojtečky a hesla — tedy salt + ":" + heslo. Výsledek se zapisuje jako hexadecimální řetězec malými písmeny. Původní heslo v tomto případě není nutné zasílat.
💡 Pořadí a dvojtečka jsou podstatné. Pro heslo tajne a salt rovný abcd se hashuje řetězec abcd:tajne — ne tajneabcd ani abcdtajne.
Podporované typy hash funkcí:
Hodnota atributu | Poznámka |
| Výchozí funkce pro ukládání hesel poslaných v otevřené podobě. |
| — |
| — |
| — |
| Nejbezpečnější, ale také výrazně nejpomalejší metoda — je záměrně pomalá. |
⚠️ Jiná hodnota atributu hash skončí chybou 400 s kódem hashInvalid a hlášením Nepodporovaná hodnota atributu hash.
Autentizace kontaktu
Kontakt se ověří požadavkem POST na akci authenticate. Jméno a heslo se posílají jako data formuláře:
POST https://demo.flexibee.eu/c/demo/kontakt/1/authenticate
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
username=jan&password=heslo
Autentizace funguje také na obecné URL kontaktů, tedy bez uvedení konkrétního 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 se do akce authenticate posílá vždy v otevřené podobě — i tehdy, když jste ho nastavovali už zahashované. Hash si ABRA Flexi spočítá sama.
Výsledek
🚨 Výsledkem je vždy odpověď s HTTP stavem 200 — a to i při neúspěšném ověření. Úspěch nikdy neposuzujte podle stavového kódu, ale výhradně podle vlastnosti success v těle odpovědi.
Úspěšná autentizace:
<?xml version="1.0"?>
<winstrom version="1.0">
<success>true</success>
<message/>
</winstrom>
Neúspěšná autentizace:
<?xml version="1.0"?>
<winstrom version="1.0">
<success>false</success>
<message>Bylo zadáno chybné uživatelské jméno či heslo.</message>
</winstrom>