Page History
Navitabs | ||||
---|---|---|---|---|
| ||||
Table of Contents |
---|
Introduktion
Formål
MinSpærring Samtykkeservicen servicen er en national service til administration og verifikation af en borgers samtykke og spærringer for sundhedsfagliges adgang til data i nationale systemer.
Formålet med dette dokument er beskrive arkitektur og design i MinSpærring servicenSamtykkeservicen.
For et overblik over systemet se afsnittet "Overblik over løsningen".
Læsevejledning
I dokumentet bruges begreberne autorisation og autoriseret primært i en sikkerhedskontekst, det vil sige i forståelsen af, at en person eller et system er autoriseret til at bruge en given ressource. Hvis begreberne anvendes om en sundhedsfaglig med dansk autorisation, der er anført i Sundhedsstyrelsens autorisationsregister, vil det blive udtrykkeligt angivet.
Dokument historik
Version | Date | Responsible | Description |
---|---|---|---|
1.0 | 29.06.2012 | Systematic | First edition |
1.1 | 28.11.2014 | Systematic | References to National Patient Index (NPI) removed |
1.2 | 25.11.2016 | Systematic | MinLog now reuses SOSI ID-card and no longer requires HSUID (5.4) |
1.3 | 7.2.2017 | Systematic | Added handling of data specific consent by precautionary principle to section 5.3.1. |
1.4 | 13.06.2018 | Systematic | Migrated to NSPOP SVN |
23.10.2018 | KIT | Document moved from Word to Confluence. Original document name was: SDD0011 Consent Services Architecture and Design.docx | |
14.05.2020 | KIT | SDS-3883 Etablering af IDWS snitflade | |
09.11.2020 | KIT | SDS-3685 Min Spærring skal anvende SORES til SOR-SHAK opslag | |
12.11.2020 | KIT | Oversættelse til dansk | |
06.05.2021 | KIT | [SDS-2416] Samtykkeservicen skal ændres til at kalde minlog2 |
Definitiner og referencer
Formålet med dette afsnit er at give en oversigt over definitioner og dokumentreferencer, der bruges i dette dokument.
...
Reference | Beskrivelse |
---|---|
Behov | National consentservice, v1.1 (behovsbeskrivelse for Min Spærring Service) |
Data Model | MinSpærring Samtykkeservicen- Data Model |
Administra Service Interface Beskrivelse | MinSpærring Samtykkeservicen- Administration Service Interface Description |
Verifikation Service Interface Beskrivelse | MinSpærring Samtykkeservicen- Verifikation Service Interface Beskrivelse |
Driftsvejledning | MinSpærring Samtykkeservicen- Driftsvejledning |
MinLog | Snitfladebeskrivelse Min-log Web services (SSE/11734/IFS/0003) (Min-log Service Interface Description, available in Danish only).MinLogProvider |
UdviklerGuide | |
HSUID-Header | MinSpærring Samtykkeservicen- Healthcare Service User Identification Header Interface Description |
Sundhedsloven | LBK nr 913 af 13/07/2010 (Sundhedsloven) https://www.retsinformation.dk/forms/r0710.aspx?id=130455 |
Ændring af sundhedsloven | LOV nr 605 af 14/06/2011 (Lov om ændring af sundhedsloven) |
...
Samtykkeservicen
Baggrund
Grundlaget for samtykke service er som følger::
...
Web Service for registration and lookup / control of consent information.”
Kravene, som MinSpærring skal Samtykkeservicenskal opfylde, er uddybet i [Behov]. Det juridiske grundlag er beskrevet i [Sundhedsloven] med rettelser givet i [Ændring af sundhedsloven].
Overblik over løsningen
MinSpærring Samtykkeservicen udstiller to services. Det er MinSpærring Samtykkeservicen Administration og MinSpærring Samtykkeservicen Verifikation.
MinSpærring Administration
Allows registration and maintenance of submitted consents for the citizen. The service expose the following operations
Tillader registrering og vedligeholdelse af spærringer og samtykker for en borger. Serivcen tilbyder nedenstående funktionalitet.
ConsentRegistrationsGet – Returnerer alle registreringer for en borger.
ConsentAdd – Opretter en ny spærringer eller samtykke for en borger. Et registrering er defineret i MinSpærring - Data Model og indeholder:
Type (samtykke eller spærring)
Hvad det gælder
Hvem det gælder for
Gyldighedsperiode
Operationen kan kaldes af både borgere og af en anden person, som det kaldende system har verificeret, har lov til at oprette en spærring eller samtykke på borgerens vegne.
Operationen understøtter desuden oprettelse af samtykke til udenlandsk sundhedspersonales adgang til data.
- ConsentModify - Ændrer et samtykke til en borger. En ændringer er defineret på samme måde som hvis der oprettes en ny registrering.
- ConsentRevoke - Tilbagekalder et samtykke eller spærring så det ikke længere er gyldigt.
Nogle operationer tillader at bruger og borger ikke er den samme person. Hvis de ikke er den samme person logges handling til borgerens MinLog.
MinSpærring Administration opbevarer i sin database information om samtykke og spærring, som angivet af ConsentAdd ovenfor, ud over oplysninger om, hvem og hvornår samtykke henholdsvis oprettes og ændres.
MinSpærring Verifkation
Servicen anvendes til at verificere spærringer og samtykker mellem border og sundhedsfaglig. Service udstiller nedenstående operationer:
HTML |
---|
<iframe src="https://archi.nspop.dk/NSP/570928ca/views/ba962f9c-58fb-40ba-92cc-a7d065936542.html" name="test" height="570" 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.
Samtykkeservicen Brugertyper
Der findes følgende brugertyper i Minspærring:
- Borger
- Systembruger
- Sundhedsfaglig
- Administrativ
Bestemmelse og mapning til actor
De enkelte brugertyper bestemmes udfra modellen, der udstilles i Security API. Disse regler er opsummeret i tabellerne nedenfor.
Brugertypen: Borger | Verifikation | Mapning til Samtykkeservicen ServiceActor | ||
SecurityContext | Ticket | Audience | Matche audience som findes som konfiguration i Minspærring | |
Validity | Er valid | |||
Message | Verificeres ikke - må gerne være der | |||
ActingUser | UserType | Skal være Citizen | Brugertypen: Borger | |
IdentifierFormat | Skal være CPR | |||
Identifier | Skal være sat | actionUserCpr | ||
GivenName | Verificeres ikke - må gerne være der | |||
SurName | Verificeres ikke - må gerne være der | |||
Credentials | Verificeres ikke - må gerne være der | |||
PersistentUniqueKey | Verificeres ikke - må gerne være der | |||
PrincipalUser | Må ikke være der | |||
Organisation | Må ikke være der | |||
Client | Name | Verificeres ikke - må gerne være der | systemName |
Brugertypen: Sundhedsfaglig | Verifikation | Mapning til Samtykkeservicen ServiceActor | ||
SecurityContext | Ticket | Audience | Verificeres ikke - må gerne være der | |
Validity | Er valid | |||
Message | Verificeres ikke - må gerne være der | |||
ActingUser | UserType | Skal være HealthCareProfessional | Brugertypen: Sundhedsfaglig | |
IdentifierFormat | Skal være CPR | |||
Identifier | Skal være sat | actionUserCpr | ||
GivenName | Verificeres ikke - må gerne være der | |||
SurName | Verificeres ikke - må gerne være der | |||
Credentials.NationalRole | Må ikke være der | |||
PersistentUniqueKey | Verificeres ikke - må gerne være der | |||
PrincipalUser | Må ikke være der | |||
Organisation | Identifier | Skal være der | organisationIdentifier | |
identifierFormat | Skal være der og skal være CVR | |||
Client | Name | Verificeres ikke - må gerne være der | systemName |
Brugertypen: Administrativ | Verifikation | Mapning til Samtykkeservicen ServiceActor | ||
SecurityContext | Ticket | Audience | Verificeres ikke - må gerne være der | |
Validity | Er valid | |||
Message | Verificeres ikke - må gerne være der | |||
ActingUser | UserType | Skal være HealthCareProfessional | Brugertypen: Administrativ | |
IdentifierFormat | Skal være CPR | |||
Identifier | Skal være sat | actionUserCpr | ||
GivenName | Verificeres ikke - må gerne være der | |||
SurName | Verificeres ikke - må gerne være der | |||
Credentials.NationalRole | Skal være der - og skal matche config variable i MinSpaerring | |||
PersistentUniqueKey | Verificeres ikke - må gerne være der | |||
PrincipalUser | Må ikke være der | |||
Organisation | Identifier | Skal være der | organisationIdentifier | |
identifierFormat | Skal være der og skal være CVR | |||
Client | Verificeres ikke - må gerne være der | systemName |
Brugertypen: System | Verifikation | Mapning til Samtykkeservicen ServiceActor | ||
SecurityContext | Ticket | Audience | Verificeres ikke - må gerne være der | |
Message | Verificeres ikke - må gerne være der | |||
ActingUser | Må ikke være der | Brugertypen: System | ||
PrincipalUser | Må ikke være der | |||
Organisation | Identifier | Skal være der | organisationIdentifier | |
identifierFormat | Skal være der og skal være CVR | |||
Client | Verificeres ikke - må gerne være der | systemName |
Transformation af Systembruger
En systembruger giver ikke mening i sig selv i forhold til de beskrevne brugerhistorier. Systembrugeren er der kun således at systemer (i praksis sundhed.dk) kan anvende Samtykkeservicen og ved hjælp af en medsendt HSUID header kan opnå status som een af brugertyperne Borger eller Sundhedsfaglig.
Brugertypen Borger (sundhed.dk) | Verifikation | Mapning til Samtykkeservicen ServiceActor | ||
HSUID Header | userType | Skal være der og skal være CITIZEN | Brugertypen: Borger | |
actingUserCivilRegistrationNumber | Skal være sat | actionUserCpr | ||
responsibleUserCpr | Må ikke være sat eller være anderledes end actingUserCivilRegistrationNumber | |||
systemName | Verificeres ikke - må gerne være der | systemName (prefix) | ||
systemVersion | Verificeres ikke - må gerne være der | systemName (postfix) |
Brugertypen Sundhedsfaglig (sundhed.dk) | Verifikation | Mapning til Samtykkeservicen ServiceActor | ||
HSUID Header | userType | Skal være der og være HEALTHCAREPROFESSIONAL | Brugertypen: Sundhedsfaglig | |
actingUserCivilRegistrationNumber | Skal være sat | actionUserCpr | ||
responsibleUserCpr | Må ikke være sat eller være anderledes end actingUserCivilRegistrationNumber | |||
orgUsingIDType | Verificeres ikke - må gerne være der | healthcareOrgType | ||
orgUsingIDName | Verificeres ikke - må gerne være der | healthCareOrg | ||
systemName | Verificeres ikke - må gerne være der | systemName (prefix) | ||
systemVersion | Verificeres ikke - må gerne være der | systemName (postfix) |
Samtykkeservicen Administration
Allows registration and maintenance of submitted consents for the citizen. The service expose the following operations
Tillader registrering og vedligeholdelse af spærringer og samtykker for en borger. Serivcen tilbyder nedenstående funktionalitet.
ConsentRegistrationsGet – Returnerer alle registreringer for en borger.
ConsentAdd – Opretter en ny spærringer eller samtykke for en borger. Et registrering er defineret i Samtykkeservicen - Data Model og indeholder:
Type (samtykke eller spærring)
Hvad det gælder
Hvem det gælder for
Gyldighedsperiode
Operationen kan kaldes af både borgere og af en anden person, som det kaldende system har verificeret, har lov til at oprette en spærring eller samtykke på borgerens vegne.
Operationen understøtter desuden oprettelse af samtykke til udenlandsk sundhedspersonales adgang til data.
- ConsentModify - Ændrer et samtykke til en borger. En ændringer er defineret på samme måde som hvis der oprettes en ny registrering.
- ConsentRevoke - Tilbagekalder et samtykke eller spærring så det ikke længere er gyldigt.
Nogle operationer tillader at bruger og borger ikke er den samme person. Hvis de ikke er den samme person logges handling til borgerens MinLog.
Samtykkeservicen Administration opbevarer i sin database information om samtykke og spærring, som angivet af ConsentAdd ovenfor, ud over oplysninger om, hvem og hvornår samtykke henholdsvis oprettes og ændres.
Samtykkeservicen Verifkation
Servicen anvendes til at verificere spærringer og samtykker mellem border og sundhedsfaglig. Service udstiller nedenstående operationer:
ConsentForUserCheck – Returnerer det generelle samtykkeforhold (samtykke eller spærring) for en bruger med hensyn til en borger; hvis brugeren har lov til at se alt eller intet om borgeren.
ConsentForDataCheck – Returnerer det
ConsentForUserCheck – Returnerer det generelle samtykkeforhold (samtykke eller spærring) for en bruger med hensyn til en borger; hvis brugeren har lov til at se alt eller intet om borgeren.
ConsentForDataCheck – Returnerer det specifikke samtykkeforhold (samtykke eller spærring) for en bruger og konkrete oplysninger om en borger; hvis brugeren har lov til at se disse konkrete oplysninger om borgeren. De konkrete oplysninger / dokumenter returneres i form af en liste af ID'er. ID'erne der ønskes undersøgt er en del af forespørgslen til servicen.
ConsentForForeignersCheck – Returnerer, om udenlandske sundhedsfaglige kan få adgang til patientoversigt og elektronisk recept til borgeren gennem epSos
...
For sundhedsfaglige er det nedenstående beslutningstræ der anvendes til at lave MinSpærring Samtykkeservicen Verifikation:
Gliffy Diagram macroId d54356ae-900b-4792-b5d3-dd7011d9e504 name Verifikation pagePin 1
...
Bemyndigelse er en tilstand hvor en sundhedsfaglig arbejder på vegne af en anden. Den sundhedsfaglige der arbejdes på vegne er typisk ansvarlig for de handlinger der udføres.
Fælles for MinSpærring
Begge services overholder Den Gode Web Service 1.0.1 og kræver:
At anvendersystem er godkendt af STS på NSP med mindst sikkerhedsniveau 3
At anvender er whitelisted i servicen
Det er anvendersystemets ansvar It is the responsibility of the calling system to ensure that the user is authenticated and authorized.
Database og service deployment overblik
Som afbildet i figur 3 lagres MinSpærring data i en central database, der replikeres til de forskellige NSP instanser.
.0.1 og kræver:
At anvendersystem er godkendt af STS på NSP med mindst sikkerhedsniveau 3
At anvender er whitelisted i servicen
Det er anvendersystemets ansvar It is the responsibility of the calling system to ensure that the user is authenticated and authorized.
Database og service deployment overblik
Samtykkeservicen data lagres i en central database, der replikeres til de forskellige NSP instanser.
HTML |
---|
<iframe src="https://archi.nspop.dk/NSP/570928ca/views/id-0d9123b8-1e2f-41eb-b393-5d9b50963a60.html" name="test" height="340" 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.
Samtykkeservicen MinSpærring Administration installeres på en central server og eksponeres på NSP-forekomster gennem afkoblingskomponenten DCC. Proxyen for MinSpærring Samtykkeservicen Administration, der bruges i en NSP-instans, implementeres ikke som en del af denne service. Proxyen oprettes på NSP i form af en konfiguration af DCC.
MinSpærring Samtykkeservicen Verifikation er kun installeret på cNSP og forespærger forespørger på den lokale database.
Design mål og beslutninger
Design mål
Systemet skal designes i overensstemmelse med de mål og prioriteter, der er angivet i tabel 1. Prioriteten for hvert mål er angivet med en score på 1 til 5, hvor 5 angiver den højeste prioritet.
...
Tabel 1: Design mål og deres indbyrdes prioritering
Design beslutninger
Dette afsnit indeholder vigtige designbeslutninger og deres begrundelse. Hvis det er relevant, præsenteres afviste designs også med begrundelsen for deres afvisning.
Belslutning angående logning
Fejlr og debug logging er implementeret via log4j der er konfigureret for hvert service. Der laves en logfil pr. service.
I denne log registreres exceptions og stacktraces. Hvis konfigurationen er indstillet til 'debug'-niveau, logges der også flowID ved ind- / udgang af servicemetoderne.
Debuglog er blevet implementeret for at lette fejlfinding, således at flowID (og følgelig en besked) kan spores mellem serviceopkald.
...
Tid (zulu time)
Bruger ID
Metodekald
borgeren
Anvender systems CVR nummer
SessionID fra IDWS sikkerhedskontekst (messageID)
Beslutning angående konfiguration
The service configuration is performed in two (three for the administration service) different properties files that must be deployed on the Web server somewhere in the application’s classpath.
Servicekonfigurationen udføres i to (tre for MinSpærring Samtykkeservicen Administration) forskellige property filer, der leveres som en del af docker setup.
Changes in the configuration should prompt a reboot of the service, as the configuration is loaded and verified on start-up of the individual servicesaf docker setup.
Ændringer i konfigurationen skal medføre en genstart af den container som servicen den kører i da konfiguration indlæses ved opstart.
For beskrivelse af konfigurationen se MinSpærring Samtykkeservicen - Driftsvejledning.
Applikations konfiguration
...
Service klient konfiguration
MinSpærring Samtykkeservicen Administration service skal være i stand til at kommunikere med Min Log'-tjenesten, og konfigurationen af den anvendte serviceklient skal også udføres i en konfigurationsfil.
Placeringen af denne fil findes i applikationskonfigurationen.
Log konfiguration
In the log configuration file, error and debug log configuration is provided by stating a log4j-logger property with the name log4j.logger.dk.nsi.
I logkonfigurationsfilen leveres konfiguration af error og debug ved at angive en log4j-logger property med navnet log4j.logger.dk.nsi.
Database konfiguration
Both consent services must be provided with a data source with the name ’ConsentServiceDS’ that has access to the consent database described in [Data Model].
.nsi.
Database konfiguration
Begge Samtykkeservicen Begge MinSpærring services skal forsynes med en datasource med navnet 'ConsentServiceDS', der har adgang til den database der er beskrevet i MinSpærring Samtykkeservicen - Data Model.
Both services must have access to a data source with the name ’WhitelistDS’ that is used by whitelist validation of calling systems.
Begge tjenester skal have adgang til en datasource med navnet 'WhitelistDS', der bruges af whitelist af anvendersystemer.
Decision concerning Web services
The two consent Web services has been developed with a ”Java-first” approach, where the Java code has been developed independently and the WSDL generated at the time of running on the Web server on the basis of the implemented code.
The Java-first approach was chosen to ease development and maintenance of the service, as this makes it possible to harness existing Java-competencies. The option of customizing the exposed WSDL is sacrificed.
Contents of Web service call
The Web service operations consists of: a Medcom-header, a security-header, a HSUID-header [HSUID], and a body element.
In the consent administration, the contents of the HSUID-header is used to authenticate and validate the authorization of the calling user in addition to validate if the user is allowed to call the method with the included body parameters.
Furthermore, the ’acting user’-field in the HSUID-header is used to set the ’created by’ (’oprettet af’) and ’modified by’ (’modificeret af’) fields on consents in addition to assess if it must be logged that a consent has been created/changed by another citizen than the one the consent concerns.
In consent verification, only the validity of the HSUID-header is validated.
The Medcom-header is used to validate the security level and the signature.
The security header is used to validate whether the attached signature and STS security-token is valid, cf. the configuration that has been used to configure the service.
All other parameters for the method calls are contained in the attached body for which content varies in regard to the individual operation (see [Consent Administration Interface Description] and [Consent Verification Interface Description]).
Decision regarding service architecture
Each service is implemented as a Java EE stateless session bean that implements an interface that defines the methods the Web service exposes. Both the bean and the Web Service implementation is handled through Java EE annotations.
By implementing the service as a Java EE bean, it is made possible for the application server to handle data source injection, transactions, and system resources, rather than handling this manually in the code.
Every aspect of complying with DGWS, IDWS, security handling and logging is handled by Java EE interceptors that are automatically invoked by the surrounding EJB container.
Decision regarding data sources
The consent database handling is implemented through Hibernate, which makes it possible to detach the database handling from the code. The data source for the consent database is handled through injection from the EJB container in the application server.
The data source for the whitelist (that is used to verify whether calling systems has access to the service), is handled by a context-lookup in the code and thus is not injected from the EJB container.
The reason for doing so is that the whitelist is not handled directly by the bean, but by an interceptor that can be configured independently of the bean implementation. The interceptor is provided by a common code module and is used by multiple services to ensure that DGWS is obeyed in addition to validation of security. To avoid a dependency from the whitelist to the bean, the data source lookup takes place in the shared module.
Data Model
The data model for consent service is documented in [Data Model].
Architecture Design
This section describes static as well as dynamic aspects of the system architecture, including the basis for the individual design choices.
Static Structure
Overview
The general service structure is that the service is implemented as a stateless session bean that implements a Web interface that is a Java Web service.
This bean then handles the service logic, DAOs and other business logic.
Security validation, logging and error handling is handled by a number of Java EE interceptors.
The service is deployed on an application server that is responsible for generation of a Web interface (and WSDL), managing data source injection and handling of system resources.
Database handling
The database communication is handled by a number of DAOs (one per injected data source) that encapsulates the database communication in a number of object related methods.
The whitelist is not handled through a DAO. Instead, the whitelist implementation makes a direct request to its data source.
ConsentVerificationDAO
Is handled by an entity manager (defined in the persistence.xml-file in the application) named ’ConsentVerificationService’ that is injected through the Java EE annotation @PersistenceContext in the bean.
This entity manager make use of the data source ’ConsentServiceDS’.
The DAO exposes methods that correspond to the functions that the Web service expose to calling systems. It is used by the bean to obtain a citizen’s consents.
ConsentAdministrationDAO
Is handled by an entity manager (defined in the persistence.xml-file in the application) named ’ConsentAdmin’ that is injected through the Java EE annotation @PersistenceContext in the bean.
This entity manager make use of the data source ’ConsentServiceDS’.
The DAO exposes methods that correspond to the functions that the Web service expose for calling systems. It is used by the bean to modify the citizen’s consents.
...
Interceptors
A number of interceptors are used in the implementation of the specific service for performing SLA-logging, error handling and security validation. These interceptors make use of the interceptor-pattern and prevents the EJB container from calling the specific service implementation directly, as the call hits a proxy that calls the annotated interceptors sequentially.
Each interceptor then wraps the ensuing call and can perform error handling and logging.
Every interceptor is annotated with @AroundInvoke, which means that they are called before the service methods are invoked.
SLA logging
SLA log-interceptor is responsible for SLA logging of all service calls.
Error handling
Consent Administration and Consent Verification handles errors differently. See the subsections "Error Handling" in the following two sections.
Service Logic for Consent Administration
The service logic is implemented directly in the bean implementation as the logic primarily consist of forwarding calls to the DAO. Additionally, overall validation of the HSUID header is performed in addition to validating that health professionals are only allowed to call the ‘ConsentAdd’ method.
If the user differs from the citizen that is subject of the consent, a call is additionally made to the Min-log service to log this change in the citizen’s ’Min Log’.
The consent service make use of the Min Log service client (see section 5.4).
Error handling
The error handling intercept performs general error handling of all service calls and wraps and ensures that it is only SOAP faults that are returned to the calling systems.
It additionally ensures that potential errors are logged in the error log and performs debug logging of flow ID.
Service Logic for Consent Verification
The service logic comply with the decision graph that has been made for consent verification (see section 2.2) and it is implemented in the class ConsentVerificationServiceLogic.
Consent verification
The verification consists of three different operations: user verification, data verification and verification of foreign health professionals.
The foreign health professionals are persons who attempt to access a citizen’s data through epSos. It is possible for a citizen to register positive consent for this (see section 2.2).
User verification is used to obtain an indication of whether a user can access a citizen’s data. It is possible for a system to call this service and thus avoiding examination of each individual data element.
If ’Positiv’ is returned, then the calling system do not need to validate consent for possible data as the citizen has provided consent for the calling user for all data.
If ’Negativ’ is returned, then the calling system do not need to lookup data, as negative consent is provided for the calling user for all data.
Only on a ’Dataspecifik’ returnvalue will it be necessary for the calling system to make a request to the other verification method.
Data verification is used to examine which data in a sequence of specific data elements the user has consent too view.
This method is only necessary to call if user verification has returned a data specific result.
The method accepts a list of possible data elements and returns a list of those data elements (from the received list) that the user has consent to view.
Consent for persons and data
The service logic class retrieves all the citizen’s consents from the database and filter these using the class ConsentTypeFilterer.
In this class, consents are filtered in relevant units corresponding to the various steps in the decision graph (e.g. positive consent for the user’, ‘negative consent for all’, ’positive consent for the users organization’ etc.). The filtration is performed on the consents and possible associated ’who’ element. The ‘what’ element is not examined in the filtration.
...
whitelist af anvendersystemer.
Beslutninger angående Web Services
De to Samtykkeservicen services er udviklet med en ”Java-first” tilgang, hvor Java-koden er udviklet uafhængigt, og WSDL genereres på tidspunktet for kørsel på webserveren på basis af den implementerede kode.
Java-first-metoden blev valgt for at lette udvikling og vedligeholdelse af tjenesten, da dette gør det muligt at udnytte eksisterende Java-kompetencer. Muligheden for at tilpasse den udsatte WSDL ofres.
Denne beslutning er omgjort med SDS-4222, hvor der er lavet faste WSDL filer, hvorfra der generes java klasser. WSDL filerne udstilles direkte via en servlet og på servicens endpoints (?wsdl).
Indhold af Web Service kald
Web Service operationerne består af: en Medcom-header, en sikkerheds-header, en HSUID-header Samtykkeservicen - Healthcare Service User Identification Header Interface Description og et body-element.
I Samtykkeservicen Administraition bruges indholdet af HSUID-headeren til at autentificere og validere autorisationen for den kalende bruger ud over at validere, at brugeren har lov til at kalde metoden med de inkluderede parametre i body elementet.
Desuden bruges det 'fungerende bruger'-felt i HSUID-headeren til at indstille felterne' oprettet af' og' modificeret af' på en spærring/samtykke samt for at vurdere om det skal logges at en registrering er oprettet/rettet af en anden borger end den registreringen berører.
Ved Samtykkeservicen Verifikation er kun gyldigheden af HSUID-headeren valideret.
Medcom-headeren bruges til at validere sikkerhedsniveauet og signaturen.
Security Headeren bruges til at validere, om den vedhæftede signatur og STS-sikkerhedstoken er gyldig, jf. den konfiguration, der er brugt til at konfigurere tjenesten.
Alle andre parametre for kald til servicen er indeholdt i SOAP body elementetm for hvilket indhold varierer med hensyn til den enkelte operation (se Samtykkeservicen - Administration Service Interface Description og Samtykkeservicen - Verifikation Service Interface Beskrivelse).
Beslutninger vedrørende service arkitektur
Hver service implementeres som en stateless Java EE-sessionbønne, der implementerer en grænseflade, der definerer de metoder, servucen udstiller. Både implementeringen af bønne og webservicen håndteres via Java EE-kommentarer.
Ved at implementere tjenesten som en Java EE-bønne er det muligt for applikationsserveren at håndtere datasource injection, transaktioner og systemressourcer i stedet for at håndtere dette manuelt i koden.
Hvert aspekt af overholdelse af DGWS, IDWS, sikkerhedshåndtering og logning håndteres af Java EE-interceptorer, der automatisk kaldes af den omgivende EJB-container.
Beslutninger vedrørende data sources
Samtykkeservicen databasen implementeres gennem Hibernate, hvilket gør det muligt at afkoble databashåndteringen fra koden. Datasource til Samtykkeservicen håndteres gennem injektion fra EJB-containeren i applikationsserveren.
DataSournce til whitelisting (der bruges til at kontrollere, om anvendersystemer har adgang til tjenesten), håndteres af et kontekstopslag i koden og injiceres således ikke fra EJB-containeren.
Årsagen til dette er, at whitelist ikke håndteres direkte af bønnen, men af en interceptor, der kan konfigureres uafhængigt af bønneimplementeringen. Interceptoren leveres af et fælles kodemodul og bruges af flere tjenester for at sikre, at DGWS overholdes ud over validering af sikkerhed. For at undgå en afhængighed fra whitelist til bønnen finder datasource opslag sted i det delte modul.
Data Model
Datamodelen er dokumenteret i Samtykkeservicen - Data Model.
Arkitektur
Dette afsnit beskriver både statiske og dynamiske aspekter af systemarkitekturen, herunder grundlaget for de individuelle designvalg.
Statisk struktur
Overblik
Den generelle servicestruktur er, at tjenesten implementeres som en statsløs sessionbønne, der implementerer en Web Service, der er en Java Web Service.
Denne bønne håndterer derefter servicelogikken, DAO'er og anden forretningslogik.
Sikkerhedsvalidering, logning og fejlhåndtering håndteres af et antal Java EE-interceptors.
Tjenesten kører på en applikationsserver, der er ansvarlig for generering af en Web Interface, styring af datasource injection og håndtering af systemressourcer.
Database håndtering
Databasekommunikationen håndteres af et antal DAO'er (en pr. Injiceret datasource), der indkapsler databasekommunikationen i et antal objektrelaterede metoder.
Whitelist håndteres ikke via en DAO. I stedet fremsætter hvidlisteimplementeringen en direkte forespørgsel til sin datakilde.
ConsentVerificationDAO
Håndteres af en EntityManager (defineret i persistence.xml-filen i applikationen) med navnet 'ConsentVerificationService', der injiceres gennem Java EE-kommentaren @PersistenceContext i bønnen.
Denne EntityManager gør brug af datasourcen 'ConsentServiceDS'.
DAO udstiller metoder, der svarer til de funktioner, som webservicen udstiller til anvendersystemer. De bruges af bønnen til at læse en borgers samtykker og spærringer.
ConsentAdministrationDAO
Håndteres af en EntityManager (defineret i persistence.xml-filen i applikationen) med navnet 'ConsentAdmin', der injiceres gennem Java EE-kommentaren @PersistenceContext i bønnen.
Denne EntityManager gør brug af datasourcen 'ConsentServiceDS'.
DAO udstiller metoder, der svarer til de funktioner, som webservicen udstiller til anvendersystemer. De bruges af bønnen til at vedligeholde en borgers samtykker og spærringer.
Databasefunktionerne implementeres ved hjælp af Hibernate.
Interceptors
Et antal interceptors bruges til implementering af SLA-logning, fejlhåndtering og sikkerhedsvalidering. Disse interceptors gør brug af interceptor-mønsteret og forhindrer EJB-containeren i at kalde den specifikke serviceimplementering direkte, da kald rammer en proxy, der kalder de annoterede interceptors sekventielt.
Hver interceptor indpakker derefter det efterfølgende kald og kan udføre fejlhåndtering og logning.
Alle interceptorer er annonteret med @AroundInvoke, hvilket betyder, at de kaldes op, før servicemetoderne eksekveres.
SLA logging
SLA-log-interceptor er ansvarlig for SLA-logning af alle servicekald.
Fejlhåndtering
Samtykkeservicen Administration og Samtykkeservicen Verifikation håndterer fejl forskelligt. Se underafsnittene "Fejlhåndtering" i de følgende to sektioner.
Service Logik Samtykkeservicen Administration
Servicelogikken implementeres direkte i bønneimplementeringen, da logikken primært består i videresendelse af opkald til DAO'en. Derudover udføres samlet validering af HSUID-overskriften ud over validering af, at sundhedspersonale kun har tilladelse til at kalde 'ConsentAdd' -metoden. Det tjekkes ved kald af cprexists-servicen, at det cpr-nummer som forespørgslen indeholder er gyldigt.
Ved oprettelse, ændring og sletning af samtykke sendes adviseringer til National Adviseringsservice (NAS2) med borgerens cpr-nummer som id. Dermed kan anvendere abonnere på ændringer for specifikke borgere.
Hvis brugeren adskiller sig fra den borger, der er omfattet af samtykke logges ændringen i Min Spærring til MinLog2.
Samtykketjenesten gør brug af Min Log Provider.
Fejlhåndtering
Fejlhånterings-interceptoreren udfører generel fejlhåndtering af alle servicekald og sikrer, at det kun er SOAP-fejl, der returneres til opkaldssystemerne.
Det sikrer desuden, at potentielle fejl er logget i fejlloggen og udfører fejllogning af flow-id.
Service Logik for Samtykkeservicen Verifikation
Servicelogikken overholder beslutningsgrafen, der er lavet til godkendelsesbekræftelse (se tidligere afsnit), og den implementeres i klassen ConsentVerificationServiceLogic.
Samtykkeservicen Verifikation
Verifikationen består af tre forskellige operationer: brugerverifikation, dataverifikation og verifikation af udenlandske sundhedspersonale.
Det udenlandske sundhedspersonale er personer, der forsøger at få adgang til en borgeres data gennem epSos. Det er muligt for en borger at registrere positivt samtykke til dette (se tidligere afsnit).
Brugerverfikation bruges til at få en verifikation af, om en bruger kan få adgang til en borgeres data. Det er muligt for et system at kalde til denne service og dermed undgå at lave verifikation af hvert enkelt dataelement.
Hvis 'Positiv' returneres, behøver anvendersystemet ikke at validere samtykke til mulige data, da borgeren har givet samtykke til den kalende bruger til alle data.
Hvis 'Negativ' returneres, behøver det kaldende system ikke at slå op data, da der er oprettet en spærring til den kalende bruger for alle data.
Kun på et 'Dataspecifik' er det nødvendigt for det kaldende system at at kalde 'dataverifikation'.
Dataverifikation bruges til at undersøge, hvilke data i en sekvens af specifikke dataelementer, som brugeren har samtykke eller spærring til at få vist.
Denne metode er kun nødvendig at kalde hvis der er returneret dataspecifik.
Metoden accepterer en liste over mulige dataelementer og returnerer en liste over de dataelementer (fra den modtagne liste), som brugeren har samtykke til at få vist.
Samtykke/Spærring for personer og data
Serviceklassen henter alle borgerens samtykker og spærringer fra databasen og filtrerer disse ved hjælp af klassen ConsentTypeFilterer.
I denne klasse filtreres samtykker og spærringer i relevante enheder svarende til de forskellige trin i beslutningsgrafen (f.eks. spærringeer til brugeren ',' spærring til alle ',' samtykke til brugerorganisationen 'osv.). Filtreringen udføres på registreringerne og mulig tilknyttet 'hvem' element. 'Hvad' elementet undersøges ikke i filtreringen.
Opslag foretages i SORES-tjenesten for at sortere organisationsspecifikke samtykke korrekt.
If user or data verification is performed, then the general consent verification logic will subsequently be performed in the abstract class ServiceLogicHandler that has been implemented by two concrete classes: a class for user verification and a class for data verification. Filtration of consents, order of consent verification, and handling of positive/negative/data specific consents, are identical for both the concrete classes.
General service verification
The general verification algorithm is as follows, where the parenthesized text indicates if the individual step results in a positive, negative or data-specific handling.
In each step, it is examined whether the filtration has found consents that belong to the current category whereupon the stated handling is performed.
For instance, a positive handling is performed if a positive consent is found for the current user in step 2.
’On behalf of’ (step 1) is used when a health professional is working on behalf of another health professional. This could be a medicine student working on behalf of his senior physician or a secretary making lookups for a health professional.
In this case, the algorithm is swiftly executed if positive consent exists towards both users. Otherwise, it is required that if negative consent exists towards only one of the users, no access is allowed to the user’s data.
On behalf of (positive/negative/data-specific)
Positive personal consent for all (positive)
Positive personal consent for specific data (data-specific)
Negative personal consent for all (negative)
Positive consent towards the user’s organization for all (positive)
Positive consent towards the user’s organization for specific data (data-specific)
Negative consent towards anybody for specific data (data-specific)
Negative consent towards anybody for all (negative)
No more consents / no consents registered (positive)
Handling of the individual steps varies between user and data-verification.
User verification
The logic for user verification is simple and will result in either a positive, negative or data-specific answer.
The value for the first handling, where consents are found in the database, is returned to the calling system.
...
Hvis der udføres bruger- eller dataverifikation, udføres den generelle tilladelsesverifikationslogik derefter i den abstrakte klasse ServiceLogicHandler, der er implementeret af to konkrete klasser: en klasse til brugerverifikation og en klasse til dataforifikation. Filtrering af samtykke, bekræftelse af samtykkeordre og håndtering af positive / negative / dataspecifikke samtykke er identiske for begge de konkrete klasser.
Generel service verifikation
Den generelle verifikationsalgoritme er som følger, hvor parentessteksten angiver, om det enkelte trin resulterer i en positiv, negativ eller dataspecifik håndtering.
I hvert trin undersøges det, om filtreringen har fundet samtykke eller spærring, der hører til den aktuelle kategori, hvorpå den angivne håndtering udføres.
For eksempel udføres en positiv håndtering, hvis der findes et samtykke til den nuværende bruger i trin 2.
'På vegne af' (trin 1) bruges, når en sundhedsprofessionel arbejder på vegne af en anden sundhedsperson. Dette kan være en medicinstudent, der arbejder på vegne af hans overlæge eller en sekretær, der søger efter en sundhedsperson.
I dette tilfælde udføres algoritmen hurtigt, hvis der findes samtykke til begge brugere. Ellers kræves det, at hvis der kun findes spærring over for en af brugerne, er der ikke adgang til brugerens data.
- På vegne af (positiv / negativ / dataspecifik)
- Personligt samtykke for alle (positive)
- Personligt samtykke til specifikke data (dataspecifikke)
- Personlig spærring for alle (negativt)
- Samtykke over for brugerens organisation for alle (positive)
- Samtykke over for brugerens organisation for specifikke data (dataspecifikke)
- Spærring over for nogen til specifikke data (dataspecifik)
- Spærring over for enhver for alle (negativt)
- Ikke flere registreringer elller ingen registreringer (positivt)
- Håndteringen af de enkelte trin varierer mellem bruger og data-verifikation.
Bruger verifikation
Logikken til brugerbekræftelse er enkel og vil resultere i enten et positivt, negativt eller dataspecifikt svar.
Værdien for den første håndtering, hvor samtykke eller spærring findes i databasen, returneres til det kaldende system.
'Positiv' returneres, når samtykke findes trin (2, 5), 'Negativt' i de tring hvor der er spærring trin (4,8) og 'Dataspecifikt' i de dataspecifikke trin (3,6,7) .
In step 1, a value is returned that depends on the citizen’s consents towards the person that work is performed on behalf of, and the user calling the service.
Data verification
Consent verification for data sorts the data, where there is negative consent, from the total list of possible data elements. The verification is performed once for each data element.
If positive handling is performed, the element is added to the return list. If negative handling is performed, the element is removed from the list of possible data elements
On a data-specific handling, iteration is performed over the remaining possible data elements and the ’what’-elements of the consents are examined. Comparison is made with the creating organization of the data element and the ’what’-organization provided in the consent:
If no ’what’-element is provided or the ’what’-organization is subject of a positive consent, the element is added to the return list.
If it is the subject of a negative consent, it is removed from the list of possible data elements.
Handling by precautionary principle:
If the creating organization of the data element is of type unknown or other, it is removed when there is negative consent or one or more negative data specific consents with overlapping referral period, unless there is also a positive data specific consent (with overlapping referral period) which applies to any origin (‘what’-organization).
If the creating organization of the data element is of type SHAK or DEA (Danish: ydernummer) and the identifier cannot be looked up as a SOR code, it is treated similarly to the unknown or other organization type described above.
Otherwise, verification continues.
This proceeds until all steps of the verification has been passed or the list of possible data-elements is empty.
The return list (with all the data elements without negative consent) is returned to the calling system.
The handling by precautionary principle is simply, that if a data element is of type unknown or type other, it might represent data from the same organization (‘what’-organization) as that of a negative data specific negative consent. The data element, therefore is eligible for being removed from list. The same does not apply for the positive data specific consent. Although the data element might represent the same organization, the opposite might as well be true. Therefore, positive data specific consent applies only when defined for any origin (any ‘what’-organization).
Error handling
The error handling intercept performs general error handling of all service calls and wraps and ensures that it is only DGWS faults that are returned to the calling systems.
It additionally ensures that potential errors are logged in the error log and performs debug logging of flow ID.
DGWS and security
The DGWS-interceptor performs validation of the security and Medcom headers. It ensures that only authenticated user systems can access the service by authorizing them in a whitelist.
Consent for foreign health professionals
On verification of foreign health professionals, iteration occurs over all the citizen’s consents to examine if one exists towards foreign health professionals (epSos).
If so, the type of the consent is returned (positive/negative). Otherwise, negative is returned, as the citizen specifically must allow access for foreign health professionals.
Min-log Service Client
All calls to the Min-log service is performed through the Min-log service client, based on the loaded configuration (see section 3.2.2).
Call is forwarded to the Min Log service with the same Medcom and security headers, as received by the calling system.
The interface for the Min-log service can be seen in [Min-log].
Integration and Test
Integration Strategy
There is no specific sequence in which the two components must be integrated. However, the Min Log service-client must be available before the consent administration service can be integrated.
For a description of the build process and external/internal depencies for the service, see [UdviklerGuide].
...
I trin 1 returneres en værdi, der afhænger af borgerens samtykke til den person, som arbejdet udføres på vegne af, og den bruger, der kalder tjenesten.
Data verifikation
Samtykkeverifikation returnerer, fra den samlede liste af dataelementer, de elementer der er samtykke til at tilgå. Verifikationen udføres én gang for hvert dataelement.
Hvis der udføres positiv håndtering, tilføjes elementet til returlisten. Hvis der udføres negativ håndtering, fjernes elementet fra listen over mulige dataelementer
På en dataspecifik håndtering udføres iteration over de resterende mulige dataelementer og 'hvad'-elementerne i registreringen undersøges. Sammenligning foretages med oprettelsen af dataelementet og den 'what'-organisation, der er givet i samtykke:
- Hvis der ikke gives noget 'what'-element, eller' what'-organisationen er underlagt et samtykke, føjes elementet til returlisten.
- Hvis det er genstand for en spærring fjernes det fra listen over mulige dataelementer.
- Håndtering efter forsigtighedsprincip:
- Hvis den oprettende organisation af dataelementet er af ukendt eller anden type, fjernes det, når der er rale om en spærring eller en eller flere dataspecifikke spærringer med overlappende henvisningsperiode, medmindre der også er et positivt samtykke (med overlappende henvisningsperiode ), der gælder for enhver oprindelse ('hvad'-organisation).
- Hvis den oprettende organisation af dataelementet er af typen SHAK eller ydernummer, og identifikatoren ikke kan ses som en SOR-kode, behandles den på samme måde som den ukendte eller anden organisationstype beskrevet ovenfor.
- Ellers fortsætter verifikationen.
Dette fortsætter, indtil alle trin i verifikationen er gennmemført, eller listen over mulige dataelementer er tom.
Returlisten (med alle dataelementerne uden spærring) returneres til det kaldende system.
Håndteringen af forsigtighedsprincippet er, at hvis et dataelement er af en ukendt type eller en anden type, kan det repræsentere data fra den samme organisation ('hvad'-organisation) som for en dataspecifikt spærring. Dataelementet er derfor berettiget til at blive fjernet fra listen. Det samme gælder ikke for det dataspecifikke samtykke. Selv om dataelementet muligvis repræsenterer den samme organisation, kan det modsatte lige så godt være tilfældet. Derfor gælder dataspecifikt samtykke kun, når det er defineret for enhver oprindelse (enhver 'hvad'-organisation).
Fejlhåndtering
Fejlhåndterings-interceptoret udfører generel fejlhåndtering af alle servicekald og sikrer, at det kun er DGWS-fejl, der returneres til opkaldssystemerne.
Det sikrer desuden, at potentielle fejl er logget i fejlloggen og udfører fejllogning af flow-id.
DGWS og sikkerhed
DGWS-interceptoren udfører validering af sikkerheds- og Medcom-headere. Det sikrer, at kun godkendte brugersystemer kan få adgang til tjenesten ved at godkende dem i sin whiteliste.
Samtykke til udenlandskesundhedspersonale
Ved verifikation af udenlandske sundhedspersonale itereres der over alle borgerens registreringer for at undersøge om der eksieterer en for udenlandsk sundhedspersonale (epSos).
I så fald returneres typen af registrering (positiv / negativ). Ellers returneres negativt, da borgeren specifikt skal tillade udenlandsk sundhedspersonale adgang.
Min Log Provider
Alle kald til Min-log-servicen udføres via Min Log provider, baseret på den indlæste konfiguration.
National Adviseringsservice (NAS2) modul
Alle kald til NAS2 Notifikation Broker udføres via nas-notification-modulet.
Integration og Test
Integrationsstrategi
Der er ingen specifik rækkefølge, hvor de to komponenter skal integreres. Min Log-serviceklienten skal dog være tilgængelig, før servicen samtykkeadministrationstjeneste kan kaldes.
For en beskrivelse af byggeprocessen og eksterne / interne afhængigheder for servicen se Samtykkeservicen - Guide til Udviklere.
Testspecifikationer
To be able to test the consent administration service, the Min Log-service must be available. It is also possible to test consentadministrationsservicen with a stub for Min Log.
Min Spærring administration
The following three integration test classes exists for the administration service:
- ConsentAdministrationServiceIT
- ConsentAdministrationSecurityIT
- ConsentAdministrationServiceMinLogLoggingIT
The security-class ensures that the service validates and verifies those security tokens that are included in the service request.
The service-class contains those integration tests that verify that the service requirements have been met, in addition to ensuring that OIO-IDWS 1.1 and SLA-logging is implemented correctly.
The MinLog-class ensures that the service logging mechanism using MinLog is implemented correctly.
Consent verification
Two unit test classes exists for the verification service:
ConsentVerificationLogicTest and ConsentForForeignersTest
The verificationLogic-test ensures that the service logic classes has been implemented correctly.
The foreigners-test ensures that the logic that checks for consents for foreign health professionals has been implemented correctly.
Additionally, two integration test classes exists for the verification service:
ConsentVerificationServiceIT and ConsentVerificationSecurityIT
The security-class ensures that the service validates and verifies the security tokens that are included in the service request.
The service class contains those integration tests that verify that the service requirements have been met, in addition to ensuring that DGWS 1.0.1 and SLA-logging is implemented correctly
Common
Log.
Min Log-tjenesten skal være tilgængelig for at kunne teste Samtykkeservicen Administration. Det er også muligt at teste Samtykkeservicen Administration med en stub til Min Log.
Min Spærring administration
Der findes en række klasse med Samtykkeservicen Administration integrationstest. De findes alle i modulet consent-administration-integrationtest.
De klasser der er navngivet med "Security" sikrer, at tjenesten validerer og verificerer de sikkerhedstokener, der er inkluderet i request.
De kalsser der er navngivet med "Service" indeholder de integrationstests, der tester, at servicekravene er opfyldt, ud over at sikre, at OIO-IDWS 1.1 og SLA-logning implementeres korrekt.
MinLog-klassen sikrer, at serviceloggingsmekanismen ved hjælp af MinLog implementeres korrekt.
Samtykkeservicen Verifikation
Der findes en række unit tests til Samtykkeservicen Verifikation. Disse findes alle i modulet consent-verification-app.
Yderlige findes der en række integrationstests. Disse findes i projektet. consent-verification-integrationtest.
De har alle til formål at teste at applikationen fungerer efter hensigten.
Fælles
Yderlige findes der ekstar unit tests i consentservices-common der har til formål at verificere at intercepter og DAO er implementeret korrekt.
Furthermore, there exists a number of unit tests that ensure that the different interceptor-validations and DAOs has been implemented correctly.