Pre partnerské riešenia, ktoré potrebujú spravovať inštancie ABRA Flexi v cloude, sme pripravili API, ktoré to umožňuje. Jeho stav je zatiaľ beta a tento dokument popisuje plánovaný stav. Všetko si dôkladne pred použitím overte.
Autentifikácia požiadaviek voči ABRA Flexi
ABRA Flexi podporuje niekoľko spôsobov tzv. serverovej autorizácie:
serverovým menom a heslom – pri zadaní špeciálneho mena a hesla je akceptovaná serverová autorizácia. Toto riešenie nie je použiteľné v cloude.
klientským certifikátom – umožňuje, aby sme pre každého partnera alebo inštanciu mali certifikát, ktorý umožňuje administráciu. Toto riešenie zatiaľ nie je použiteľné mimo cloudu.
Serverové meno a heslo
Pre tento typ autorizácie je potrebné upraviť /etc/flexibee/server-auth.xml a doplniť:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"><properties> <comment>WinStrom server configuration</comment> <entry key="username">winstrom-server-admin</entry> <entry key="password">velmi-tajne-a-hodne-dlouhe-heslo</entry></properties>
Po reštarte servera sa meno a heslo už akceptuje.
Poznámka: heslo musí byť minimálne 15 znakov dlhé. Toto heslo umožní prístup ku všetkým údajom na danej inštalácii. Bezpečne ho ukladajte!
Klientským certifikátom
Bezpečnejším spôsobom je použitie certifikátu. Možno sa ním autorizovať na získanie administrátorského prístupu. Pre komunikáciu je nutné použiť protokol HTTPS a pripájať sa na port 7000. Na serveri je uložený iba odtlačok certifikátu (SHA1 fingerprint).
Odtlačok certifikátu možno získať takto:
openssl x509 -noout -in cert.pem -fingerprint
Tento odtlačok je potrebné zaslať na podporu a bude nastavený do danej inštancie, resp. stromu inštancií (ich zoskupenia).
Impersonifikácia používateľa
V niektorých prípadoch je potrebné, aby sa server prihlásil a následne sa vyhlásil za jedného z používateľov.
To možno vykonať doplnením hlavičky:
X-FlexiBee-Authorization: jmeno.
Od tej chvíle budú všetky zmeny vrátane práv vykonané pod týmto používateľom.
Scenáre použitia API
Celé ABRA Flexi REST API vždy pracuje nad jednou databázou s údajmi firmy. Výnimkou je správa používateľov a firiem. Tá je z firmy vyňatá a uložená iným spôsobom. Informácie o používateľoch sú pri bežnej inštalácii v databáze centralServer. Firmy sú v jednotlivých databázach. V prípade cloudovej prevádzky sú informácie vo vysoko replikovanej databáze CouchDB.
Ak by sa spracovanie robilo vo viacerých požiadavkách, je možné, že pri prideľovaní práv používateľa do firmy obsluhujúci server nebude vedieť, že firma alebo používateľ je už založený. Preto vzniklo toto dávkové API, kedy sa odovzdá zoznam operácií a vykoná ich jeden server, čím je zabezpečená konzistencia.
Pretože požiadavka môže zlyhať (napríklad pri dočasnej nedostupnosti jednej z komponentov), je možné požiadavku zopakovať. Potom sa vykoná všetko tak, ako je uvedené, znova. Ak už nejaká zmena bola vykonaná, operácia sa preskočí (operácie sú idempotentné).
Založenie účtu administrátora ABRA Flexi inštancie a predvolenej účtovnej firmy
So založením ADMIN účtu v ABRA Flexi sa založí predvolená účtovná firma podľa údajov z objednávky (budeme mať názov firmy, IČO).
Nie je možné založiť firmu bez administrátorského používateľa.
<flexibee-batch id="abc-1">
<user action="create-update">
<username>admin</username>
<password hash="sha256" salt=”123”>f86vs6vds66</password>
<email>admin@firma.cz</email>
<givenName>Roman</givenName>
<familyName>Skamene</familyName>
<ssoIdentifier>admin@firma.cz</ssoIdentifier>
<defaultRole>ADMIN</defaultRole>
<permissions>
<manageAll>true</manageAll>
<createCompany>false</createCompany>
<deleteCompany>false</deleteCompany>
<createUser>false</createUser>
<changePassword>false</changePassword>
<grantPermission>false</grantPermission>
<licenseManagement>false</licenseManagement>
</permissions>
</user>
<company action="create-update">
<id>digitalni_media_s_r_o_</id>
<name>Digitalní media s.r.o.</name>
<country>CZ</country>
<regNo>966664322</regNo><!-- IČ -->
<type>PODNIKATELE</type>
<adminUser role="ADMIN">admin</adminUser>
</company>
</flexibee-batch>
Štandardné používateľské roly v ABRA Flexi
ADMIN
SUPERUZIVATEL
MZDOVYUCETNI
UCETNI
OBCHODNIK
SKLADNIK
SKLADNIKSPOKLADNOU
UZIVATEL
JENCIST
ZABLOKOVAN
Typ organizácie + evidencia
Podvojné účtovníctvo je predvolené pre všetky typy organizácií.
PODNIKATELE
PODNIKATELE+PU (podvojné účtovníctvo)
PODNIKATELE+DE (daňová evidencia)
ROZPOCTOVE
NEZISKOVE
PODNIKATELIA (iba pre Slovensko)
Podporované hash funkcie pre ukladanie hesiel
sha256 (predvolená pre ukladanie hesiel zaslaných v plain texte)
sha512
sha1
md5
pbkdf2 (najbezpečnejšia, ale aj najpomalšia metóda – bez používania session pri REST API je potom nepoužiteľná – je zámerne príliš pomalá).
Ukážka programu pre výpočet odtlačku hesla pre ABRA Flexi.
import org.apache.commons.codec.binary.Hex; public static final String SHA256 = "sha256"; public static final String SEPARATOR = ":"; protected static String encryptPasswordSHA256(String plain, String salt) { String toDigest = salt + SEPARATOR + plain; try { MessageDigest md = MessageDigest.getInstance("SHA-256"); byte[] result = md.digest(toDigest.getBytes("utf-8")); return SHA256 + SEPARATOR + salt + SEPARATOR + new String(Hex.encodeHex(result)); } catch (UnsupportedEncodingException e) { throw new RuntimeException(e); } catch (GeneralSecurityException e) { throw new RuntimeException(e); } } public static String getRandomSalt() { byte[] b = new byte[10]; new Random().nextBytes(b); return new String(Hex.encodeHex(b)).substring(10); } String plain = "moje heslo"; String result = encryptPasswordSHA256(plain, getRandomSalt());Založenie ďalších „bežných" používateľov
Títo používatelia sa budú zakladať už z Admin portálu ako noví používatelia správcom tenanta. Bude volané aj hromadne pre viacerých používateľov pri zmene profilu na Admin portáli.
<?xml version="1.0"?><flexibee-batch id="abc-12"> <user action="create-update"> <username>anna.mlada</username> <password hash="sha256" salt="123">f86vs6vds66</password> <email>anna.mlada@firma.cz</email> <givenName>Anna</givenName> <familyName>Mladá</familyName> <defaultRole>UZIVATEL</defaultRole> <permissions> <manageAll>true</manageAll> </permissions> </user></flexibee-batch>
Možno uložiť aj heslo bez saltu, ale dôrazne to neodporúčame!
Zmena hesla existujúceho používateľa
<?xml version="1.0"?><flexibee-batch id="abc-123"> <user action="create-update"> <username>anna.mlada</username> <password hash="sha256" salt="123">f86vs6vds66</password> </user></flexibee-batch>
Vymazanie existujúceho používateľa
Vymazanie používateľa z Admin portálu = uvoľnenie licencie. Bude volané aj hromadne pre viacerých používateľov pri zmene profilu.
<?xml version="1.0"?><flexibee-batch id="abc-12345"> <user action="delete"> <username>anna.mlada</username> </user></flexibee-batch>
Poznámka: ak bol používateľ vymazaný a neskôr nastavím create-update, mal by sa znova obnoviť.
Obnovenie používateľa
<?xml version="1.0"?><flexibee-batch id="abc-123456"> <user action="create-update"> <username>anna.mlada</username> </user></flexibee-batch>
Poznámka: pri create-update používateľa sa najprv skúša recyklovať záznamy s príznakom „vymazané". Všetky nastavenia prístupov a rolí zostanú zachované.
Blokovanie existujúceho používateľa
Zablokovanie používateľa z Admin portálu = nemôže sa prihlásiť.
<?xml version="1.0"?><flexibee-batch id="abc-123456"> <user action="create-update"> <username>anna.mlada</username> <blocked message="Blocked from external system">true</blocked> </user></flexibee-batch>
Odblokovanie používateľa
<?xml version="1.0"?><flexibee-batch id="abc-123456"> <user action="create-update"> <username>anna.mlada</username> <blocked>false</blocked> </user></flexibee-batch>
Pridanie roly ADMIN existujúcemu používateľovi
Pridanie atomickej roly „ERP administrátor" na Admin portáli. Môže byť volané aj hromadne pre viacerých používateľov pri zmene profilu na Admin portáli.
<?xml version="1.0"?><flexibee-batch id="abc-1234567"> <user action="create-update"> <username>anna.mlada</username> <defaultRole>ADMIN</defaultRole> </user> <access role="ADMIN"/></flexibee-batch>
Odobratie roly ADMIN existujúcemu používateľovi
Odobratie atomickej roly „ERP administrátor" na Admin portáli. Môže byť volané aj hromadne pre viacerých používateľov pri zmene profilu na Admin portáli.
<?xml version="1.0"?><flexibee-batch id="abc-12345678"> <user action="create-update"> <username>anna.mlada</username> <defaultRole>UZIVATEL</defaultRole> </user> <access role="UZIVATEL"/></flexibee-batch>
Zmena mena, priezviska existujúceho používateľa
<?xml version="1.0"?><flexibee-batch id="abc-123456789"> <user action="create-update"> <username>anna.mlada</username> <givenName>Anička</givenName> <familyName>Starší</familyName> </user></flexibee-batch>
Skrytie / zobrazenie firmy (odpojenie)
<?xml version="1.0"?><flexibee-batch id="abc-123"> <company action="create-update"> <id>digitalni_media_s_r_o_</id> <show>false</show> <!-- true pro zobrazení --> </company></flexibee-batch>
Vymazanie firmy
<?xml version="1.0"?><flexibee-batch id="abc-123"> <company action="delete"> <id>digitalni_media_s_r_o_</id> </company></flexibee-batch>
Použitie API
Platné pre prvú zverejnenú testovaciu verziu s funkčným zakladaním používateľov v centrálnej databáze.
Volanie
HTTP PUT na URL = http://server:7000/admin/batch
Požiadavka musí byť autorizovaná.
XML s požiadavkou možno odoslať pomocou curl takto:
curl -3 'https://server:7000/admin/batch' -T batch.xml -E cert.pem
Ukážková požiadavka
batch.xml
<?xml version="1.0"?><flexibee-batch id="abc-123"> <!-- ID by mělo unikátně označovat dávku --> <user> <username>anna.mlada</username> <password hash="sha256" salt="xyz987">af123bd35</password> <email>anna.mlada@firma.cz</email> <givenName>Anna</givenName> <familyName>Mladá</familyName> <permissions> <manageAll>true</manageAll> <createCompany>true</createCompany> <deleteCompany>true</deleteCompany> <createUser>false</createUser> <changePassword>false</changePassword> <grantPermission>true</grantPermission> <licenseManagement>false</licenseManagement> </permissions> <defaultRole>UZIVATEL</defaultRole> </user> <company action="create-update"> <!-- action="create-update" je výchozí akce --> <id>moje_firma_s_r_o_</id> <name>Moje Firma s.r.o.</name> <country>CZ</country> <!-- aktuálně podporované jsou CZ a SK --> <regNo>123</regNo> <!-- IČO --> <vatId>CZ123</vatId> <!-- DIČ --> <type>PODNIKATELE</type> <adminUser>anna.mlada</adminUser> </company> <company action="delete"> <id>demo_a_s_</id> </company> <access role="ADMIN">anna_mlada_s_r_o_</access> <access role="UZIVATEL">moje_firma_s_r_o_</access> <access>demo_a_s_</access> <access role="ADMIN"/> <access>demo_a_s_</access></flexibee-batch>
Odpoveď
Pri úspechu (HTTP 200) je odoslané XML v tomto formáte:
<?xml version="1.0" encoding="UTF-8"?><flexibee-batch-result id="abc-12345678"> <entry> <id>moje_firma_s_r_o_</id> <entity>COMPANY</entity> <action>DELETE</action> <result> <status>SKIPPED</status> <message>Not implemented yet.</message> </result> </entry> <entry> <id>anna.mlada@firma.cz</id> <entity>USER</entity> <action>CREATE_UPDATE</action> <result> <status>CREATED</status> </result> </entry></flexibee-batch-result>
Výčet typov entít
USER
COMPANY
ACCESS_LIST
Výčet typov akcií
CREATE_UPDATE
DELETE
Výčet stavových kódov
CREATED
UPDATED
DELETED
FAILED (popis dôvodu chyby bude v elemente <message>)
SKIPPED (môže byť doplnené elementom <message>)