5.1. Zabezpečení

Funkce REST API vyžadují autentizovaného uživatele. Na základě autentizace je provedena autorizace k provedení dané operace.

Jednotlivé implementace digitálního archivu mohou podporovat více metod zabezpečení přístupu a autentizace. Následují dva příklady způsobu zabezpečení přístupu.

5.1.1. Autentizace na Národním archivním portálu

Přístup k digitálnímu archivu zajišťuje Národní archivní portál. Uživatelé Portálu mají přiřazeny role, které určují možnost využívat jednotlivé služby. Pokud se uživatel přihlásí na Portál a má odpovídající roli, tak může volat požadované funkce.

V případě autentizace pomocí Portálu je každý požadavek směrující na digitální archiv, resp. příslušné funkce obohacen o JWT token s informacemi o přihlášeném uživateli.

Specifikace technického řešení zabezpečení Portálu je součástí jeho dokumentace, viz https://frnk.lightcomp.cz/download/nacr/ndais/doc/bezpecnost/portal_jwt.html.

5.1.2. Autentizace pomocí API Key

K autentizaci každého požadavku je možné použít API Key. Jedná se o dvojici identifikátoru klíče a tajné hodnoty klíče. Tajná hodnota slouží pro podepisování požadavků. Každý přijatý požadavek s tímto typem autentizace musí obsahovat potřebné informace ve svých hlavičkách.

API Key je tvořen dvojicí hodnot:

  • identifikátor klíče - UUID identifikující daný klíč

  • hodnota klíče - 40 znaků, které tvoří klíč, znaky jsou v rozsahu [0-9][A-Z][a-z]

Ke každému uživatelskému účtu je možné přiřadit více přístupových api klíčů.

Hlavičky požadavku

Zaslaný požadavek musí mít povinně uvedeny dvě hlavičky:

  • Authorization - hlavička s informacemi o oprávnění

  • X-NDA-Date - čas vzniku požadavku

Hlavička X-NDA-Date

Hodnota obsahuje čas vzniku požadavku. Uvádí se čas UTC.

Formát: yyyymmddHHMMSS

Příklad: 20230915215620

Hodnota vstupuje do výpočtu hodnoty podpisu (viz Způsob výpočtu podpisu požadavku) a čas vzniku požadavku se nesmí příliš odlišovat od přesného času. Maximální povolená odchylka je 2 minuty.

Hlavička Authorization

Hodnota obsahuje typ autentizace a sadu hodnot.

Příklad:

NDA-HMAC-SHA256 KeyId=29ca33ec-46bc-402d-b3bd-8d00d387842d,Signature=IT+NIJmiqm2QnB3nW3dqOwCip4z6TBYb9/y9SKv0xTc

Jako typ autentizace se uvádí: NDA-HMAC-SHA256.

Po typu autentizace za mezerou následují čárkou oddělené hodnoty: KeyId=.... a Signature=.... KeyId=.... je identifikátor daného klíče, tj. jeho UUID. Signature=... je pomocí base64 zakódovaný podpis požadavku.

Způsob výpočtu podpisu požadavku

Podpis je vygenerován podepsáním řetězce funkcí HMAC-SHA256 a zakódováním podpisu pomocí Base64.

Do výpočtu podpisu požadavku vstupuje:

  1. hodnota z hlavičky host (cílový server)

  2. typ HTTP požadavku (GET, POST, …)

  3. relativní část URL požadavku (cesta)

  4. parametry požadavku uváděné v URL

  5. hodnota z hlavičky X-NDA-Date

Části jsou zřetězeny jedna po druhé do řetězce bez oddělovačů. Tento řetězec vstupuje do podepisovací funkce. Pořadí zřetězení je pevně dané.

Jako token:secret pro funkci HMAC-SHA256 slouží hodnota klíče.

Příklad

API Key:

  • KeyId=29ca33ec-46bc-402d-b3bd-8d00d387842d

  • hodnota: Pr3fxFN4dB5kMtqdRUzj5lHfJS61eATb5wCqUveb

Dotaz na další změněné balíčky:

  • URL: https://portalvyvoj.nacr.cz/da/updates

  • Metoda: GET

  • Čas položení dotazu: 2023-09-15 21:56:20

Řětězec pro podepsání:

HOST                  cesta            X-NDA-Date

portalvyvoj.nacr.czGET/da/updates20230915215620

Výsledek: OPpkPjL19zbGVzN3UOV9ul1TTau5YxGmXbpMzv1Yv5Q

Příklad 2

Dotaz obsahující parametry se podepisuje tak, že se tyto přidávají do podepisovaného řetězce bez oddělovače.

Pro dotaz metodou GET na URL:

https://portalvyvoj.nacr.cz/da/updates-from?pageSize=100&nextQuery=352220190915215620

Je podepisovaný řetězec:

portalvyvoj.nacr.czGET/cam/api/v1/da/updates-frompageSize=100&nextQuery=352220190915215620