Autentizace a autorizace | ABRA API dokumentace

Standardní přihlášení

Přihlášení probíhá klíčem Authorization v HTTP hlavičce požadavku metodou Basic Authentication. Argumenty musí být v UTF-8 a musí být zakódovány do base64 (včetně oddělovacích znaků).

Authorization: Basic login:[password|token][;lock_connection]

Argument	Popis argumentu
login	Přihlašovací jméno. Jedná se standardně o povinný parametr. Parametr je nepovinný pouze tehdy, pokud je zatržen parametr Umožnit rychlé přihlášení přes token. Přihlašovací jméno nesmí obsahovat znak dvojtečky ":". Pokud znak dvojtečky bude obsahovat, vrátí přihlášení do Web API chybu: `{"error":"Unauthorized"}` Přihlašovací jméno se vždy uvádí s dvojtečkou na konci. Tj. i tehdy, pokud není vyplněno heslo nebo token.
password	Heslo uživatele, který se přihlašuje. Jedná se o nepovinný parametr.
token	Token uživatele, který se přihlašuje. Jedná se o nepovinný parametr. Pokud je zatržen parametr Umožnit rychlé přihlášení přes token není nutné vyplňovat login (Uživatelské jméno). V takovém případě je nutné před token uvést znak dvojtečky. Pokud se login nevyplní, použije se jako výchozí login řetězec ~token~. Přihlášení na uživatele s tímto loginem (resp. Přihlašovacím jménem) pak probíhá přes vyplněný Token. Přihlášení na tohoto uživatele se realizuje jako první. V aplikaci Postman se Token může na záložce Authorization vyplnit do pole Password.
lock_connection	Heslo zámku parametru Spojení je uzamčeno v nástroji DBAdmin.exe. Je třeba jej uvést za středník. Jedná se o nepovinný parametr. Heslo, token ani heslo zámku spojení nesmí obsahovat středník ";". Pokud znak středníku bude obsahovat uživatelské heslo nebo token, vrátí přihlášení do Web API chybu: `{"error":"ApiLib library user verification failed, internal error EWARESTError - Status: 500, title: Volání do spojení, description: Nepodařilo se ověřit uživatele, ověření skončilo chybou NxError: Nepodařilo se otevřít spojení. \r\nChybné heslo zámku spojení"}` `{"error":"ApiLib library user verification failed, internal error EWARESTError - Status: 500, title: Volání do spojení, description: Nepodařilo se ověřit uživatele, ověření skončilo chybou NxError: Nepodařilo se otevřít spojení. \r\nChybné heslo zámku spojení"}` Pokud znak středníku bude obsahovat heslo zámku, vrátí přihlášení do Web API chybu: `{"error":"Nepodařilo se otevřít spojení. \r\nChybné heslo zámku spojení","error_code":1114}` Po nastavení Hesla zámku je nutno Web API restartovat.

Uživatel je Supervisor, heslo (či token) je 1234. Supervisor:1234 zakódován do base64 je řetězec U3VwZXJ2aXNvcjoxMjM0. V HTTP hlavičce požadavku tedy bude uvedeno:

Authorization: Basic U3VwZXJ2aXNvcjoxMjM0

Uživatel je Supervisor, heslo ani token nejsou vyplněny. Supervisor: zakódován do base64 je řetězec U3VwZXJ2aXNvcjo=. V HTTP hlavičce požadavku tedy bude uvedeno:

Authorization: Basic U3VwZXJ2aXNvcjo=

Uživatel je Supervisor, heslo (či token) je 1234, heslo zámku je 567. Supervisor:1234;567 zakódován do base64 je řetězec U3VwZXJ2aXNvcjoxMjM0OzU2Nw. V HTTP hlavičce požadavku tedy bude uvedeno:

Authorization: Basic U3VwZXJ2aXNvcjoxMjM0OzU2Nw

Uživatel je Supervisor, heslo ani token nejsou vyplněny, heslo zámku je 567. Supervisor:;567 zakódován do base64 je řetězec U3VwZXJ2aXNvcjo7NTY3. V HTTP hlavičce požadavku tedy bude uvedeno:

Authorization: Basic U3VwZXJ2aXNvcjo7NTY3

Uživatel je Supervisor, token je 1234, parametr Umožnit rychlé přihlášení přes token je zatržen. :1234 zakódován do base64 je řetězec OjEyMzQ. V HTTP hlavičce požadavku tedy bude uvedeno:

Authorization: Basic OjEyMzQ

Pro zakódování a dekódování řetězců lze využít různé on-line nástroje typu Base64 decoder/encoder. Aplikace pro odesílání REST API požadavků jako např. Postman dokáží uživatelské jméno a heslo zakódovat i vygenerovat HTTP hlavičku.

Doménové přihlášení

Doménové přihlášení je z pohledu API realizováno stejně jako standardní přihlášení, ale je třeba zohlednit obdobná pravidla jako pro přihlášení uživatele přes doménový server.

Podmínky, aby doménové přihlášení fungovalo:

Aplikační server musí být na serveru (PC), který je v doméně a musí běžet pod doménovým účtem.
API server může být nainstalován na doménovém serveru, ale i na nedoménovém. Spuštěn může být pod doménovým i nedoménovým, účtem.
Klient (např. Postman) může být spuštěn kdekoliv, tzn. není vyžadováno PC připojené do domény ani doménový účet.

Autentizace proběhne v těchto případech:

Dotaz bude obsahovat doménové jméno shodné s přihlašovacím jménem v ABRA Gen a doménové heslo.
Dotaz bude obsahovat doménové jméno shodné s přihlašovacím jménem v ABRA Gen a tokenem v ABRA Gen.

Pokud dotaz bude obsahovat doménové jméno, bude zatržen parametr Umožnit rychlé přihlášení přes token, bude vyplněn Token, Heslo nebude prázdné a jako Přihlašovací jméno bude uveden řetězec ~token~, pak přihlášení také proběhne a navíc se tento způsob přihlášení realizuje jako první.

Autentizace neproběhne v těchto případech:

Dotaz bude obsahovat doménové jméno shodné s přihlašovacím jménem v ABRA Gen, ale nebude obsahovat heslo či token.

Pokud bude klient přihlášen pod doménovým jménem shodným s přihlašovacím jménem v ABRA Gen a současně pod stejným doménovým účtem je spuštěn API server, dojde k přihlášení, i pokud dotaz nebude obsahovat heslo.
Dotaz bude obsahovat doménové jméno shodné s přihlašovacím jménem v ABRA Gen a heslo v ABRA Gen.

Query parametr auth

Přihlašování do API podporuje normu RFC 4648. V praxi to znamená, že je možné používat URL Safe verzi kódováni Base64 (base64url) v hlavičce Authorization i v Query parametr auth.

Mějme uživatele Supervisor s heslem 12345 a aliasem spojení data. Abra Web API nám poběží na lokálním portu 8082. Potom výběr z kolekce faktur vydaných, kde každá faktura bude obsahovat částku (Amount) a celý objekt firmy (Firm_ID), provedeme s parametrem auth takto.

http://localhost:8082/data/issuedinvoices?select=Amount&expand=Firm_ID&auth=U3VwZXJ2aXNvcjoxMjM0NQ

Upozorňujeme, že, jak bylo řečeno výše, parametru auth je nutno předat hodnotu jméno:heslo (v našem příkladu Supervisor:12345) zakódovanou do base64url. Samotné base64 nestačí!

Oprávnění uživatelé

Přístup k API je umožněn pouze uživatelům systému ABRA Gen, kteří mají ve svém nastavení zatržený příznak Přihlášení nevizuálního uživatele API. Při přístupu k datům jsou zohledňována práva k chráněným objektům a také obecná funkcionalita ochrany dat.

Nejsou zohledňována práva k funkcím, která se týkají pouze práce s uživatelským rozhraním ABRA Gen.

Thread pool a Connection pool

Thread pool v systému ABRA Gen Web API slouží k paralelní obsluze volání, kde maximální počet současně obsluhovaných volání je určen parametrem threadPoolSize. Každé volání musí projít procesem autentizace, který je pro opakované dotazy z téhož zdroje urychlen díky serverové keši.

V reálném provozu se však můžeme setkat s výzvou v podobě nevalidních volání generovaných typicky různými boty, což může ovlivnit celkovou výkonnost API. Pro řešení této situace byl vytvořen tzv. Connection pool.

V kontextu systému se Connection pool využívá pro nepřihlášená pracovní vlákna. Tato implementace působí jako počáteční etapa zpracování, kde probíhá ověření volání předtím, než jsou tato volání předána do hlavního Thread poolu. Tato prvotní fáze zpracování je méně náročná na systémové prostředky, neboť se soustředí především na základní ověření volání. Connection pool je konfigurovatelný pomocí parametrů connectionPoolSize, connectionQueueTimeoutMs a connectionTimeoutMs.

Pokud je skrze Connection pool ověřeno, že se jedná o validní volání (tj. volání od uživatele identifikovaného v databázi, nikoli od bota), je takové volání předáno do hlavního Thread poolu pro další zpracování. Tímto postupem je zajištěno, že výkonnost Web API je optimalizována při současném dodržování nezbytných bezpečnostních opatření.

Přístup k chráněným objektům

Kromě ochrany dat ve smyslu obecné funkcionality ochrany dat, která je předmětem samostatné kapitoly, Web API zohledňuje také práva aktuálního uživatele k chráněným objektům, včetně nastavení omezení pro číselníky chráněných objektů. Omezení za chráněné objekty jsou aplikována na všechny business objekty.

Obecně platí:

K získávání informací o business objektech s vazbami na chráněné objekty (metodou GET v režimu základního dotazování i metodou POST v režimu rozšířeného dotazování) je zapotřebí právo Zobrazit ke všem chráněným objektům, které jsou na daném objektu použity.
K ukládání (metody POST, PUT a DELETE) je zapotřebí právo Použít ke všem chráněným objektům, na které se ukládaný business objekt odkazuje.

Obě práva tedy mají při práci v aplikaci ABRA Gen i v rozhraní Web API stejný význam.

V číselníku vlastních bankovních účtů je nadefinovaný účet 98765432100/5500.

Uživatel Smith je obsazený do role, která má k tomuto účtu právo Zobrazit, ale nemá právo Použít. K datům přistupuje prostřednictvím uživatelského rozhraní aplikace ABRA Gen.

Uživatel Smith si může zobrazit fakturu vydanou, která má v položce Vlastní účet vyplněný odkaz na bankovní účet 98765432100/5500, protože k tomuto účtu má právo Zobrazit.
Pokud je na některé faktuře vydané nastavený jiný bankovní účet, uživatel Smith ho v aplikaci ABRA Gen nemůže změnit na 98765432100/5500, protože k tomuto účtu nemá právo Použít.

Uživatel Apu je obsazený do stejné role, ve vlastnostech uživatele má zatržený příznak přihlášení nevizuálního uživatele API, k datům přistupuje prostřednictvím rozhraní Web API.

Stejně jako uživatel Smith může uživatel Apu získat (zobrazit) informace o faktuře vydané.
Stejně jako uživatel Smith nemůže uživatel Apu na hlavičkách faktur nastavovat vazbu na účet 98765432100/5500, protože k tomuto účtu nemá právo Použít.

Při aktualizaci business objektů je zapotřebí právo Použít ke všem navázaným chráněným objektům, nejen k těm, jejichž hodnoty se mění. Pro změnu bankovního účtu na hlavičce faktury je tedy zapotřebí nejen právo Použít k příslušnému bankovnímu účtu, ale také například ke všem skladům, které jsou použity na řádcích daného dokladu.

Při práci s doklady tvořenými hlavičkou a řádky platí:

Je uplatňována stejná logika jako při práci s doklady ve vizuálním prostředí ABRA Gen - tj. pokud doklad obsahuje řádky s odkazy na chráněné objekty, ke kterým uživatel nemá přístup, doklad je možné načíst (včetně řádků), ale není možné jej uložit.

Pro bezpečnostní omezení (security podmínky) platí:

Pro systémové položky na jednotlivých business objektech jsou brány v úvahu informace zaregistrované v DynSQL - pokud není změna v DynSQL, použije se výchozí (DynSQL)SecurityMask z číselníku. Výchozí hodnota parametru SecurityWithNull je True.
Parametry definovatelných položek (běžných uživatelských položek i extra položek) jsou načítány zvlášť, bezpečnostní omezení jsou u nich společná pro výběr i pro ukládání.
Na vlastněné kolekce a na odkazované business objekty nejsou bezpečnostní omezení aplikována.
Rovněž na hierarchické business objekty nejsou bezpečnostní omezení aplikována. Přesněji nejsou aplikována na referenční položky business objektu, které ukazují na stejný typ business objektu, jako je ten, na kterém jsou definovány. Příkladem je hierarchická struktura středisek - i když je struktura definována (s využitím položky Parent_ID), bezpečnostní omezení je zapotřebí nastavit pro každý záznam (středisko) zvlášť, bez ohledu na hierarchii.