

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 sistem login
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"
}