Autentizace, autorizace a práva

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]

{"error":"Unauthorized"}

{"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í"}

{"error":"Nepodařilo se otevřít spojení. \r\nChybné heslo zámku spojení","error_code":1114}

Authorization: Basic U3VwZXJ2aXNvcjoxMjM0

Authorization: Basic U3VwZXJ2aXNvcjo=

Authorization: Basic U3VwZXJ2aXNvcjoxMjM0OzU2Nw

Authorization: Basic U3VwZXJ2aXNvcjo7NTY3

Authorization: Basic OjEyMzQ

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.

JWT (JSON Web Token) umožňuje bezpečné a efektivní přihlášení uživatelů do Web API systému ABRA Gen. Proces zahrnuje vytvoření přístupového a případně i obnovovacího tokenu, které slouží k autorizaci požadavků na API. Přihlášení pomocí JWT tokenu je třeba nakonfigurovat v agendě Definice JWT a explicitně zatrhnou na uživateli parametr JWT Přihlášení.

Pro generování přihlašovacích JWT na endpointech/currentuser/logintoken a /currentuser/refreshtoken je třeba přidělit uživateli právo Použít příslušnou Definici JWT. Právo lze udělit v agendě Rolenebo Skupiny rolí, na záložce Práva k objektům

Proces přihlášení

1. Získání přístupového a obnovovacího tokenu

Přihlášení se provádí přes endpoint:

POST http://localhost:81/currentuser/logintoken

Parametry:

• Basic Authentication: Uživatel se přihlásí pomocí jména a hesla (pomocí HTTP Basic Auth).

• jwtsettingcode (volitelné): Pokud existuje více definic JWT, je nutné specifikovat kód definice:

  POST http://localhost:81/demodata/currentuser/logintoken?jwtsettingcode=<kod_definice>

Výsledek:

• Přístupový token (access_token): Používá se pro autorizaci běžných API požadavků.
• Obnovovací token (refresh_token, pokud je povolen): Používá se k získání nových tokenů.

2. Použití přístupového tokenu

Pro autorizaci požadavků na API se přístupový token přidává do hlavičky Authorization:

Authorization: Bearer <access_token>

Token je nutné použít před vypršením jeho platnosti (definováno v agendě Definice JWT).

3. Obnovení přístupového tokenu

Pokud je povoleno obnovení přihlášení, lze použít endpoint:

POST http://localhost:81/demodata/currentuser/refreshtoken

Podmínky:

• Obnovovací token musí být platný.
• Přístupový token musí být v poslední desetině své životnosti.

Výsledek:

• Nový přístupový a obnovovací token.

Příklad...

Pro účely příkladu je nakonfigurováno použití přihlašovacího i obnovovacího tokenu.

Vygenerování tokenů, použití přihlašovacího a obnovovacího tokenu:

import base64
import json
import sys

import requests
from http_constants.headers import HttpHeaders

session = requests.Session()
headers = {}
headers[HttpHeaders.CONTENT_TYPE] = HttpHeaders.CONTENT_TYPE_VALUES.json
headers[HttpHeaders.AUTHORIZATION] = "Basic " + (
	base64.urlsafe_b64encode(("tester" + ":" + "testerp").encode("utf-8"))
).decode("utf-8")

# generate new token
response = session.post(
	url="http://localhost:81/demodata/currentuser/logintoken?jwtsettingcode=<kod_definice>",
	headers=headers,
)
if response.status_code != 200:
	print(f"\n\nerror issuing new token: {response.status_code} {response.text}")
	sys.exit(0)
print(f"\n\nnew login and refresh tokens:\n{json.dumps(response.json(), indent=2)}")
access_token = response.json()["access_token"]
refresh_token = response.json()["refresh_token"]

# use login token in authorization as a bearer
headers_token = {}
headers_token[HttpHeaders.CONTENT_TYPE] = HttpHeaders.CONTENT_TYPE_VALUES.json
headers_token[HttpHeaders.AUTHORIZATION] = "Bearer " + access_token
response = session.get(
	url="http://localhost:81/demodata/countries?where=code eq 'cz'",
	headers=headers_token,
)
print("\n\nuse of login token:")
if response.status_code != 200:
	print(f"error: {response.status_code} {response.text}")
	sys.exit(0)
print(f"status code: {response.status_code}")
print("response body:")
print(response.text)

# use refresh token to generate new token(if use of refresh tokens is configured)
headers_refresh = {}
headers_refresh[HttpHeaders.CONTENT_TYPE] = HttpHeaders.CONTENT_TYPE_VALUES.json
headers_refresh[HttpHeaders.AUTHORIZATION] = "Bearer " + refresh_token
response = session.post(
	url="http://localhost:81/demodata/currentuser/refreshtoken",
	headers=headers_refresh,
)
print("\n\nuse of refresh token:")
if response.status_code != 200:
	print(f"error: {response.status_code} {response.text}")
	sys.exit(0)
print(f"new login and refresh tokens: {json.dumps(response.json(), indent=2)}")

Výstup:

new login and refresh tokens:
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJEZW1vdmVyemUiLCJzdWIiOiJ0ZXN0ZXIiLCJhdWQiOiJ0ZXN0IiwiZXhwIjoxNzA4OTU4MzEwLCJwcnAiOiJhdCJ9.dqegGmsotsTvizWflhEgyCetPqy8KmW8rPWXd47XqwQ",
  "expires_in": 320,
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJEZW1vdmVyemUiLCJzdWIiOiJ0ZXN0ZXIiLCJhdWQiOiJ0ZXN0IiwiaWF0IjoxNzA4OTM5MTEwLCJleHAiOjE3MDg5NTgzMTAsInBycCI6InJ0In0.w9VJ9PIInZlxRpoMIezXcoRHkTLvkOkAJKreiFbKahI",
  "refresh_token_expires_in": 10080
}


use of login token:
status code: 200
response body:
[{"alternatecode":"","code":"CZ","currency_id":"0000CZK000","hidden":false,"id":"00000CZ000","name":"Česká republika","numcode":"203","objversion":6}]


use of refresh token:
new login and refresh tokens: {
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJEZW1vdmVyemUiLCJzdWIiOiJ0ZXN0ZXIiLCJhdWQiOiJ0ZXN0IiwiZXhwIjoxNzA4OTU4MzE1LCJwcnAiOiJhdCJ9.KasrkJTMKjzAC5RbjvQpcqru6aCXrNwfKBVIevXBDc4",
  "expires_in": 320,
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJEZW1vdmVyemUiLCJzdWIiOiJ0ZXN0ZXIiLCJhdWQiOiJ0ZXN0IiwiaWF0IjoxNzA4OTM5MTE1LCJleHAiOjE3MDg5NTgzMTUsInBycCI6InJ0In0.C2ts75DOPtVJJX_w3c98ZE8Ji4tHg3KFnAWFkh0CFK4",
  "refresh_token_expires_in": 10080
}

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.

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

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.

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

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 agendách Role nebo Skupiny rolí lze na záložce Privilegia nastavit privilegim s názvem Číst položky číselníků v API. Toto privilegium umožní číst všechna data číselníků bez potřeby nastavení práva Zobrazit.

API poskytuje sadu endpointů pro čtení a správu uživatelských práv, rolí a skupin rolí.

Dokumentace

Endpointy vracející statické výčty práv, která lze v systému nastavovat.

• Chráněné objekty:

  GET /api-docs/securityobjects

• Chráněná místa:

  GET /api-docs/securitypoints

• Privilegia:

  GET /api-docs/privileges

Role

Endpointy pro čtení a zápis práv k dané roli:

• Chráněné objekty:

  GET, PUT /securityroles/{id}/securityobjects

• Chráněná místa:

  GET, PUT /securityroles/{id}/securitypoints

• Privilegia:

  GET, PUT /securityroles/{id}/privileges

Endpointy pro správu uživatelů přiřazených dané roli (zobrazení, přidání, odebrání):

• Uživatelé:

  GET, PUT, DELETE /securityroles/{id}/securityusers

Endpointy pro správu skupin rolí přiřazených dané roli (zobrazení, přidání, odebrání):

• Skupiny:

  GET, PUT, DELETE /securityroles/{id}/securitygroups

Skupiny rolí

Endpointy pro čtení a zápis práv k dané skupině rolí:

• Chráněné objekty:

  GET, PUT /securitygroups/{id}/securityobjects

• Chráněná místa:

  GET, PUT /securitygroups/{id}/securitypoints

• Privilegia:

  GET, PUT /securitygroups/{id}/privileges

Endpointy pro správu rolí přiřazených dané skupině rolí (zobrazení, přidání, odebrání):

• Role:

  GET, PUT, DELETE /securitygroups/{id}/securityroles

Uživatelé

Endpointy pro čtení efektivních práv daného uživatele:

• Chráněné objekty:

  GET /securityusers/{id}/securityobjects

• Chráněná místa:

  GET /securityusers/{id}/securitypoints

• Privilegia:

  GET /securityusers/{id}/privileges

Endpointy pro správu rolí přiřazených danému uživateli (zobrazení, přidání, odebrání):

• Role:

  GET, PUT, DELETE /securityusers/{id}/securityroles