Dette dokument beskriver NSP Security API til brugerautentificering og autorisering på NSP.

Det første afsnit beskriver den arkitekturmæssige motivation for indførelsen af NSP Security API.

Dernæst vises hvordan NSP Security API rent praktisk indføres i en NSP komponent med konkrete eksempler på anvendelse. Denne sektion er især relevant for udviklere, der skal bruge NSP Security API i forbindelse med en konkret opgave.

Dette afsnit er delt op i følgende underafsnit:

1. Dependency management: Viser, hvordan Maven dependency management samt deployment descriptors til NSP base Docker image anvendes til at få de nødvendige afhængigheder på plads for anvendelse af NSP Security API.
2. Brugermodellering og mapning: TODO
3. Logning og fejlhåndtering

Arkitekturoverblik og motivation for NSP Security API

Målet med security API er at gøre det let for services at tjekke sikkerhed - både DGWS, IDWS og eventuelle sikkerhedsprotokoller i fremtiden.

Dette skal gøres på en måde, så det der tilbydes de anvendende services/komponenter de nødvendige abstraktioner/termer og tilbyde en passende mapning fra de konkrete sikkerhedsprotokoller.

Termerne spiller også ind i måden, som SDS ønsker at modellere brugere/aktører i forhold til de user stories som beskriver opførsel og komponenter. Det er op til komponenterne selv at modellere de aktører, som de skal servicere, så security API opererer på et lavere niveau, hvor denne mapning giver mening.

Modellen i Security API

Udtrykker kun den information, som findes i sikkerhedsbilletten - og ikke andet.

Stiller informationen til rådighed for komponenten gennnem SecurityContext hvorfra, der er adgang til alle information bl.a. ActingUser (den bruger, der trykker på knapperne), PrincipalUser (den bruger, der er ansvarlig for handlingen), Organisation, Message og Ticket.

Der anvendes Optionals rundt omkring.

Modellen er mere generel end de nuværende sikkerhedsprotokoller og udfaldrummet for de aktuelle sikkerhedsbilletter giver anledning til.

F.eks. finder der i praksis i dag ikke billet, hvor en sundhedsperson kan arbejde på vegne af en anden sundhedsperson (dvs. både ActingUser og PrincipalUser er tilstede). Dette kan udtrykkes i Security API'ets model og det er meget tænkeligt, at der kommer support for dette i fremtiden (når XUA kommer på banen).

Ansvarsfordeling mellem komponent og Security API

Som det blev beskrevet før, så er Security APIs model meget generel og kan udtrykke ting, som der i øjeblikket ikke kan forekomme i praksis.

Dette betyder dog, at det kan være ligeså vigtigt, at en komponent validerer både attributter der findes, og dem der ikke findes, for at mappe korrekt til de relevante aktører.

I eksemplet fra før, hvor en sundhedsfaglig, der handler på vegne af en anden sundhedsfaglig: Dette kan udtrykkes i Security API, men der findes ikke (i dag) en sikkerhedsbillet, der kan bærer denne information.

Komponenten bør dog forholde sig til, hvad der er muligt i Security API'et model, og ikke kun på, hvad der er muligt i de aktuelle sikkerhedsbilletter.

Eksempler på aktører. Denne liste er ikke udtømmende, og det er vigtigt at overveje, hvad der skal gælde i de enkelte komponenter.:

TODO: Dokumentationskrav: 1) Brugerhistorier med komplet liste af brugertyper og beskrivelse af dem, så de giver mening for anvenderne 2) De enkelte brugertyper og de regler, der omgiver dem (hvad tjekkes i security api) skal beksrives i design og arkitekturguide

Eksemplerne nedenfor skal beriges med, hvad der IKKE må være tilstede (f.eks. for borger må der ikke være en organisation). Kig på de enkelte attributter i security api f.eks. som en tabel eller ligenden, så man kan se strukturen og de regler der gælder på de forskellige niveauer.

Komponenten skal modellere disse aktører på en eller anden måde (f.eks nedarvning eller en simpel enumeration, der lister typerne).

Komponenten skal selv mappe fra security context til sin egen aktørmodel:

• Er der en billet og er den valid?
• I forhold til de enkelte aktører skal man forholde sig til sikkerhedsmodellen og tjekke, at alle betingelser er opfyldt. Det kan f.eks. være vigtigt at tjekke, at Principal User ikke er sat, hvis man gerne vil matche en borger der handler på egne vegne.
• Det er vigtig at lave en korrekt og gensidig udelukkende match mellem SecurityContext og aktør, så man ikke ved et uheld ender op med en forkert aktørtype. Det er nok særlig relevant i "på vegne af" tilfældet, hvor eksistensen af en PrincipalUser er afgørende.

Hvad med alt det, der ikke er i sikkerhedsbilletten?

I mange komponenter er forretningslogikken og aktør-modelleringen afhængig af oplysninger, der ikke er en del af Security API. Eksempler kan være:

• HSUID Header: Mulighed for at udtrykke på vegne af mellem sundhedspersoner
• Særlige 'admin' URL'er: Mulighed for at kalde som en særlig kraftig brugertype

I aktørmodellen må komponenten gerne tage disse oplysninger med i aktørmodelleringen.

Det skal dog være tydligt, hvilke oplysninger, der stammer hvorfra (hvilke, der er en del af de STS-validerede oplysninger og hvilke der er kontekst-oplysninger, der essentielt bare er en udvidelse af det af komponenten udbudte API med ekstra kontekst).

Forslag til forbedringer

• Javadoc bliver i dag ikke loadet korrekt af IDE - af en eller anden grund. Så hvis man vil se Javadoc, så skal man kigge i SVN.
• Modelleringen af aktører i komponenernet skal være eksplicit i RFC'er (både omlægningopgaver og ændringsønsker). Det har stor impact på en komponent, hvilke aktører man har, og hvordan de modelleres, og forretningen bør være en del af denne beslutning. Det skal ikke være et "biprodukt af en teknisk opgave".
• KIT foreslår, at man laver eksempler (enten i pseudokode på denne side eller på en anden måde) med modellering og validering af "gængse aktørtyper". Selvom Security API ikke vil begrænse komponenten i forhold til dette, så kunne det være en stor hjælp og afgørende i forhold til ensartethed henover komponenter at have eksempler på "gængse aktørtyper" og hvordan man mapper/validerer disse korrekt. Det er f.eks. "borger, der handler på vegne af sig selv" eller "borger, der handler på vegne af anden borger". Der er højst sandsynligt ikke den store forskel på, hvordan komponenter vil mappe/validere disse.

Anvendelse af NSP Security API i NSP komponenter

For at anvende NSP Security API i en konkret NSP komponent i udviklingsmæssig sammenhæng, så er der et par tekniske øvelser, der skal være på plads. Da hovedparten af NSP'ens komponenter er bygget op på samme måde, så vil denne vejledning umiddelbart kunne anvendes i langt de fleste tilfælde. Antagelsen i denne vejledning er derfor at:

• Komponenten anvender Maven til styring af dependencies
• Komponenten afvikles på Wildfly (evt via et af NSP'ens Docker images)

I de følgende afsnit gennemgåes først, hvordan en komponent forberedes til at kunne anvende NSP Security API ved at udtrykke både en kodemæssig og en afviklingsmæssig afhængighed til NSP Security API.

Dernæst vises det med et praktisk eksempel hentet fra Dokumentdelingsservicen, hvordan NSP Security API bliver anvendt i applikationskode til at implementere brugerautentificering og -autorisation.

Det er vigtigt at notere sig, at eksempler i denne anvenderguide er ment som inspiration til anvendere af NSP Security API. Det er således ikke en udtømmende facitliste. Anvendelsen af NSP Security API kræver komponentspecifikke og forretningsspecifikke overvejelser:

• Hvilke brugertyper er til stede i min komponent?
• Hvordan skal disse brugertyper tjekkes/mappes i forhold til de forretningsregler, der gæder i min komponent=?
• Eksempler på aktører. Denne liste er ikke udtømmende, og det er vigtigt at overveje, hvad der skal gælde i de enkelte komponenter.:

Teknisk opsætning og anvendelse af NSP Security API

I forgående afsnit blev det fremhævet, at det ikke er en NSP komponents ansvar selv at inkludere NSP Security API i dens færdigbyggede modul.

I stedet udtrykker komponenten, at den regner med, at de omgivelser, hvori den efterfølgende afvikles, stiller NSP Security API til rådighed på afviklingstidspunktet.

Afviklingsomgivelserne for en standard NSP komponent er Wildfly (evt via et af NSP'ens Docker images). På Wildfly findes en række tredjeparts biblioteker, der leveres med platformen - herunder også NSP Security API.

Som default er de fleste af disse bibliotekter afskærmet og således ikke til rådighed for komponenten på afviklingstidspunktet - men via en særlig konfigurationsfil (som Wildfly forstår) kan det udtrykkes, at komponenten ønsker, at få adgang til et eller flere af disse biblioteker.

For at Wildfly kan stiller NSP Security API til rådighed for en komponent skal filen /src/main/webapp/WEB-INF/jboss-deployment-structure.xml findes i Maven projektet og i det byggede modul og have følgende indhold:

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        <!-- NSP komponenter styrer selv logning -->
        <exclude-subsystems>
            <subsystem name="logging"/>
        </exclude-subsystems>

        <!-- Denne komponent anvender NSP Security API -->
        <dependencies>
            <module name="dk.sds.nsp.security"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Det er vigtigt af forstå, at der ikke nødvendigvis er sammenhæng mellem det versionsnummer af NSP Security API, som bliver udtrykt i Maven afhængigheden, og den version af NSP Security API, der bliver stillet til rådighed af Wildfly.

Det er komponentens eget ansvar at sørge for, at der er sammenhæng mellem disse. Eventuelle versionsforskelle mellem det, som en komponent tror, at den får stillet til rådighed, og det, som den rent faktisk får stillet til rådighed, kan give en masse udfordringer og underlige fejl (NoSuchMethodException, ClassNotFoundException med flere), når komponenten afvikles og anvender NSP Security API.

I praksis kan man tjekke versionen af NSP Security API, der bliver stillet til rådighed af Wildfly, på følgende måde:

root@7e07691acb13:~# cd /tmp
root@7e07691acb13:/tmp# jar xf /pack/wildfly/modules/system/layers/base/dk/sds/nsp/security/main/nsp-security-api.jar
root@7e07691acb13:/tmp# cat META-INF/MANIFEST.MF 
Manifest-Version: 1.0
Implementation-Title: NSP Security API
Implementation-Version: 
Archiver-Version: Plexus Archiver
Built-By: root
Created-By: Apache Maven 3.5.4
Build-Jdk: 1.8.0_275
Specification-Version: 1.0.6

I ovenstående eksempel er det NSP Security API version 1.0.6, der stilles til rådighed af den konkrete version af Wildfly, hvilket hænger fint sammen med det versionsnummer, der blev udtrykt i Maven afhængigheden (i pom.xml).

TODO: Dokumentationskrav: 1) Brugerhistorier med komplet liste af brugertyper og beskrivelse af dem, så de giver mening for anvenderne 2) De enkelte brugertyper og de regler, der omgiver dem (hvad tjekkes i security api) skal beksrives i design og arkitekturguide

Eksemplerne nedenfor skal beriges med, hvad der IKKE må være tilstede (f.eks. for borger må der ikke være en organisation). Kig på de enkelte attributter i security api f.eks. som en tabel eller ligenden, så man kan se strukturen og de regler der gælder på de forskellige niveauer.

Komponenten skal modellere disse aktører på en eller anden måde (f.eks nedarvning eller en simpel enumeration, der lister typerne).