Dette dokument beskriver hvordan man anvender NSP Audit API til audit logning 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. I dette afsnit gives også input til, hvordan en NSP komponent bør dokumentere sin anvendelse af NSP Audit API.
Arkitekturoverblik
NSP A
Anvendelse af NSP Audit API
For at anvende NSP Audit API i en konkret NSP komponent, så er der et par tekniske øvelser, der skal være på plads. Da hovedparten af NSPens komponenter er bygget op på samme måde, så vil denne vejledning umiddelbart kunne anvendes. Antagelsen i denne vejledning er 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 Audit API ved at udtrykke både en kodemæssig og en afviklingsmæssig afhængighed til 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.
Maven dependency
Langt de fleste NSP komponenter anvender Maven til at holde styr på afhængigheder til tredjeparts biblioteker.
NSP Audit API adskiller sig ikke fra andre tredjeparts biblioteker i den forstand og kræver således blot, at følgende tilføjes til rækken af dependencies (NB tjek versionsnummer i forhold til den gældende version) i konfigurationsfilen (pom.xml):
<dependency> <groupId>dk.sds.nsp.audit</groupId> <artifactId>audit-api</artifactId> <version>1.0.1</version> <scope>provided</scope> </dependency>
Det er vigtigt at notere sig, at afhængigheden til NSP Audit API skal have provided scope.
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 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.
Wildfly dependency
I forgående afsnit blev det fremhævet, at det ikke er en NSP komponents ansvar selv at inkludere NSP Audit API.
I stedet udtrykker komponenten, at den regner med, at de omgivelser, hvori den afvikles, stiller NSP Audit API til rådighed for den.
Afviklingsomgivelsern for en NSP komponent er Wildfly (evt via et af NSP'ens Docker images). På Wildfly findes en række tredjeparts biblioteker - herunder også NSP Audit 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.
For at Wildfly kan stiller NSP Audit 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 Audit API --> <dependencies> <module name="dk.sds.nsp.audit"/> </dependencies> </deployment> </jboss-deployment-structure>
Det er vigtigt af forstå, at der ikke nødvendigvis er sammenhæng mellem det versionsnummer af NSP Audit API, som bliver udtrykt i Maven afhængigheden, og den version af NSP Audit 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 inkludere, og det, som den rent faktisk inkluderer, kan give en masse udfordringer og underlige fejl (NoSuchMethodException mv), når komponenten afvikles og anvender NSP Audit API.
I praksis kan man tjekke versionen af NSP Audit API, der bliver stillet til rådighed af Wildfly, på følgende måde:
root@7e07691acb13:~# cd /tmp root@7e07691acb13:/tmp# jar xf /pack/wildfly8/modules/system/layers/base/dk/sds/nsp/audit/main/audit-api.jar root@7e07691acb13:/tmp# cat META-INF/MANIFEST.MF Manifest-Version: 1.0 Implementation-Title: NSP Audit 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.1
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 audit logning 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 er meget simpel. For hver request som komponenten modtager skal følgende linie kaldes:
AuditBuilder auditBuilder = Audit.createAuditBuilder();
Dette opretter en Audit Builder som kan føres med rundt i komponenten og kaldes hver gang audit information i forbindelse med kaldet opstår.
Det er vigtigt at denne linie udføres på den samme tråd som kalder komponentens Servlet metoder, annoterede WebMethod metoder eller lign.
Dette sikrer at platformen kan koble builderen sammen med det request/response der er i gang.
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.
Anvendelse af NSP Audit API under udvikling
Overblik over NSP Audit API funktioner
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
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 passende 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.
En leverance af en komponent til NSP må ikke indeholde en provider-configuration fil idet dette kunne påvirke andre komponenter på platformen.
Eksempel på auditlogning
Alle
Beskrivelse i dokumentationen
Alle NSP komponenter skal i følge kravene dokumentere deres auditlogninger i driftsdokumentationen. Når NSP Audit API anvendes, anbefales det at man for hver request angives hvilke audit informationer der logges ved at udfylde følgende skema
Komponent | Kontekst | Type | Nøgle | Information |
---|---|---|---|---|
For hvert request kan man angive et skema med en række for hver audit information der logges. Følgende er et eksempel fra STS'en:
Komponent | Kontekst | Type | Nøgle | Information |
---|---|---|---|---|
STS | SecurityTokenRequest | Ikke personlig | cvr | CVR nummeret for den kaldende organisation |
STS | SecurityTokenRequest | Følsomme | cpr | CPR nummeret på den person der skal have udsted et id kort. |