Dette dokument beskriver hvordan man anvender NSP Audit API til audit logning auditlogning på NSP.

Det første afsnit beskriver de arkitekturmæssige begrundelser for indførelse af NSP Audit API samt en oversigtstegning af, hvordan NSP Audit API spiller sammen de øvrige komponenter på NSP.

Dernæst vises hvordan NSP Audit API rent praktisk indføres i en NSP komponent med konkrete eksempler på anvendelse. 

Tilsidst vises "effekten" af anvendelse . I dette afsnit af NSP Audit API - hvilke informationer logges, og hvor stammer de fra.  Her gives også input til, hvordan en NSP komponent bør dokumentere sin anvendelse af NSP Audit API.  hvilket niveau af dokumentation den enkelte NSP komponent skal levere i f.eks. driftsmanualen.

Arkitekturoverblik og motivation for NSP Audit API

...

Dernæst vises det med et praktisk eksempel hentet fra Dokumentdelingsservicen, hvordan NSP Audit API kan anvendes i koden til at implementere audit logning.

Det demonstreres gennem eksemplet fra Dokumentdelingsservice, hvorledes anvendelsen af NSP Audit API kommer til udtryk i forhold til informationsniveau i den resulterende auditlog. Herigennem bliver det muligt for udviklere af NSP komponenter at forstå, hvilke informationer, der stammer fra afviklingsplatformen, og hvilke der stammer fra komponenten selv.

Tilsidst inkluderes en "dokumentationsskabelon", der kan anvendes som input til de konkrete driftsmanualer for de NSP komponenter, der anvender NSP Audit API.

auditlogning.

Maven dependency

Langt de fleste NSP komponenter anvender Maven til at holde styr på afhængigheder til tredjeparts biblioteker.

...

Provided scope i Maven benyttes til at udtrykke en afhængighed til et tredjeparts bibliotek, som ikke skal inkluderes i modulet selv, men som i stedet antages at blive stillet til rådighed (provided) af de omgivelser, som modulet afvikles i.

Afviklingsomgivelsern Afviklingsomgivelserne for en NSP komponent er Wildfly (evt via et af NSP'ens Docker images). I det følgende afsnit vises, hvordan man sørger for, at Wildfly rent faktisk stiller NSP Audit API til rådighed og derved opfylder kontrakten, som blev udtrykt i Maven konfigurationsfilen.

...

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

Udvikling af

...

auditlogning i komponent vha NSP Audit API

Når en komponent har fået sat afhængighed op til NSP Audit API, er den klar til at begynde at anvende dette til auditlogningsformål.

Anvendelse af NSP Audit API kan deles op i to punkter:

1. Oprettelse af en AuditBuilder til et kald (request) mod servicen, der ønsker at auditlogge
2. Tilføjelse af konkrete auditloginformationer til konkret AuditBuilder i forbindelse emd servicens udførelse af kald (request)

Fordi AuditBuilder er koblet sammen med platformens håndtering af kald (request/response), er der ikke brug for at komponenten kalder en commit metode eller lign.

Der skal derfor ikke gøres mere end de to nævnte punkter. Disse gennemgåes i det følgende.

Oprettelse af AuditBuilder

Anvendelse af NSP Audit API er meget simpel. For hver request som komponenten modtager skal følgende linie kaldes:

...

Når man kalder createAuditBuilder metoden i NSP Audit API'et anvender denne Java Service Loader systemet til at finde en NSP Audit Provider.

Når komponenten afvikles i drift på NSP platformen, vil der være en provider tilgængelig som rent faktisk står for at logge audit informationerne for hvert request. Det er driftens ansvar at sørge for, at dette sker

Under udvikling er det dog stadig muligt at bruge NSP Audit API idet den indeholder en fallback development provider. Denne provider skriver en advarsel til stderr om at den ikke må bruges i et driftet NSP miljø, men foretager sig ellers ikke noget pr. default. Hvis man sætter følgende system property vil den skrive hver audit information ud på stdout som et JSON objekt:

dk.sds.nsp.audit.DevelopmentAuditProvider.enabled=true

Alternativt kan man lave en ny NSP Audit Provider og få den loadet ved at placere provider-configuration filen dk.sds.nsp.audit.AuditProvider i en passende META-INF/services folder. Se Java Service Loader dokumentationen for detaljer.

I praksis vil der ikke være brug for dette, da fallback development provider i de fleste tilfælde er fuldt ud dækkende.

Tilføjelse af konkrete auditloginformationer

En AuditBuilder har 4 forskellige metoder til at tilføje audit information.

Den eneste forskel mellem metoderne er, hvordan den eller de valgte værdier er pakket ind.

Fælles for alle metoder er at de kræver følgende argumenter:

• component - : Komponentens aftalte forkortelse. Ofte forkortelsen af det projekt som stod bag komponenten. F.eks. STS, DDS, SDM, DCC mv.
• context - : Navnet på den context som komponenten er i lige nu. Det kunne f.eks. være hvilken service der er kaldt i komponenten, hvilken delkomponent der er i brug mv.
• type - : En af de mulige værdier "SensitivePersonalInformation", "RegularPersonalInformation" eller "NonPersonalInformation". Alt efter om der er tale om følsomme personoplysninger, almindelige personoplysninger eller oplysninger der ikke er knyttet til en person. Det er vigtigt at der vælges den korrekte type da det har konsekvens for hvem der har adgang til data.
• key - : En valgfri nøgle for den information der tilføjes. F.eks "cpr", "cvr", "samtykke" eller lign.
• value(s) - : Den eller de værdier der skal tilføjes til audit loggen.

...

public void addAuditInformation(String component, String context, TypeOfInformation type, String key, Object value);
public void addAuditInformation(String component, String context, TypeOfInformation type, String key, Supplier<?> value);
public void addAuditInformation(String component, String context, TypeOfInformation type, String key, Object... values);
public void addAuditInformation(String component, String context, TypeOfInformation type, String key, Iterable<?> values);

Fordi builderen er koblet sammen med platformens håndtering af request/response, er der ikke brug for at komponenten kalder en commit metode eller lign.

Der er derfor ikke mere arbejde end at oprette builderen og kalde en af de fire metoder for hver audit information der skal logges.

I forhold til hvilke værdier, der skal auditlogges, så er det op til den enkelte komponent at afklare det juridske behov i det konkrete tilfælde.

Dokumentdelingsservice: Eksempel på auditlogning via NSP Audit API

I de forgående afsnit blev det gennemgået, hvordan en AuditBuilder skal oprettes og håndteres i en NSP komponent, der ønsker at auditlogge, og hvorledes auditloginformationer kan tilføjes i løbet af servicens behandling af et kald.

I dette afsnit kigger vi på konkrete eksempler på dette taget fra Dokumentdelingsservice.

Dokumentdelingsservice gør det muligt for anvendere at fremsøge lister af dokumenter for borgere med forskelligt indhold f.eks. aftaler, laboratoriesvar og stamkort. Der er behov for at auditlogge hvem, der har tilgået disse informationer hvornår.

Dokumentdelingsservice indeholder

Anvendelse af NSP Audit API under udvikling

...

Eksempel på auditlogning

Det demonstreres gennem eksemplet fra Dokumentdelingsservice, hvorledes anvendelsen af NSP Audit API kommer til udtryk i forhold til informationsniveau i den resulterende auditlog. Herigennem bliver det muligt for udviklere af NSP komponenter at forstå, hvilke informationer, der stammer fra afviklingsplatformen, og hvilke der stammer fra komponenten selv.

Tilsidst inkluderes en "dokumentationsskabelon", der kan anvendes som input til de konkrete driftsmanualer for de NSP komponenter, der anvender NSP Audit API.

Alle

Beskrivelse i dokumentationen

...