Indhold

Indledning

Dokumenthistorik

Formål

Dette dokument giver et overblik over MinLog2 applikationerne med fokus på design og arkitektur.

Dokumentet giver et overblik over løsningens snitflader samt den interne struktur. Desuden indeholder det en beskrivelse af håndtering af ikke funktionelle krav.

Versionering

Ved nyt release af MinLog2, bumpes minor versionen kun hvis det er nødvendigt for anvendere at opdatere producer biblioteket.

Overblik

MinLog2 er primært delt i to applikationerdele, Registration og Lookup. Hver del indeholder SOAP baserede webservices der håndterer sikkerhed og mapning til/fra databasen.

Registration tilbyder services til.:

• Registering af logninger.

Lookup tilbyder services til.:

• Forespørgsel på logninger til borger opslag.
• Forespørgsel på logninger til medhjælpslog.

Image Removed

...

• .

Lookup services findes således i 2 sikkerhedsvarianter

1. DGWS (Den Gode WebService) - til sundhedsfaglige personale
2. OIOIDWS

Snitflader

Løsningen har en ekstern snitflade, der udstiller de ovenfor nævnte services som webservices.

1. - til borgeren

Nedenfor vises den overordnede arkitektur. 

En sundhedsfaglig person anvender en løsning som foretager en registrering i MinLog2:

Data valideres og formateres for at blive afleveret til et Kafka cluster. En eller flere MinLog2 consumere læser fra Kafka og indsætter i databasen.

Borgeren anvender feks. sundhed.dk til at se egen log og det gøres via forespørgsler til Lookup der læser fra databasen.

Af figuren nedenfor fremgår desuden, at MinLogs registreringsservice udstilles på dNSP'erne (foruden på cNSP). Via Kafka flyttes data til cNSP, og skrives i MinLog2-databasen. Fra cNSP udstilles MinLog2 lookup-services til hhv. borgeropslag og til medhjælpsloggen.

Image Added

Snitflader

MinLog2 løsningen håndterer både MinLog2 og MinLog1 formaterne.

Snitfladerne for MinLog2 beskrives i detaljer i dokumenterne "Guide til anvendere" - Registration skema beskrivelse og Lookup skema beskrivelse. Der er også her man finder links til WSDL filer. Vedrørende snitfladerne til MinLog1 så henvises der til dokumenterne som findes i svn - https://svn.nspop.dk/public/components/minlog-reg/latest/doc/ og https://svn.nspop.dk/public/components/minlog-ws/latest/doc/. 

Der henvises til de respektive moduler mht. detaljer omkring wsdl'er og fejlbeskederDer er ikke afhængigheder til andre services, men til komponenter til håndtering af autentifikation (SEAL) og SLA logning (NSPUtils).

Udover MinLog2's egen database, er løsningen afhængig af stamdatamodulets databaser, til berigelse af logdata ved Lookup. Principperne for anvendelse af stamdata fra stamdatamodulet afviges dermed, idet der ikke anvendes enkeltopslags- services eller kopiregisterservices. Dette er dog accepteret i MinLog 2-sammenhæng.

<iframe src="https://archi.nspop.dk/NSP/570928ca/views/cc47730d-040d-4f3f-8024-32441c1e2e6d.html" name="test" height="740" width="800">You need a Frames Capable browser to view this content.</iframe>   

* Hver kasse i ovenstående diagram har en kort forklaring, som kommer frem i et nyt browservindue, når der klikkes på kassen.

Komponenter

Løsningen er designet som en JEE web applikation bestående af følgende komponenter. Hvis der er ting der adskiller sig i de to applikationer, bliver det nævnt specifikt:

Webservice

CXF webservice komponent, der udstiller de forretningsmæssige services. Denne komponent håndterer protokol og headers.

Sikkerhed

Sikkerheden er implementeret i 2 varianter DGWS og OIOIDWS.

DGWS – Registration og Lookup

WSSecurity

IDCard læses fra SOAPHeader og sættes det på threadlocal. Kan kortet ikke læses, eller er signaturen ugyldig afvises brugeren.
I svaret tilføjes en WSSecurity header med et timestamp.

Medcom

På vej ind gemmes Medcom header på Threadlocal. På vej ud tilføjes Medcom header baseret på den indkomne.

Autentifikation og autorisation

IDCard fra Threadlocal og autentificerer kalderen ved at kontrollere, at kortet er gyldigt og ikke udløbet.

Herefter autoriseres brugeren, idet det verificeres, at denne har det fornødne niveau (medarbejder eller virksomhed). Bemærk at der efter aftale ikke er gjort brug af whitelisting på det udstillede services.

OIOIDWS – Lookupid

Sikkerheden omkring signering varetages af indgående og udgående CXF interceptorer.

Den indgående interceptor foretager:

• Validering af signaturer
• Validering af korrekt Audience
• Validering af eventuel Samtykke
• Udtræk af messageid og CPR/CVR til senere anvendelse

Data gemmes på threadlocal.

Den udgående interceptor foretager:

• Signering

Autentifikation og autorisation

opdelt i følgende struktur jee bestående af henholdsvis lookup og registration applikationerne, consumer, producer og shared.  

├── service
│   ├── lookup
│   │   ├── lookup-core
│   │   ├── lookup-ear
│   │   ├── lookup-idws
│   │   └── lookup-ws
│   ├── registration
│   │   ├── registration-core
│   │   ├── registration-war
│   │   ├── registration-minlog1-ws
│   │   └── registration-ws
├── shared
│   ├── shared-configuration
│   ├── shared-db
│   ├── shared-domain-api
│   ├── shared-test
│   ├── shared-test-idws
│   └── shared-ws
├── Consumer      
└── Producer

Service

Er opdelt i lookup og registration.

Som det fremgår er der flere webservices i modulerne lookup og registration - de deler deres kode i xxxx-core. Modulerne med postfix "-ws" indeholder selve implementeringen af webservicens operationer. Modulerne registration-war og lookup-ear er udelukkende holdere af deployment information samt initialiseringskode til applikationerne.

Consumer

Consumer modulet lytter på et kafka topic efter entries til MinLog2 og ved modtagelse indsættes de i databasen. Koden har taget udgangspunkt i Den Gode Brug af Kafka og følger dennes retningslinier. 

Producer

Producer har tidligere være et selvstændigt modul, men er nu en del af MinLog2. Dokumentation for dette modul findes her: https://www.nspop.dk/display/public/web/MinLogProvider+-+Leverancebeskrivelse

Shared

Dette modul har forskellige anvendelsesformål. 

Konfiguration

• shared-configuration indeholder DDL og konfigurationer - herunder muligheden for dem generet til specifikke miljøer

Der er ikke kode i denne

Delt kode

• shared-db indeholder kode, der deles mellem komponenter, der indsætter i databasen (consumer og lookup)
• shared-domain-api indeholder objekter, der udveksles via Kafka (registration og consumer)
• shared-ws indeholder kode relateret til adgang, SLA o.lign og benyttes i modulerne, der udstiller webservices (lookup og registration)

Disse komponenter deployes med i consumer, registration og lookup via maven afhængigheder

Delt testkode

• shared-test-xxx modulerne indeholder integrationstests og hjælpeværktøjer - der henvises til Integrationstests. 

Denne kode bliver ikke deployet.

Webservice stakken

Der er anvendt Apache CXF som webservice stak. Udgangspunktet er WSDL filer - som vha. maven danner klasser hvorfra MinLog2 implementeringerne arver fra:

dk.nsi.minlog2.registration.webservice.RegisterServiceImpl implements RegisterservicePort
dk.nsi.minlog2.registration.webservice.RegisterServiceImpl implements Service (Minlog1)
dk.nsi.minlog2.lookupid.LookupidImpl implements LookupidServicePortType
dk.nsi.minlog2.lookup.webservice.LookupServiceImpl implements LookupServicePort 

I forbindelse med deployment skal man være opmærksom på at subsystemerne i Jboss Wildfly til logning og webservices er slået fra - for at opnår den fulde kontrol over stakken. 

Nedenfor ses en sekvens diagram over registreringsdelen.

Image Added

Og opslagsdelen:

Image Added

Sikkerhed

Sikkerheden er implementeret i 2 varianter DGWS og OIOIDWS.

I begge tilfælde anvendes det af platformen tilbudte Security API til at tjekke indkommende credentials og restriktioner i forhold til medsendte oplysninger i sikkerhedsbilletter.

Autenficering af brugeren er foretages premature af STS. Bemærk at der efter aftale ikke er gjort brug af whitelisting på det udstillede services.

Vær opmærksom på at whitelisting heller ikke er implementeret for MinLog1.

Statuskomponent

Monitorering

En simpel servlet, der returnerer ok (http kode 200), hvis systemet er tilgængeligt. Desuden er det muligt at få detaljer om, hvilke komponenter, der er i live eller fejler.

Versionsinfo

En servlet, der fortælle hvilken version af løsningen, der er den aktuelle.

Forretningslag

Indeholder forretningslogikken.

Forretningslogik

Arkitektur lag

Der er fortaget en traditionel lagdeling af løsningen:

Webservice

Dette lag indeholder kode som interceptorer til håndtering af audit- og slalogning - hvis er kode relateret til sikkerhed som ikke håndteres af webservicestakken, skemavalidering af data (hvor det giver mening).

Controller

Laget En stateless ejb(controller) modtager kald fra webservicelaget og delegerer til andre klasser, der hver især håndterer hhv. validering, caching, groupering samt håndtering af persistens.

Domain

For Lookup Indeholder domain, JPA klasser til persistering. I Registration er det POJO's.

Data

...

lag

Indeholder logikken til insert af data fra Registration samt forespørgsel fra Lookup.

Registration afleverer data til Kafka igennem NSP komponenterne.

Lookup og Consumer, gør udelukkende brug af JPA til at håndtere forbindelsen til databasen. Alt insert sker via standard preparedStatements. Dette er gjort med henblik på af holde JPA ude af domain pakken, da direkte insert i databasen, fra servicen, er en midlertidig løsning.Lookup, bruger JPA dels til forbindelsen, men også mapning til domain. Dog er alle queries defineret som rå SQL, i koden, således at intet bliver autogeneret. Dette er gjort for at imødekomme tidligere erfaringer på platformen, om at autogeneret SQL fra JPA kan blive unødig kompleks og forringe performance.

...

Afhængigheder mellem komponenter.

Databasedesign

Log events, består af to deleprimærer tabeller. En source og en destinationlogentry. Destination indeholder Logentry indeholder alt information om logningen, mens source er kaldekæden gennem systemerne. Se Løsningsbeskrivelsen for nærmere beskrivelse. Disse gemmes i hver sin tabel. Database layout, herunder default værdier for felter kan ses i filen "shared/shared-configuration/src/main/resources/sql/initial_schema.sql".

For at forhindre at der kan forekomme dublikater ved insert, laves der en SHA256 hash over en række værdier, af databasen.

Caching

I MinLog2-Lookup er der en feature der kan opdele logninger i en række forskellige grupper. Det er et krav at der er mulighed for at bruge paginering ved disse grupper. Det giver problemer da grupperne nødvendigvis skal dannes på baggrund af hele søge resultatet og ikke blot over en delmængde. Hvis det skulle være muligt er man nød til at søge hele resultatet frem hver gang der forespørges på en ny side.

<iframe src="https://archi.nspop.dk/NSP/570928ca/views/fd898793-0995-4db2-ac58-29d71c50fcf3.html" name="test" height="260" width="800">You need a Frames Capable browser to view this content.</iframe>   

* Hver kasse i ovenstående diagram har en kort forklaring, som kommer frem i et nyt browservindue, når der klikkes på kassenFor at imødekomme begge krav, er der anvendt caching(ehcache) i Lookup. Når data er blevet grupperet bliver det cached. Der anvendes en nøgle generet ud fra de forskellige parametere i forespørgselen.

Ikke funktionelle krav

Sikkerhed

Løsningen er sikret med IDCard, der enten kan repræsentere en person eller en myndighed. I tilfælde af Lookupid anvendes OIOIDWS.Ved hver enkelt servicekald verificeres det, at kalderen har den fornødne rolle (myndighed eller medarbejder), og at det medfølgende IDCard overholder levetidskravet til det konkrete kalddet af platfomen udbudte Security API.

SLA logning

Der logges med brug af NSPUtils biblioteket: Et filter opretter en log entitet, der senere beriges med messageID fra Medcom headeren. SLAloggen gemmes i en tekstfil, og dens udseende kan konfigureresLogning foretages gennem NSP-Util og følger retningslinier herfor.

Audit logning

Ved alle kald registreres

...