Historik
OS2Kitos applikationen (herefter KITOS) består overordnet set af en Angular JS applikation (herefter: UI) der kommunikerer med en backend via en række REST APIer.
Da API-initiativet blev startet primo 2018, blev det besluttet, at man ville udstille de eksisterende REST APIer til andre klienter end UI - såkaldte API klienter.
For at tilgodese disse API klienter, blev der udviklet en Json Web Token baseret autentifikationsmodel (herefter: JWT) , hvormed en bruger kan tilgå KITOS' API. Adgang med JWT giver de samme rettigheder (på brugeniveau), som havde man programmeret sin API klient baseret på cookies (hvilket nogle kommuner allerede har). En midlertidig undtagelse fra denne regel beskrives i “Kun adgang til læseoperationer”.
JWT tokens er den eneste autentifikationsform, der bør anvendes af API klienter, idét man herved kun får adgang til det “officielle” API.
Kun adgang til læseoperationer
Såfremt man anvender APIet som tiltænkt dvs. med JWT, får man kun adgang til operationer, der ikke ændrer på data (se “Kendte problemer”).
Man kan derfor i første omgang ikke ændre på data i KITOS uden om UI.
Konkrete behov for API adgang til ændring af data fremsendes til Kitos Sekretariatet, hvor en eventuel udviklingsopgave vil blive formuleret og prioriteret (se “Hvad kan I forvente af KITOS API fremadrettet?”).
Begreber og tilgange
KITOS' REST APIer er realiseret via to forskellige designs.
Klassiske REST API
De klassiske REST API’er findes under ruterne /api/* og forholdet mellem URI og operationer tilnærmer sig de gængse retningslinjer.
API’erne returnerer DTO objekter der repræsenterer en abstraktion af den bagvedliggende datamodel.
OData (V3) REST API
Under stien /odata/* findes KITOS' OData baserede REST APIer. Udover specialiserede endpoints indeholder de fleste et “root query” endpoint som typisk findes på “collection” URI dvs f.eks.:
/odata/itsystems
Med denne URI i hånden, kan der foretages OData queries på den delmænge af ressourcen, som brugeren har lov til at se i den aktive kontekst (den organisation som man er logget ind i).
Det betyder, at hvis man f.eks. er almindelig bruger i en kommune, så består delmængden af:
Alle IT-systemer, som er lokalt oprettet.
Alle IT-systemer i andre organisationer, som er markeret som “Offentlig”.
Indenfor denne delmængde kan man så anvende standard OData queries til f.eks. at filtrere ($filter), sortere ($orderBy) og begrænse returmængden ($top,$skip).
Swagger dokumentation
Den interaktive Swagger dokumentation for KITOS API findes her: https://kitos.dk/swagger.
Med en JWT i hånden kan de forskellige API endpoints kaldes direkte fra dokumentationen via funktionaliteten “Try it out” som vist nedenfor.
Eksempler på anvendelse
KITOS APIets testgrundlag udvikles løbende og vedligeholdes her: https://github.com/Strongminds/kitos/tree/master/Tests.Integration.Presentation.Web(seneste udviklingsversion) og her: https://github.com/os2kitos/kitos/tree/master/Tests.Integration.Presentation.Web(senest frigivne version).
Her findes eksempler på interaktion med KITOS API med hhv. cookie (forudsætninger for udtræk) og via JWT (via det officielle API).
Kendte problemer
Følgende problemer er identificeret og vil blive løst løbende i forbindelse med videreudviklingen af KITOS.
Sikkerhedsmodellen er ikke implementeret konsekvent
Databeskyttelsen i KITOS gennemtvinges i to skridt.
For det første skal man være en autentificeret bruger - enten ved brug af cookie (fra UI) eller JWT (som API klient).
For det andet, skal man “have lov” (være autoriseret) til at se/ændre på det data man peger ud via APIet.
Den første del - autentifikation - er gennemtvunget konsekvent, mens skridt to - autorisation - ofte fungerer fordi UI kalder endpoints med de rigtige argumenter. Der findes altså endpoints, hvor man kan tilgå lokale data fra andre organisationer selvom man kun er autoriseret til at se data i sin egen kommune. Årsagen hertil findes i, at KITOS ofte realiserer beslutningen om “hvad man må se” i UI, hvorfor APIet “glemmer” at autorisere forespørgslen ned i en konkret organisationskontekst inden data graves frem og sendes tilbage.
Første skridt ift. at løse dette problem blev taget ifm.: KITOSUDV-91 - Getting issue details... STATUS
I denne story blev de grundlæggende regler for adgangsstyring i KITOS klarlagt og gennemtvunget på API-niveau for hhv. IT System anvendelser samt IT Systemer i IT System kataloget.
For at løse de resterende vertikaler er der oprettet følgende story: KITOSUDV-134 - Getting issue details... STATUS
Alternativt vil den konsoliderede rettighedsmodel blive rullet ud ifm. arbejde i de enkelte vertikaler (Projekter, Kontrakter osv.)
OData-API’erne udstiller domæne/database modellen 1-1
Ved tilgang til KITOS API via OData API, vil KITOS aflevere data i den eksakte form, som den er repræsenteret i den bagvedliggende datamodel.
Det skaber en række problemer ift. at begrænse hvad man kan trække ud af en forespørgsel. Man kan f.eks., ved brug af $expand, grave information frem, som man ellers ikke ville være autoriseret til at se. Derudover, vil man ofte få mere tilbage end man “havde lyst til”, hvilket har indflydelse på svartiden. Udover de nævnte udfordringer, vil en ændring i den bagvedliggende model også automatisk påvirke alle klienter (før var det kun UI), og det skaber nogle unødvendige bindinger.
I det fremadrettede arbejde med KITOS, vil der i høj grad være fokus på ikke at aflevere mere data end “nødvendigt”, hvilket både løser rettighedsproblemet og de ydelsesrelaterede udfordringer.
Da en stor del af KITOS UI baserer sig på de faciliteter, der er årsag til ovennævnte problemer, vil de eksisterende OData APIer i første omgang bestå i sin nuværende form.
Endpoints returnerer bredere forspørgsler end man tror
Da KITOS API historisk set kun har haft én kunde (UI) er nogle endpoints hårdere koblet til en konkret use-case end hvad der er hensigtsmæssigt.
Som eksempel kan man tage:
/odata/Organizations(1)/ItSystems
Ved blot at se på ovenstående URI, kunne man fristes til at tro, at man ville få ItSystemerne for organisation '1' tilbage. Det man får tilbage er:
Alle IT Systemer, som man har lov til at se i organisation '1'
Hvis man er bruger i en komme eller global admin, får man også IT Systemer fra andre organisationer som er delt dvs. “Synlighed=Offentlig”
Årsagen hertil findes sandsynligvis i en konkret use case, man har forsøgt løst for UI, men ved at se på URI alene, virker resultatsættet umiddelbart forkert.
I det videre arbejde med KITOS vil vi sikre, at API endpoints undgår implicitte regler, og tydeligt kommunikerer deres intention. I overgangsfasen vil vi, hvor det er muligt, sikre, at swagger dokumentationen beskriver det potentielle indhold af resultatsættet.
Hvad kan i forvente af KITOS API fremadrettet?
For at sikre, at KITOS API udvikler sig i den rigtige retning, vil der fremadrettet blive holdt fokus på:
I samarbejde med brugerne at specificere og udvikle konkrete eksterne API-snit, hvor intentionen fra starten af er tilgang fra en tilstandsløs klient, der ikke forventer data trukket ud efter implicitte regler, der skal understøtte én bestemt klients use case.
At overvåge anvendelsen af det nuværende API, således at vi nemmere kan fokusere indsatsen på de områder der anvendes mest.
At få udrullet den konsoliderede sikkerhedsmodel, således at vi som minimum kun afleverer data jf. brugerens rettigheder.
At versionere nye API endpoints.
Vær med til at præge udviklingen
For at sikre, at KITOS API udvikler sig i den rigtige retning, er det vigtigt, at eventuelle problemer, spørgsmål eller ønsker rettes til KITOS Sekretariatet. I samråd med leverandøren, vil konkrete tiltag herefter blive formuleret, vurderet og prioriteret.