Dávkové operace

Pro partnerská řešení, která potřebují spravovat instance FlexiBee v cloudu, jsme připravili API, které to umožňuje. Jeho stav je zatím beta a tento dokument popisuje plánovaný stav. Vše si důkladně před použitím ověřte.

Autentifikace požadavků vůči FlexiBee

FlexiBee podporuje několik způsobů tzv. serverové autorizace:

  • serverovým jménem a heslem – při zadání speciálního jméne a hesla je akceptována serverová autorizace. Toto řešení není použitelné v cloudu.
  • klientským certifikátem – umožňuje, abychom pro každého partnera nebo instanci měli certifikát, který umožňuje administraci. Toto řešení zatím není použitelné mimo cloud.

Serverové jméno a heslo

Pro tento typ autorizace je nutné upravit /etc/flexibee/server-auth.xml a doplnit:

<?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 restartu serveru se již jméno a heslo akceptuje.

Poznámka: heslo musí být minimálně 15 znaků dlouhé. Toto heslo umožní přístup ke všem datům na dané instalaci. Bezpečně jej ukládejte!

Klientským certifikátem

Bezpečnějším způsobem je použití certifikátu. Lze se jím autorizovat pro získání administrátorského přístupu. Pro komunikaci je nutné použít protokol HTTPS a připojovat se na port 7000. Na serveru je uložen pouze otisk certifikátu (SHA1 fingerprint).

Otisk certifikátu lze získat takto:

openssl x509 -noout -in cert.pem -fingerprint

Tento otisk je nutné zaslat na podporu a bude nastaven do dané instance resp. stromu instancí (jejich seskupení).

Impersonifikace uživatele

V některých případech je nutné, aby se server přihlásil a následně se prohlásil za jednoho z uživatelů. To lze provést doplněním hlavičky:

X-FlexiBee-Authorization: jmeno.

Od té chvíle budou všechny změny včetně práv provedeny pod tímto uživatelem.

Scénáře použití API

Celé FlexiBee REST API vždy pracuje nad jednou databází s daty firmy. Vyjímkou je správa uživatelů a firem. Ta je z firmy vyjmuta a uložena jiným způsobem. Informace o uživatelích jsou u běžné instalace v databázi centralServer. Firmy jsou v jednotlivých databázích. V případě cloudového provozu jsou informace ve vysoce replikované databázi CouchDB. Pokud by se zpracování dělalo ve více požadavcích, je možné, že při přidělování práv uživatele do firmy nebude obsluhující server vědět, že je firma nebo uživatel již založen. Proto vzniklo toto dávkové API, kdy se předá seznam operací a vykoná je jeden server a tím je zajištěna konzistence.

Protože požadavek může selhat (ať už např. při dočasně nedostupnosti jedné z komponent), je možné požadavek zopakovat. Pak se provede vše tak jak je uvedeno znovu. Pokud již nějaká změna byla provedena, operace se přeskočí (operace jsou idempotentní).

Založení účtu administrátora FlexiBee instance a výchozí účetní firmy

Se založením ADMIN účtu ve FlexiBee se založí výchozí účetní firma podle údajů z objednávky (budeme mít název firmy, IČO).

Není možné založit firmu bez administrátorského uživatele.

<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>

Standardní uživatelské role ve FlexiBee

  • ADMIN
  • SUPERUZIVATEL
  • MZDOVYUCETNI
  • UCETNI
  • OBCHODNIK
  • SKLADNIK
  • SKLADNIKSPOKLADNOU
  • UZIVATEL
  • JENCIST
  • ZABLOKOVAN

Typ organizace + evidence

Podvojné účetnictví je výchozí pro všechny typy organizací.

  • PODNIKATELE
  • PODNIKATELE+PU (podvojné účetnictví)
  • PODNIKATELE+DE (daňová evidence)
  • ROZPOCTOVE
  • NEZISKOVE
  • PODNIKATELIA (pouze pro Slovensko)

Podporované hash funkce pro ukládání hesel

  • sha256 (výchozí pro ukládání hesel poslaných v plain textu)
  • sha512
  • sha1
  • md5
  • pbkdf2 (nejbezpečnější, ale také nejpomalejší metoda – bez používání session u REST API je pak nepoužitelná – je záměrně příliš pomalá).

Ukázka programu pro výpočet otisku hesla pro FlexiBee.

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žení dalších „běžných“ uživatelů

Tito uživatelé se budou zakládat již z Admin portálu jako noví uživatelé správcem tenanta. Bude voláno i hromadně pro více uživatelů při změně profilu na Admin portálu.

<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>

Lze uložit i heslo bez saltu, ale důrazně to nedoporučujeme!

Změna hesla existujícího uživatele

<flexibee-batch id="abc-123">
        <user action="create-update">
                    <username>anna.mlada</username>
                    <password hash="sha256" salt="123">f86vs6vds66</password>
        </user>
</flexibee-batch>

Smazání existujícího uživatele

Smazání uživatele z Admin portálu = uvolnění licence. Bude voláno i hromadně pro více uživatelů při změně profilu.

<flexibee-batch id="abc-12345">
        <user action="delete">
                    <username>anna.mlada</username>
        </user>
</flexibee-batch>

Poznámka: pokud byl uživatel smazán a později nastavím create-update, měl by se znovu obnovit.

Obnovení uživatele

<flexibee-batch id="abc-123456">
        <user action="create-update">
                   <username>anna.mlada</username>
        </user>
</flexibee-batch>

Poznámka: při create-update uživatele se nejprve zkouší recyklovat záznamy s příznakem “vymazáno”. Veškeré nastavení přístupů a rolí zůstane zachováno.

Blokace existujícího uživatele

Zablokování uživatele z Admin portálu = nemůže se přihlásit.

<flexibee-batch id="abc-123456">
        <user action="create-update">
                   <username>anna.mlada</username>
                   <blocked message="Blocked from external system">true</blocked>
        </user>
</flexibee-batch>

Odblokování uživatele

<flexibee-batch id="abc-123456">
        <user action="create-update">
                 <username>anna.mlada</username>
                 <blocked>false</blocked>
        </user>
</flexibee-batch>

Přidání role ADMIN existujícímu uživateli

Přidání atomické role „ERP administrátor“ na Admin portálu. Může být voláno i hromadně pro více uživatelů při změně profilu na Admin portálu.

<flexibee-batch id="abc-1234567">
       <user action="create-update">
                <username>anna.mlada</username>
                <defaultRole>ADMIN</defaultRole>
       </user>
       <access role="ADMIN"></access>
</flexibee-batch>

Odebrání role ADMIN existujícímu uživateli

Odebrání atomické role „ERP administrátor“ na Admin portálu. Může voláno i hromadně pro více uživatelů při změně profilu na Admin portálu.

<flexibee-batch id="abc-12345678">
       <user action="create-update">
                   <username>anna.mlada</username>
                   <defaultRole>UZIVATEL</defaultRole>
       </user>
       <access role="UZIVATEL"></access>
</flexibee-batch>

Změna jména, příjmení existujícího uživatele

<flexibee-batch id="abc-123456789">
        <user action="create-update">
                    <username>anna.mlada</username>
                    <givenName>Anička</givenName>
                    <familyName>Starší</familyName>
        </user>
</flexibee-batch>

Skrytí / zobrazení firmy (odpojení)

<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>

Smazání firmy

<flexibee-batch id="abc-123">
    <company action="delete">
        <id>digitalni_media_s_r_o_</id>
        </company>
</flexibee-batch>

Použití API

Platné pro první zvěřejněnou testovací verzi s funkčním zakládáním uživatelů v centrální databázi.

Volání

HTTP PUT na URL = http://server:7000/admin/batch

Požadavek musí být autorizován.

XML s požadavkem lze odeslat pomocí curl takto:

curl -3 'https://server:7000/admin/batch' -T batch.xml -E cert.pem

Ukázkový požadavek

batch.xml

<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Č -->
        <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>

Odpověď

Při úspěchu (HTTP 200) je odesláno XML v tomto formátu:

<?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 typu entit

  • USER
  • COMPANY
  • ACCESS_LIST

Výčet typu akcí

  • CREATE_UPDATE
  • DELETE

Výčet stavových kódů

  • CREATED
  • UPDATED
  • DELETED
  • FAILED (popis důvodu chyby bude v elementu <message>)
  • SKIPPED (může být doplněno elementem <message>)