Model integracije
Pristup↵
Poslovnim API funkcijama se pristupa preko adrese https://gjls.trezor.gov.rs
. Svaki poziv ima prefiks api
i opciono verziju u putanji vX.Y
:
/api/test
Poziva poslednju verziju funkcije./api/v1.1/test
Poziva verziju 1.1 funkcije.
Napomena
U svrhu implementacije i lakšeg testiranja eksternih integrativnih servisa, podignuto je i stavljeno u funkciju javno testno okruženje KIBJLS servisa, dostupnih na adresi https://gjlstest.trezor.gov.rs
. Servisi javnog testnog okruženja su funkcionalno identični produkcionim servisima (što ne uključuje korisničke podatke) i potrebno ih je koristiti u ranim fazama integracije, obzirom da je masovan unos testnih podataka na produkcione servise zabranjen.
Zaglavlje rezultata svakog poziva sadrži atribut api-supported-versions
koji lista sve raspoložive verzije funkcije. Poslednja verzija API-ja je dodatno označena sufiksom current
, npr. 1.1-current
.
Neaktuelne verzije API-ja zastarevaju (eng: deprecation) i biće uklonjene. Uklanjanje se neće vršiti ranije od 3 meseca od trenutka raspoloživosti nove verzije.
API koristi JSON format za razmenu podatka i osim ako je drugačije napomenuto, ContentType za svaki request je application/json
.
Upozorenje
Postoji maksimalna frekvencija upotrebe svake konkretne funkcije KIBJLS servisa (eng: Rate Limiter).
Na primer, neke funkcije je moguće koristiti maksimalno jednom u sekundi.
Model povratnog paketa↵
Sve API funkcije servisa KIBJLS imaju standardizovanu formu povratnog paketa (payload). Povratni paket sadrži sledeći set polja:
- status - statusni kod i opis greške - u slučaju neuspelog poziva, inače
Success
- payload - poslovni podaci konkretnog endpoint-a kao rezultat izvršenja funkcije
- additionalInformation - dodatni poslovni podaci, ukoliko je neophodno
Primer uspešnog povratnog paketa
{ "status": { "message": "Success", "code": "Success" }, "payload": { "creationTime": "2022-05-07T18:58:04.193788+02:00", "accessToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...", "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...", "applicationStateId": 1 }, "additionalInformation": null }
Primer povratnog paketa sa greškom
{ "status": { "message": "Failed to generate access token with submitted credentials", "code": "GenerateAccessToken" }, "payload": null, "additionalInformation": null }
Autentikacija i autorizacija↵
Pristup zaštićenim pristupnim tačkama servisa zahteva autentikaciju. Pristup konkretnim funkcionalnostima zahteva odgovarajuća aplikativna prava (autorizaciju).
KIBJLS koristi JWT standard za autentikaciju i autorizaciju.
Pristup se ostvaruje preuzimanjem access tokena (accessToken
) pozivom /api/login javne pristupne tačke servisa KIBJLS https://gjls.trezor.gov.rs
. Poziv zaštićenih pristupnih tačaka zahteva da u zaglavlju (eng: Headers) postoji Authorization atribut sa vrednošću Bearer <accessToken>
.
Poruke o greškama koje se javljaju kod pristupa API funkcijama usled neodgovarajuće autentikacije ili autorizacije su:
Code | Message | Opis |
---|---|---|
401 |
Unauthorized |
Korisnik nije autentifikovan |
403 |
Forbidden |
Korisnik nema odgovarajuće ovlašćenje za korišćenje funkcionalnosti |
Workflow autentikacije↵
Kako bi se krajnjem korisniku obezbedio nesmetan rad na servisu, kao i smanjio nepotreban broj poziva ka servisu, JWT pristup obezbeđuje mehanizam kontinualnog pristupa zaštićenim funkcijama upotrebom refresh workflow-a.
Inicijalnim pozivom pozivom login javne pristupne tačke servisa, sadržaj povratnog paketa uspešnog zahteva će sadržati polja:
- accessToken - pristupni token kratkoročne validnosti - 20 minuta,
- refreshToken - dugoročni token
Pristupni access token omogućava neposredno pozivanje zaštićenih funkcija u toku trajanja access sesije (20 minuta). Nakon isteka sesije, pozivi zaštićenih funkcija servisa sa istim access tokenom će rezultovati greškom 401 - Unauthorized
.
Kako bi se izbegla potreba za ponovnim slanjem korisničkih kredencijala, postavljanjem Authorization atributa na vrednost Bearer <refreshToken>
i pozivom refresh funkcije, omogućeno je pribavljanje novog aktivnog access tokena i time nastavljen neometan rad krajnjeg korisnika u trajanju nove access sesije.
Rezime workflow-a
- Pribavljanje access i refresh tokena pozivom login funkcije servisa sa korisničkim kredencijalima,
- Rad sa zaštićenim funkcijama servisa upotrebom access tokena u trajanju kratkoročne sesije,
- Nakon isteka kratkoročne sesije, poziv zaštićene funkcije rezultuje greškom
401 - Unauthorized
, - Pribavljanje validnog access tokena pozivom refresh funkcije servisa upotrebom refresh tokena,
- Nastavak rada sa zaštićenim funkcijama servisa upotrebom novog validnog access tokena
Napomena
Implementacijom refresh workflow-a, integrativni korisnik u opštem slučaju ima potrebu da se prijavi na sistem samo jednom kako bi pribavio dugoročni token. Obzirom na performantnu taksativnost asimetričnih algoritama zaštite, svaka neprimerena upotreba refresh workflow-a (npr. pozivanje login pre svakog poziva nekog od funkcionalnih endpointa) će rezultovati blokadom integrativnog korisničkog naloga.
KIBJLS JWT token↵
Pored standardnih sigurnosnih elemenata, JWT token servisa KIBJLS sadrži i određeni broj polja koja se odnose na poslovnu logiku samog servisa.
unique_name
- jedinstveno korisničko ime u sistemlogin
user_id
- identifikator korisnika,organization_id
- identifikator organizacije korisnika,budget_user_id
- JBKJS korisnika,treasury
- šifra trezora,execution_account
- račun izvršenja trezora,treasury_branch
- šifra filijale trezora
Sekcija lobe_claims
sadrži niz aplikativnih prava koja odgovaraju poslovnim funkcionalnostima servisa, a kojima korisnik ima omogućen pristup.
Nazivi aplikativnih prava se formiraju prema pravilu resurs_akcija, pri čemu resurs označava funkcionalnu celinu (aproprijacija, kvota, itd.), dok akcija predstavlja omogućenu radnju nad datim resursom (čitanje, izmena, odobravanje itd.)
Primer JWT tokena
{ "unique_name": "admin", "user_id": "5", "organization_id": "2", "budget_user_id": "10523", "treasury": "601", "execution_account": "840000000000162021", "treasury_branch": "", "lobe_claims": [ "Claim_Local_User_Create", "Claim_Local_User_Review", "Claim_Local_User_Revoke", "Claim_User_Group_Create", "Claim_Registration_Edit" ], "nbf": 1678539332, "exp": 1678575331, "iat": 1678539332, "iss": "TreasurySecurityIssuer", "aud": "TreasurySecurityAudience" }