3.7. Zabezpečení

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

Systém podporuje dvě metody zabezpečení přístupu a autentizace:

3.7.1. Autentizace na Portálu NA ČR

Systém CAM je jednou ze služeb tvořících Portál NA ČR. 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á alespoň jednu roli pro CAM, tak může volat požadované funkce.

V případě autentizace pomocí Portálu je každý požadavek směrující na CAM 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.

3.7.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 tajnou hodnotou klíče. Utajená 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: 20190915215620

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 entitu číslo 100:

  • URL: https://portalvyvoj.nacr.cz/cam/entities/100

  • Metoda: GET

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

Řětězec pro podepsání:

HOST                  cesta            X-NDA-Date

portalvyvoj.nacr.czGET/cam/entities/10020190915215620

Výsledek: IT+NIJmiqm2QnB3nW3dqOwCip4z6TBYb9/y9SKv0xTc

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/cam/api/v1/updates?fromTransId=91812cb8-3519-4f78-b0ec-df6e951e2c7c&toTransId=356f9bdc-06a1-49a3-b373-d3ab8d5021d6&page=1&pageSize=10

Je podepisovaný řetězec:

portalvyvoj.nacr.czGET/cam/api/v1/updatesfromTransId=91812cb8-3519-4f78-b0ec-df6e951e2c7c&toTransId=356f9bdc-06a1-49a3-b373-d3ab8d5021d6&page=1&pageSize=1020190915215620