Consent Services
User’s Guide
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 1 of 10
Contents
1
2
3
Introduction ........................................................................................................ 3
1.1
Purpose ...................................................................................................... 3
1.2
Reading Guide ............................................................................................ 3
1.3
Document History........................................................................................ 3
1.4
Definitions and References ......................................................................... 3
Interface Description .......................................................................................... 5
2.1
Common ..................................................................................................... 5
2.2
Consent verification..................................................................................... 5
2.3
Consent administration ............................................................................... 7
Examples of Calling Services ............................................................................. 8
3.1
Service Clients ............................................................................................ 8
3.1.1
Creation of service client ...................................................................... 8
3.1.2
Properties ............................................................................................ 9
3.1.3
Headers ............................................................................................... 9
3.2
Example of Call to Consent Verification ...................................................... 9
3.3
Example of Call to Consent Administration................................................ 10
3.4
Client Generation from WSDL ................................................................... 10
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 2 of 10
1 Introduction
1.1 Purpose
This document describes the usage of the web services that are made available by
consent services, which consists of two independent services: consent administration
and consent verification.
The document provides an introduction to the general Web service interface for both
services, in addition to examples on how they can be used in a specific user system.
Where the services overlap, common functionality is only described once.
1.2 Reading Guide
This document is directed towards developers and architects that will be using consent
service on NSP. It is assumed that the reader is familiar with Web services and the
additional components on the NSP such as STS, in addition to knowing about Den
Gode Web service (DGWS).
1.3 Document History
Version
Date
Responsible
Description
1.0
29.06.2012
Systematic
Initial version
1.1
28.11.2014
Systematic
References to National Patient Index
(NPI) removed
1.2
07.09.2016
Systematic
Description of additional conditions for
data specific consent check (paragraph
2.2)
1.3
07.12.2016
Systematic
Consent services now support DCC –
(paragraph 3.1.1 and 3.1.2)
Changed sts.endpoint to new endpoint in
example properties file
1.4 Definitions and References
Definition
Description
NSI
National eHealth Authority
NSP
National Service Platform (within health care)
SHAK
Hospital Department Classification
SOR
Health Service Organization Register
STS
Security Token Service
Reference
Description
DGWS 1.0
Den Gode Webservice 1.0
DGWS 1.0.1
Den Gode Webservice 1.0.1
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 3 of 10
Reference
Description
HSUID-header
Healthcare
Service
(SSE/11734/IFS/0018)
Consent
Administration
Interface
Description
Consent Administration Service Interface Description
(SSE/11734/IFS/00013)
Consent
Verification
Interface
Description
Consent
Verification
(SSE/11734/IFS/0014)
Data Model
Consent Services Data Model (SSE/11734/DDD/0003)
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
User
Service
Identification
Interface
Header
Description
Page 4 of 10
2 Interface Description
The web service interfaces for the two services are described in details in the
associated interface descriptions [Consent Administration Interface Description] and
[Consent Verification Interface Description].
In this section, only the individual components that are necessary to describe the
usage of the two services are clarified.
2.1 Common
Security header
To call consent services, a user system must obtain a certificate and an ID card of
level 3, issued by STS, and add these to the security header.
It should furthermore be ensured that one has a stated company registration number
and that it is on the whitelist of authorized system. The two services use different
whitelists, so the company registration number must be added to one or both,
depending on which service one wants to call.
Medcom header
In the Medcom header it must be ensured that the flowID is set correctly. If consent
services are called from another Web service with a Medcom header, the flowID must
be retained from this call.
The Medcom header is returned from all method calls as it is set as an In/Out
parameter with flowstatus updated to ’finalized successfully’.
HSUID header
Finally, the HSUID header must be filled in with identification of the user that performs
a given operation. Some of this information is possibly reused in the body of the
message and these must of course be consistent (cf. [Consent Administration Interface
Description] and [Consent Verification Interface Description]).
2.2 Consent verification
The verification service has two methods to verify consent of a health professional:
ConsentForUserCheck and ConsentForDataCheck.
The purpose of the ConsentForUserCheck-method is that it makes it possible for a
user system to verify quickly whether a user has general positive or general negative
consent.
If the method returns positive or negative, then it is not necessary to search or request
again with the data found about the citizens.
On a positive response, the user system will assume that the user has consent to see
the health data concerning the citizen for which the consent database is responsible.
Conversely, on a negative response, the assumption is that the user has negative
consent towards all data concerning the citizen.
The ConsentForDataCheck-method accepts a list of metadata elements and filter them
based on the citizen’s consents.
If the ID’s are SHAK or DEA codes consent verification tries to lookup the related SOR
codes which will be compared to the users consents.
In addition, if a negative data specific consent has been specified for an organization
the hierarchical parents to that organization are included in that consent. Unless a
specific positive consent is given.
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 5 of 10
This is illustrated in the following examples. Figure 1 shows citizen who has a general
positive consent but has made a data specific negative consent on the organization
“Org”. If identifiers from all four organizations are sent to consent verification the
diagram shows the response where red is a negative consent and green is a positive
consent.
Figure 1: Specific negative on ”Org” which has impact on the parent
But on the other hand if the citizen has made a general negative consent and made a
specific positive consent for data from “Org” for a given user, the parent organization
is not affected by the consent. See Figure 2.
Figure 2: Specific positive on ”Org” does not impact parent
Those metadata whose IDs are returned from the service are the metadata the user
has a positive consent to view.
It is the user systems responsibility to ensure that the used IDs are unique so that they
can be distinguished in the returned list. The service does not use the IDs for anything
else than the return list.
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 6 of 10
2.3 Consent administration
Create- edit- and delete-methods all accept consent-objects (Consent) as parameters.
The contents of a consent-object, in addition to which options are allowed, are shown
in [Data Model] section 2.
All methods in the consent administration allows the citizen who creates a consent (or
deletes/modifies) to be different from the citizen that the consent concerns.
This means that a citizen can create/edit/delete consents on behalf of another citizen
as long as the citizen is authorized to do so.
Likewise, it is possible for a health professional to create a consent (but not edit or
delete) on behalf of a citizen.
It is the user system’s responsibility that the user is authenticated and authorized to
perform an action on behalf of another.
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 7 of 10
3 Examples of Calling Services
In this section, examples are provided on how one can use a Java-based user system
to call the two services.
The code example is taken from the integration tests for the service and both method
calls, variables and parameters come from this context.
The code might possibly not be able to compile or run its current form, as it is only
intended as a guide on how to construct a call to the service.
3.1 Service Clients
A service client has been developed for each service which can be found as Mavencomponents:
<dependency>
<groupId>dk.nsi.consentservices.verification</groupId>
<artifactId>consent-verification-client</artifactId>
<version><desired client version></version>
</dependency>
and:
<dependency>
<groupId>dk.nsi.consentservices.administration</groupId>
<artifactId>consent-administration-client</artifactId>
<version><desired client version></version>
</dependency>
3.1.1 Creation of service client
These service clients are configured using a property file, and the client takes care of
obtaining a valid STS-token, creating proper headers etc.
Properties for the client are set up through the ClientConfig-class that accepts the
name of the properties file in which the configuration is found. The properties-file must
be found on classpath.
The code below creates a port for the verification service:
Config config = new ClientConfig("VerificationClient").
addRequiredKeys(ConsentVerificationService.CONFIG_KEY,
ConsentVerificationService.CONFIG_ENDPOINT);
URL wsdl =
new URL(config.getProperty(ConsentVerificationService.CONFIG_KEY));
String wsendpoint = config.getProperty(ConsentVerificationService.CONFIG_ENDPOINT);
ConsentVerificationServiceservice =
new ConsentVerificationService (config, wsdl);
service.initialise();
ConsentVerification port = service.getConsentVerificationPort(wsendpoint);
This presupposes that a VerificationClient.properties-file can be found on classpath.
Similar code create a client for the administration service, the client is just the class
ConsentAdministrationService instead and the call results in a port defined in the class
ConsentAdministration.
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 8 of 10
3.1.2 Properties
The properties file provided for the service client, must define a number of properties
that the client uses to communicate with the service (the values must be adjusted so
that they are relevant to the user system):
administration.wsdl.location = http://localhost:8080/consent-administration/service?wsdl
administration.service.url = http://localhost:8080/consent-administration/service
verification.wsdl.location = http://localhost:8080/consent-verification/service?wsdl
verification.service.url = http://localhost:9090/consent-verification/service
idcard.level = 3
idcard.system.name = TESTSTS
idcard.subject.id.type = medcom:cvrnumber
idcard.subject.id = 19343634
idcard.subject.name = JERNALDERBYENS VENNER
sts.test.mode = false
sts.endpoint = http://test1.ekstern-test.nspop.dk:8080/sts/services/NewSecurityTokenService
sts.token.expiry.threshold = 60
sts.keystore = jks/validVocesVault.jks
sts.keystore.password = !234Qwer
cert.expires.in.warning = 30
(the values are taken from the integration tests and must possibly be changed to
function in another context).
The values for the security certificate must be corrected to the certificate one is using.
It is only necessary to provide one wsdl-location for each service.
3.1.3 Headers
Subsequently, service and port can be used to create the necessary headers, so the
service can be called.
A flowID is provided with the headers, see section 2.1.
DGWSHeaderWrapper signedHeaders = service.getSignedHeaders(flowID);
Holder<Header> medcomHeader =
new Holder<Header>(signedHeaders.getMedcomHeader());
HsuidHeader hsuidHeader = createHsuidHeader();
The values in the HSUID-header must be set manually by calling a method that creates
the object (see [HSUID-header] for a description of the header contents).
The Medcom header is wrapped in a holder-object as it is an In/Out parameter.
3.2 Example of Call to Consent Verification
An example of call to ConsentForDataCheck on the verification service is shown here.
List<ConsentDataRegistration> consentData; // the list must be populated elsewhere
ConsentForDataCheck consentForDataCheck =
new ConsentForDataCheck(citizen, healthcareProfessional, onBehalfOf,
organization, consentData);
ConsentForDataResponse consentForDataCheckResponse =
PORT.ConsentForDataCheck(consentForDataCheck, medcomHeader,
signedHeaders.getSecurityHeader(), hsuidHeader);
The element consentData has to be a list of ConsentDataRegistration-objects, see
[Consent Administration Interface Description] and [Consent Verification Interface
Description]:
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 9 of 10
The return value contains the IDs of the data elements that the user
healthcareProfessional has consent from the citizen citizen to view.
3.3 Example of Call to Consent Administration
Shown here is an example of a call to ConsentAdd on the administration service (the
contents of the actual consent-object is not shown here):
Consent consentItem = new Consent();
consentItem.setCitizenCPR(citizen);
consentItem.setPositiveConsent(positive);
consentItem.setValidFromDate(validFrom);
consentItem.setValidToDate(validTo);
consentItem.setWho(who);
consentItem.setWhat(what);
PORT.ConsentAdd(Arrays.<Consent>asList(consentItem), medcomHeader,
signedHeaders.getSecurityHeader(), hsuidHeader);
3.4 Client Generation from WSDL
It is of course also possible to use runtime WSDL-generation against a deployed
service as a starting point.
Consent Services, version 1.3
SSE/11734/PHB/0035 $Revision: 1.6$ $Date: 16 Dec 2016$
Page 10 of 10