From 04287dd82ffc09609dfa4705341ee87e29a43cbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kjetil=20R=C3=B8se=20H=C3=B8ybr=C3=A5ten?= Date: Wed, 26 Aug 2026 07:33:42 +0200 Subject: [PATCH] Krav for forvaltning av tilgangskatalogen gjennom API (BRU-TIL-KAT-001/002) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tilgangskatalogen forvaltes i dag bare av databaseforvaltningen. Kravene gir den et API med to rettighetsnivåer: utviklere hos Sikt kan opprette, endre og ta en tilgang ut av bruk, mens en egen rettighet gir rett til å oppdatere beskrivelsen — og ingenting annet. Skillet er hensikten. Dokumentasjonen av en tilgang eldes raskest og skrives best av dem som kan fagområdet, mens ingen får eller mister tilgang av at teksten endres. Avgrensningen til beskrivelsen er derfor formulert som et håndhevingskrav: et forsøk på å endre noe annet skal avvises i API-et og i datalaget, uansett inngang, også når det følger med i den samme forespørselen som en gyldig beskrivelsesendring. Kravene omfatter også en listespørring over hele katalogen, paginert og forutsigbart sortert. Ingen av dagens innganger viser katalogen i sin helhet — alle listene er avledet av tildelinger — så en tilgang uten tildelinger er i dag usynlig i løsningen. Begge nivåene trenger den listen, dokumentasjonsnivået mest, siden det er de udokumenterte tilgangene arbeidet handler om. Designnotatet peker på de to hullene kravene forutsetter tettet: listespørringen, og en markør for at en tilgang er tatt ut av bruk — katalogen har i dag ingen livsløpstilstand, og sletting er utelukket fordi tildelinger og tak refererer koden. --- .../forvalte_tilgangskatalogen.design.md | 114 +++++++++++++++ .../forvalte_tilgangskatalogen.feature | 131 ++++++++++++++++++ .../oppdatere_tilgangsbeskrivelser.feature | 120 ++++++++++++++++ 3 files changed, 365 insertions(+) create mode 100644 krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.design.md create mode 100644 krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.feature create mode 100644 krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/oppdatere_tilgangsbeskrivelser.feature diff --git a/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.design.md b/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.design.md new file mode 100644 index 0000000..836716e --- /dev/null +++ b/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.design.md @@ -0,0 +1,114 @@ +# Designnotat: Forvalte tilgangskatalogen + +**Relaterte features:** +[`forvalte_tilgangskatalogen.feature`](./forvalte_tilgangskatalogen.feature) (BRU-TIL-KAT-001) og +[`oppdatere_tilgangsbeskrivelser.feature`](./oppdatere_tilgangsbeskrivelser.feature) +(BRU-TIL-KAT-002). + +Kravene er besluttet: tilgangskatalogen skal kunne forvaltes gjennom API, med to rettighetsnivåer. +Notatet forklarer hvorfor skillet går der det går, hva som må håndheves hvor, og hvilke to hull i +dagens modell kravene forutsetter blir tettet. + +## Hva katalogen er + +Katalogen er listen over tilgangene som finnes: en kode som identifiserer hver tilgang, og en +beskrivelse av hva den gir. Den er referansepunktet for resten av tilgangsstyringen — en tildeling, +et delegeringstak og et nekt navngir alle en tilgang fra katalogen. + +To egenskaper former kravene: + +- **En rad i katalogen gir ingen noe.** Å opprette en tilgang er å innføre et begrep, ikke å dele + ut noe. Først en tildeling gjør den til en tilgang noen har. Det er grunnen til at katalogen kan + få en skriveflate uten at flaten i seg selv er en tilgangsutvidelse. +- **Koden er identiteten.** Alt annet peker på koden, så en kode som endres er en referanse som + brytes. Koden settes ved opprettelse og står. + +## Skillet: begrepet og forklaringen + +Kravene deler katalogen i to på tvers av rader, ikke på tvers av tilganger: + +| Nivå | Hva rettigheten omfatter | Hvem | +|------|--------------------------|------| +| Forvaltning | Opprette en tilgang, endre den, ta den ut av bruk | Utviklere hos Sikt | +| Dokumentasjon | Oppdatere beskrivelsen — og ingenting annet | Bidragsytere til dokumentasjonen | + +Begrunnelsen for det andre nivået er at dokumentasjonen av en tilgang er den delen som eldes +raskest og som færrest har forutsetning for å skrive. Den som kan fagområdet vet hva en tilgang +faktisk gir; den som forvalter modellen vet hva raden gjør. Uten et eget nivå må all +dokumentasjonsforbedring gå gjennom dem som kan endre modellen, og da blir den ikke gjort. + +Risikoen ved å utvide kretsen er lav, og det er verdt å si hvorfor presist: **en beskrivelse er +ikke lest av autorisasjonen.** Ingen får eller mister tilgang av at teksten endres, ingen tildeling +berøres, og ingen annen del av modellen peker på beskrivelsen. Det verste utfallet er en misvisende +forklaring — som er en dokumentasjonsfeil, ikke en sikkerhetsfeil. + +## Kolonneskopet er et håndhevingskrav + +Det viktigste å ta med videre fra dette notatet: at dokumentasjonsrettigheten bare omfatter +beskrivelsen er et krav til **håndhevingen**, ikke til hvilke felter en flate viser. + +En flate som skjuler kodefeltet, over et API som tar imot hele katalograden, oppfyller ikke kravet. +Da er avgrensningen bare en presentasjon, og enhver klient som snakker med API-et direkte står +utenfor den. Kravet er at forsøket avvises der regelen bor — i API-et og i datalaget — uansett +hvilken inngang det kommer fra, og også når det følger med i den samme forespørselen som en gyldig +beskrivelsesendring. Featuren har egne scenarioer for begge formene, fordi det er nettopp de to som +skiller et håndhevet kolonneskop fra et presentert et. + +Praktisk konsekvens for utformingen: dokumentasjonsnivået bør ha sin **egen operasjon** som bare +tar imot en kode og en beskrivelse, framfor å dele en generell endringsoperasjon med +forvaltningsnivået og filtrere på rettighet inne i den. Da er kolonneskopet en egenskap ved +grensesnittet i stedet for en regel noen må huske å håndheve. + +## Hullet kravene forutsetter tettet, nr. 1: katalogen kan ikke listes + +Ingen av dagens innganger til katalogen viser den i sin helhet. De listene som finnes er avledet av +noe annet — tilgangene en applikasjon har, tilgangene jeg selv har, tilgangene jeg har rettighet +til å tildele. En tilgang som ennå ikke er tildelt noen finnes dermed i modellen, men er usynlig i +løsningen. + +Det er et hull for begge nivåene. Forvalteren kan ikke se hva katalogen inneholder før hun +oppretter noe nytt, og den som skal dokumentere kan ikke finne fram til de tilgangene som mangler +en beskrivelse — som er nøyaktig dem arbeidet handler om. Kravet er derfor en egen listespørring +over hele katalogen, paginert og forutsigbart sortert, lesbar for begge nivåene. + +Paginering er tatt med i kravet framfor å overlates til utformingen, fordi katalogen er en liste +som vokser og som ingen naturlig avgrenser: den har verken organisasjon eller miljø å filtrere på. + +## Hullet kravene forutsetter tettet, nr. 2: en tilgang kan ikke tas ut av bruk + +Katalogen har i dag ingen livsløpsmarkør. En rad består av kode, beskrivelse og sporing av hvem som +opprettet og endret den — det finnes ingen gyldighetsperiode og ingen «utgått»-tilstand, slik de +temporale tabellene ellers i modellen har. + +Å slette raden er ikke et alternativ: tildelinger, delegeringstak og nekt refererer koden, og +historikken skal bestå. «Ta ut av bruk» i kravet forutsetter derfor en liten modellutvidelse, og +semantikken bør være den samme som ellers: raden blir stående, den merkes som noe som ikke skal tas +i bruk på nytt, og det som allerede er tildelt berøres ikke av merkingen alene. Hvilken form +markøren skal ha — en gyldighetsperiode på linje med de temporale tabellene, eller et enklere flagg +— er en modellbeslutning som hører sammen med denne leveransen. + +## Hvorfor et API her, når andre deler av modellen forvaltes i kildekoden + +Flere av mekanismene rundt katalogen forvaltes bevisst gjennom migreringer, uten flate. Skillet +følger konsekvensen av en endring, ikke hvor krevende den er å bygge: + +- Å **åpne data** eller å legge noe i **gulvet** endrer hvem som kan se hvilke data, uten at noen + er tildelt noe. Der er fravær av en skriveflate en egenskap. +- Å **innføre en tilgang i katalogen** endrer ingens tilgang. Den blir først virksom gjennom en + tildeling, som har sine egne rettigheter og sin egen sporing. + +Katalogen er dessuten den mekanismen som har et løpende dokumentasjonsbehov, og det behovet kan +ikke dekkes av migreringer uten å gjøre hver tekstrettelse til en kodeendring. + +## Åpne designspørsmål + +- [ ] Skal dokumentasjonsrettigheten kunne avgrenses til et navnerom eller et fagområde, eller + gjelder den hele katalogen? +- [ ] Skal en beskrivelsesendring kunne foreslås og godkjennes, eller er rettigheten i seg selv + godkjenningen? Sporingen viser uansett hvem som endret hva og når. +- [ ] Skal implikasjoner mellom tilganger — hvilke tilganger en tilgang omfatter — også kunne + forvaltes gjennom API-et? Kravene her dekker tilgangene selv, ikke hvordan de henger sammen, + og implikasjoner er den delen som faktisk endrer rekkevidde. +- [ ] Hvilken form skal markøren for «ute av bruk» ha, og skal den hindre nye tildelinger av + tilgangen eller bare varsle om dem? +- [ ] Skal listespørringen kunne filtrere på «mangler beskrivelse», eller er det en klientoppgave? diff --git a/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.feature b/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.feature new file mode 100644 index 0000000..2045f0e --- /dev/null +++ b/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/forvalte_tilgangskatalogen.feature @@ -0,0 +1,131 @@ +# language: no +@BRU-TIL-KAT-001 @must @planned +Egenskap: Forvalte tilgangskatalogen gjennom API + Som utvikler hos Sikt + ønsker jeg å opprette, endre og ta ut av bruk tilganger i tilgangskatalogen gjennom API + slik at katalogen kan forvaltes som en del av løsningen, og ikke bare direkte i databasen. + + Tilgangskatalogen er listen over tilgangene som finnes: koden hver av dem identifiseres ved, + og beskrivelsen av hva den gir. Alt annet i tilgangsstyringen peker på den — en tildeling, et + delegeringstak og et nekt navngir en tilgang fra katalogen — så katalogen er både den mest + leste og den mest inngripende listen i modellen. En ny tilgang der er ikke i seg selv en + tilgang noen har fått; den er et begrep resten av modellen kan referere til. + + Katalogen forvaltes i dag av databaseforvaltningen. Denne egenskapen gir den et API med to + nivåer: utviklere hos Sikt kan opprette, endre og ta en tilgang ut av bruk, mens det finnes en + egen rettighet for dem som bare skal skrive beskrivelser, jf. BRU-TIL-KAT-002. Skillet er + hensikten med kravet: dokumentasjonen av en tilgang bør kunne forbedres av dem som kan + fagområdet, uten at de samtidig kan endre hva tilgangen er. + + # ÅPNE SPØRSMÅL: + # - Skal implikasjoner mellom tilganger og navnerom for tilganger også forvaltes gjennom + # API-et, eller forblir de en beslutning i kildekoden? Denne egenskapen dekker tilgangene + # selv, ikke hvordan de henger sammen. + # - Skal listingen kunne avgrenses per navnerom, eller er hele katalogen alltid ett svar? + + Bakgrunn: + Gitt jeg er innlogget i løsningen + + Regel: Hele tilgangskatalogen kan listes + + # Behovet som mangler i dag: ingen av inngangene til katalogen viser den i sin helhet. De + # eksisterende listene er avledet av noe annet — tilgangene en applikasjon har, tilgangene + # jeg selv har, tilgangene jeg kan tildele — og en tilgang uten en eneste tildeling er + # dermed usynlig i løsningen, selv om den finnes. Både den som forvalter katalogen og den + # som dokumenterer den trenger å se den som en liste. + + Scenario: Liste hele katalogen + Når jeg åpner tilgangskatalogen + Så ser jeg alle tilgangene som finnes + Og hvert innslag viser tilgangskoden og beskrivelsen + + Scenario: Tilganger uten tildelinger er med i listen + Gitt en tilgang finnes i katalogen uten å være tildelt noen + Når jeg åpner tilgangskatalogen + Så er tilgangen med i listen + + Scenario: Listen er paginert + Gitt katalogen har flere tilganger enn det som vises om gangen + Når jeg åpner tilgangskatalogen + Så får jeg en avgrenset mengde innslag om gangen + Og jeg kan hente de neste innslagene + + Scenario: Listen er sortert forutsigbart + Når jeg åpner tilgangskatalogen + Så er listen sortert etter tilgangskode i stigende rekkefølge + + Scenario: Listen er lesbar for alle som skal forvalte eller dokumentere katalogen + Gitt jeg har rettighet til å oppdatere beskrivelser i katalogen + Når jeg åpner tilgangskatalogen + Så ser jeg alle tilgangene som finnes + + Scenario: Det fremgår hvilke tilganger som er tatt ut av bruk + Gitt en tilgang er tatt ut av bruk + Når jeg åpner tilgangskatalogen + Så fremgår det at tilgangen ikke lenger skal tas i bruk + Og jeg kan velge å se bare tilgangene som er i bruk + + Regel: Bare utviklere hos Sikt kan opprette, endre eller ta ut av bruk en tilgang + + Scenario: Utvikler oppretter en ny tilgang + Gitt jeg har utviklerrettighet for tilgangskatalogen + Når jeg oppretter en tilgang med en kode og en beskrivelse + Så finnes tilgangen i katalogen + Og den kan tildeles på lik linje med de øvrige tilgangene + + Scenario: Utvikler endrer en tilgang + Gitt jeg har utviklerrettighet for tilgangskatalogen + Og en tilgang finnes i katalogen + Når jeg endrer beskrivelsen av tilgangen + Så er den nye beskrivelsen lagret + + Scenario: Utvikler tar en tilgang ut av bruk + Gitt jeg har utviklerrettighet for tilgangskatalogen + Og en tilgang finnes i katalogen + Når jeg tar tilgangen ut av bruk + Så fremgår det i katalogen at tilgangen ikke lenger skal tas i bruk + Og tilgangen er ikke slettet + + Scenario: Uten utviklerrettighet avvises opprettelse + Gitt jeg ikke har utviklerrettighet for tilgangskatalogen + Når jeg forsøker å opprette en tilgang + Så avvises endringen + Og det fremgår hvilken rettighet som kreves + + Scenario: Uten utviklerrettighet vises ingen handlinger for å endre katalogen + Gitt jeg ikke har utviklerrettighet for tilgangskatalogen + Når jeg åpner tilgangskatalogen + Så ser jeg listen over tilganger + Men jeg ser ingen handling for å opprette eller ta en tilgang ut av bruk + + Regel: Koden identifiserer tilgangen og settes én gang + + Scenario: Koden kan ikke endres etter opprettelse + Gitt en tilgang finnes i katalogen + Når jeg forsøker å endre koden til tilgangen + Så avvises endringen + Og det fremgår at koden identifiserer tilgangen og ikke kan endres + + Scenario: Opprettelse avvises når koden allerede er i bruk + Gitt en tilgang med en gitt kode finnes i katalogen + Når jeg forsøker å opprette en ny tilgang med den samme koden + Så avvises opprettelsen + Og det fremgår at koden allerede er i bruk + + Scenario: En tilgang som er i bruk kan ikke slettes + Gitt en tilgang er tildelt noen + Når jeg forsøker å fjerne tilgangen fra katalogen + Så avvises fjerningen + Og det fremgår at tilgangen kan tas ut av bruk i stedet + + Regel: Endringer i katalogen er sporbare + + Scenario: Se hvem som opprettet en tilgang + Gitt en tilgang finnes i katalogen + Når jeg åpner tilgangen + Så ser jeg tidspunktet den ble opprettet og hvem som opprettet den + + Scenario: Se siste endring av en tilgang + Gitt en tilgang i katalogen er endret + Når jeg åpner tilgangen + Så ser jeg tidspunktet for siste endring og hvem som gjorde den diff --git a/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/oppdatere_tilgangsbeskrivelser.feature b/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/oppdatere_tilgangsbeskrivelser.feature new file mode 100644 index 0000000..86ac485 --- /dev/null +++ b/krav/07 Brukeradministrasjon og tilgangsstyring/11 Tilgangsstyring/04 Tilgangskatalogen/oppdatere_tilgangsbeskrivelser.feature @@ -0,0 +1,120 @@ +# language: no +@BRU-TIL-KAT-002 @must @planned +Egenskap: Oppdatere beskrivelsen av en tilgang + Som bidragsyter til dokumentasjonen av tilgangskatalogen + ønsker jeg å oppdatere beskrivelsen av en tilgang + slik at det står forklart hva tilgangen faktisk gir, uten at jeg kan endre hva tilgangen er. + + Beskrivelsen er det eneste i katalogen som er ren dokumentasjon. Koden identifiserer tilgangen, + og alt annet i tilgangsstyringen peker på den; beskrivelsen forklarer den. Derfor er det den + ene delen av katalogen som kan forvaltes av flere enn dem som forvalter selve modellen — den + som kan fagområdet skal kunne forbedre forklaringen uten å kunne røre begrepet. + + Rettigheten gir derfor tilgang til ett felt, ikke til katalogen. Avgrensningen er et krav til + håndhevingen, ikke bare til hvordan flaten ser ut: et forsøk på å endre noe annet skal avvises + uansett hvilken vei det kommer inn, også når det følger med i den samme forespørselen som en + gyldig beskrivelsesendring. + + Å endre en beskrivelse endrer ingenting for dem som har tilgangen. Det er nettopp derfor + rettigheten kan være videre enn utviklerrettigheten i BRU-TIL-KAT-001. + + # ÅPNE SPØRSMÅL: + # - Skal rettigheten kunne avgrenses til et fagområde eller et navnerom, eller gjelder den + # hele katalogen? + # - Skal en beskrivelsesendring kunne foreslås av flere og godkjennes av noen, eller er + # rettigheten i seg selv godkjenningen? + + Bakgrunn: + Gitt jeg er innlogget i løsningen + Og jeg har rettighet til å oppdatere beskrivelser i tilgangskatalogen + + Regel: Rettigheten gir rett til å oppdatere beskrivelsen + + Scenario: Oppdatere beskrivelsen av en tilgang + Gitt en tilgang finnes i katalogen + Når jeg oppdaterer beskrivelsen av tilgangen + Så er den nye beskrivelsen lagret + Og den vises der tilgangen er nevnt + + Scenario: Beskrivelsen kan tømmes + Gitt en tilgang har en beskrivelse + Når jeg fjerner beskrivelsen + Så står tilgangen uten beskrivelse + Og tilgangen finnes fortsatt i katalogen + + Scenario: Finne tilgangen som skal dokumenteres + Gitt katalogen har tilganger uten beskrivelse + Når jeg åpner tilgangskatalogen + Så ser jeg alle tilgangene som finnes, også de uten tildelinger + Og jeg kan se hvilke som mangler beskrivelse + + Scenario: Endringen er sporbar + Gitt jeg har oppdatert beskrivelsen av en tilgang + Når jeg åpner tilgangen + Så ser jeg tidspunktet for endringen og hvem som gjorde den + + Regel: Rettigheten gir ikke rett til noe annet enn beskrivelsen + + # Avgrensningen er et håndhevingskrav. Den skal ligge i API-et og i datalaget, ikke bare i + # hvilke felter en flate viser: en klient som sender inn mer enn en beskrivelse skal få det + # avvist, uansett hvilken inngang den bruker. + + Scenario: Forsøk på å endre tilgangskoden avvises + Gitt en tilgang finnes i katalogen + Når jeg forsøker å endre koden til tilgangen + Så avvises endringen + Og det fremgår at rettigheten bare omfatter beskrivelsen + + Scenario: Forsøk på å opprette en tilgang avvises + Når jeg forsøker å opprette en ny tilgang i katalogen + Så avvises opprettelsen + Og det fremgår at rettigheten bare omfatter beskrivelsen + + Scenario: Forsøk på å ta en tilgang ut av bruk avvises + Gitt en tilgang finnes i katalogen + Når jeg forsøker å ta tilgangen ut av bruk + Så avvises endringen + + Scenario: Forsøk på å endre hvilke tilganger en tilgang omfatter avvises + Gitt en tilgang omfatter andre tilganger + Når jeg forsøker å endre hvilke tilganger den omfatter + Så avvises endringen + + Scenario: Forsøk på å endre hvilket navnerom en tilgang hører til avvises + Gitt en tilgang hører til et navnerom + Når jeg forsøker å flytte tilgangen til et annet navnerom + Så avvises endringen + + Scenario: Forsøk på å tildele eller fjerne en tilgang avvises + Gitt en tilgang finnes i katalogen + Når jeg forsøker å tildele tilgangen til noen + Så avvises tildelingen + Og det fremgår at rettigheten ikke omfatter tildeling + + Scenario: En forespørsel som endrer mer enn beskrivelsen avvises i sin helhet + Gitt en tilgang finnes i katalogen + Når jeg sender inn en endring som både oppdaterer beskrivelsen og noe annet + Så avvises hele endringen + Og beskrivelsen er uendret + + Scenario: Avgrensningen gjelder uansett inngang + Gitt jeg bruker API-et direkte i stedet for en flate + Når jeg forsøker å endre noe annet enn beskrivelsen + Så avvises endringen på samme måte + + Regel: En beskrivelsesendring påvirker ingen tilganger + + Scenario: Tildelinger er uendret etter en beskrivelsesendring + Gitt en tilgang er tildelt flere applikasjoner og brukere + Når jeg oppdaterer beskrivelsen av tilgangen + Så har de samme applikasjonene og brukerne den samme tilgangen som før + + Scenario: Ingen mister eller får tilgang til data + Gitt en bruker arbeider med en tilgang + Når beskrivelsen av tilgangen oppdateres + Så er det brukeren kan gjøre uendret + + Scenario: Andre deler av tilgangsmodellen er uberørt + Gitt en tilgang er nevnt i et delegeringstak og i et nekt + Når jeg oppdaterer beskrivelsen av tilgangen + Så er både delegeringstaket og nektet uendret