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.
In the document, the concepts of authorization and authorized are used primarily in a security context, that is, in the understanding that a person or a system is authorized to use a given resource. If the concepts are applied towards health professionals with Danish authorization listed in Danish Health Authority’s authorization register, it will be stated explicitly.
| 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 |
The purpose of this section is to provide an overview of definitions and documents references used in this document.
| Definition | Description |
|---|---|
NSI | National eHealth Authority |
NSP | National Service Platform (within health care) |
| Reference | Description |
|---|---|
Behov | National consentservice, v1.1 (behovsbeskrivelse for Min Spærring Service) |
Data Model | Consent Services Data Model (SSE/11734/DDD/0003) |
Consent Administration Interface Description | Consent Administration Service Interface Description (SSE/11734/IFS/0013) |
Consent Verification Interface Description | Consent Verification Service Interface Description (SSE/11734/IFS/0014) |
Operator’s Handbook | Driftsvejledning Min Spærring Services (SSE/11734/OHB/0002) (Consent Services Operator’s Handbook, available in Danish only). |
Min-log | Snitfladebeskrivelse Min-log Web services (SSE/11734/IFS/0003) (Min-log Service Interface Description, available in Danish only). |
UdviklerGuide | Guide til Udviklere Min Spærring Service (SSE/11734/PHB/0007) (Consent Services Developer’s Guide, available in Danish only). |
HSUID-Header | Healthcare Service User Identification Header (SSE/11734/IFS/0018) |
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) |
The basis for Consent Service is as follows:
”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.
…
The consent service that is developed in connection with the NPI (National Patient Index) project should be viewed as the first draft. The consent service must be shared between NSP and the Health Journal and should consequently be developed in collaboration with Sundhed.dk and the architecture should support future extension of interface and functionality.
Specifically, the consent functionality in the NPI project must contain the following components:
A database with a simple data model for storage of negative and positive consent
Web Service for registration and lookup / control of consent information.”
The requirements that consent services must fulfil are elaborated in [Behov]. The legal foundation is described in [Sundhedsloven] with corrections given in [Ændring af sundhedsloven].
Two web services are established for this solution, the Consent Administration Service and the Consent Verification Service.
Allows registration and maintenance of submitted consents for the citizen. The service expose the following operations
ConsentRegistrationsGet – 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).
The consent administration service Min Spærring administrationsservice hold in its data model information concerning the consent, as stated by ConsentAdd above, in addition to information about who and when the consent is respectively created and modified.
Allows examination of the consent relationship between a citizen and a health professional. The service exposes the following operations:
ConsentForUserCheck – Returns the general consent relationship for a user in regard to a citizen; if the user is allowed to view all or nothing about the citizen.
ConsentForDataCheck – Returns the specific consent relationship for a user and concrete information in regard to a citizen; if the user is allowed to view these concrete informations about the citizen. The concrete information/documents are described strictly using document metadata.
ConsentForForeignersCheck – Returns whether foreign health professionals can access Patient Summary and Electronic Prescription for the citizen through epSos
Together with the calling health service, the consent verification service follows the following decision graph to determine a citizens’ / health professionals access to data:
Figure 1 (In Danish) State diagram for initial decision on granting access to health care information about at citizen.
For an individual/citizen it is only verified that the citizen is authenticated and that own data can be accessed.
For health professionals, the following decision graph is used to verify consents:
Figure 2 State diagram for consent verification steps when granting access for a health care professional to health care information about a citizen. References in parenthesis refer to [Sundhedsloven].
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.
Both services comply with Den Gode Web Service 1.0.1, and require:
That the calling system is authenticated by the STS on NSP with at least security level 3
That the calling system is authorized, which is checked through a whitelist
It is the responsibility of the calling system to ensure that the user is authenticated and authorized.
As depicted in Figure 3, consents are stored in a central database which is replicated to databases on NSP instances.
The consent administration service is deployed on a central server and exposed on NSP instances through the decoupling component DCC. The proxy for the administration service used on an NSP instance is not implemented as part of this service. The proxy is established on the NSP in the form of a configuration of the DCC.
The consent verification service is deployed only on the NSP instances and queries on the local database copies.
Import of SOR data to the master database is handled by an external importer component, not as part of this service.
Figure 3 Deployment of Consent Services.
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.
| Goal | Priority | Comment |
|---|---|---|
Correctness | 5 | The overall functionality concerns patient safety and is subject to an extensive legal framework that is important to obey |
Reliability | 2 | If the system cannot performs its task, the error must be forwarded. |
Usability | 1 | No user interface |
Security | 4 | The system handles patient data |
Performance | 3 | The specific performance requirements are not known as the strain of the system is unknown, but performance has been prioritized, as the system is part of calls to other systems |
Maintainability | 4 | The solution will certainly be subject to further development. The cost of this must be kept low |
Flexibility | 1 | The solution consists of Web services. This results in the necessary flexibility in the overall system. The individual services do not have to be flexible. |
Testability | 3 | The solution has to be testable through automatic tests, as there is no user interface. |
Portability | 1 | The fundamental technology decisions has been made. |
Reusability | 2 | The components must be used through delegation – not by code reuse. |
Interoperability | 2 | The desired interoperability is obtained through Web service interfaces |
Table 1: Design goals and their mutual importance
This section holds significant design decisions and their rationale. If relevant, rejected designs are also presented with the rationale for their rejection.
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.
The debug logging has been implemented to facilitate troubleshooting, such that a flowID (and consequently a message) can be traced between service calls.
Service Level Agreement (SLA) logging is supported with the aid of the (SLA) logging functionality in NSPUtil.
The SLA-logging logs all calls to the two services and consists among other things of:
Time of call, name of the invoked method, temporal length of call, ID of the message that is processed.
Audit logging also takes place through log4j, for the category ”audit”. Audit logging must log
Time (zulu time)
User-ID
Type of use
The citizen
Company registration number of calling system
Session-ID from DGWS
Type of use refers to the method call.
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.
Changes in the configuration should prompt a reboot of the service, as the configuration is loaded and verified on start-up of the individual services.
For a description of what must be set-up in the configuration, see [Driftsvejledning].
Application configuration
The application is configured in the files ConsentAdministration.properties and ConsentVerification.properties.
All configuration of security and service setup is provided in these files.
Additionally, the location of the log configuration file and the service client configuration is provided.
In this way it is possible to configure logging and client setup independently of the service, e.g. on re-use of the log configuration between services.
Service client configuration
The consent administration service must be able to communicate with the Min Log’-service and the configuration of the service client that is used must also be performed in a configuration file.
The location of this file is provided in the application configuration.
Log configuration
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.
Database configuration
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].
Furthermore, the consent verification service must have access to a data source with the name ’SORDS’, that has access to the SOR-database.
Both services must have access to a data source with the name ’WhitelistDS’ that is used by whitelist validation of calling systems.
All data sources must support distributed transactions (xa-datasource).
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]).
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, security handling and logging is handled by Java EE interceptors that are automatically invoked by the surrounding EJB container.
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 SOR-database is likewise injected from the container.
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.
The data model for consent service is documented in [Data Model].
This section describes static as well as dynamic aspects of the system architecture, including the basis for the individual design choices.
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.
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.
The database operations are implemented by means of the Hibernate framework.
SORLookupDAO
Is handled as a Java data source, that is injected through the annotation @Resource. It makes use of the data source ’SORDS’.
The DAO exposes methods that allows the bean to convert between SOR-codes and SHAK-codes/provider-numbers in addition to performing lookups in the SOR-hierarchy.
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
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.
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).
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.
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.
Lookups are performed in the SOR database to sort organization-specific consents correctly.
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.
’Positive’ is returned when consents are found in a positive step (2, 5), ’Negative’ in the negative steps (4,8) and ’Data-specific’ in the data-specific steps (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).
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.
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].
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].
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
Two integration test classes exists for the administration service:
ConsentAdministrationServiceIT and ConsentAdministrationSecurityIT
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 DGWS 1.0.1 and SLA-logging 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
Furthermore, there exists a number of unit tests that ensure that the different interceptor-validations and DAOs has been implemented correctly.