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