...

Introduktion

Purpose

Formål

MinSpærring servicen er en The consent service is a national service for administration and verification of citizens’ consents for health professionals to access their information in (the national) health systems.

The purpose of this document is to describe the system architecture for the consent service.

For an overview of the system, refer to section 5.1.1.

Reading Guide

...

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 servicen.

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

Definitions and References

Definitiner og referencer

Formålet med dette afsnit er at give en oversigt over definitioner og dokumentreferencer, der bruges i dette dokumentThe purpose of this section is to provide an overview of definitions and documents references used in this document.

...

MinSpærring Services

...

Baggrund

The basis for Consent Service is as followsGrundlaget for samtykke service er som følger::

”The health act contains stipulations regarding a citizens’ right to decline retrieval or disclosure of information. In regard to electronic retrieval of patient information, the patient must be briefed about his right to decline retrieval, but it is not required that the patient’s consent is requested on the actual retrieval. In the remarks to the law, it is stated that this right must be supported electronically in new IT solutions, i.e. the patient or a health professional acting on behalf of the patient must be able to mark which information to which access is declined.

...

Web Service for registration and lookup / control of consent information.”

The requirements that consent services must fulfil are elaborated in Kravene, som MinSpærring skal opfylde, er uddybet i [Behov]. The legal foundation is described in Det juridiske grundlag er beskrevet i [Sundhedsloven] with corrections given in med rettelser givet i [Ændring af sundhedsloven].

Overview of the Solution

Two web services are established for this solution, the Consent Administration Service and the Consent Verification Service.

...

Overblik over løsningen

MinSpærring udstiller to services. Det er MinSpærring Administration og MinSpærring 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 borgerConsentRegistrationsGet – Returns all consent registrations for a citizen.
  

• ConsentAdd – Creates a new consent for a citizen. A consent is, as specified in [Data Model] section 2.1, provided with:

• Type (positive/negative)

• What it covers

• For whom it applies

• A validity period

The operation can be called by both the citizen and by another person that the calling system has verified can create the consent in question on behalf of the citizen.

The operation additionally supports creation of positive consent for foreign health professionals access to data.

• ConsentModify – Modifies a consent for a citizen. The consent/modifications are stated as for new consents.

• ConsentRevoke – Revokes a consent, so it is no longer valid.

If user and citizen is not the same person in those operations, that allow so, the action is logged in the citizen’s My Log (Danish: Min Log).

...

• 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.

Consent Verification Service

Allows examination of the consent relationship between a citizen and a health professional. The service exposes the following operations:

...

Empowerment (Danish: Bemyndigelse) is a state where one health care professional is working on behalf of another. The health care professional worked on behalf of is typically held accountable for the actions performed by the former.

Common to Consent Services

Both services comply with Den Gode Web Service 1.0.1, and require:

...

It is the responsibility of the calling system to ensure that the user is authenticated and authorized.

Scope for Deployment and Database

As depicted in Figure 3, consents are stored in a central database which is replicated to databases on NSP instances.

...

Figure 3 Deployment of Consent Services.

Design Goals and Decisions

Design Goals

The system must be designed in alignment with the goals and priorities stated in Table 1. The priority of each goal is indicated with a score of 1 to 5 where 5 indicates the highest priority.

...

Table 1: Design goals and their mutual importance

Design Decisions

This section holds significant design decisions and their rationale. If relevant, rejected designs are also presented with the rationale for their rejection.

Decision regarding logging

Error and debug logging is implemented using log4j that is configured for each individual service. As a rule, one log file is created per service.
In this log, exceptions and stack traces for possible errors are logged. If the configuration is set to ’debug’-level, a trace of flowID on entry/exit of the service methods is additionally logged.

...

Type of use refers to the method call.

Decision concerning configuration

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.

...

All data sources must support distributed transactions (xa-datasource).

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.

...

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 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.

...

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 database operations are implemented by means of the Hibernate framework.

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.

...

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.

...

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.

...

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.

...

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).

...

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].

Test Specifications

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.

...