Page History
| Navitabs | ||||
|---|---|---|---|---|
| ||||
| Table of Contents |
|---|
Introduction
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.
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).
Document History
Introduktion
Dette dokument henvender sig til udviklere og arkitekter, der vil anvende samtykkeservice på NSP. Det antages, at læseren er fortrolig med webservices og de yderligere komponenter på NSP såsom STS, udover at have kendskab til Den Gode Webservice (DGWS).
Dokument historik
| Version | Dato | Ansvarlig | Beskrivelse |
|---|---|---|---|
1.0 | 29.06.2012 | Systematic | Initial version |
| 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 | 13.06.2018 | Systematic | Migrated to NSPOP SVN |
| 22.10.2018 | KIT | Document moved from Word to Confluence. Original document name was: PHB0035 Consent Services Users Guide.docx |
Definitions and References
| 12.11.2020 | KIT | Oversættelse fra engelsk til dansk | |
| 17.12.2021 | KIT | Tilføjet request/response eksempler for Samtykkeservicen Administration |
Definitioner og referencer
| Definition | Beksrivelse | Definition | Description |
|---|---|---|---|
NSI | National eHealth AuthoritySundheds IT | ||
NSP | National Service Platform (within health care) | ||
SHAK | Hospital Department ClassificationSygeHusAfdelingsKode | ||
SORHealth Service Organization Register | Sundhedsvæsnets Organisationsregister | ||
STS | Security Token Service |
| Reference | DescriptionBeskrivelse | |
|---|---|---|
DGWS 1.0 | Den Gode Webservice 1.0 | |
DGWS 1.0.1 | Den Gode Webservice 1.0.1 | |
HSUID-header | Healthcare Service User Identification Header (SSE/11734/IFS/0018) | Consent Administration Interface Description |
Consent Verification Interface Description | Consent Verification Service Interface Description (SSE/11734/IFS/0014) | |
Data Model | Consent Services Data Model (SSE/11734/DDD/0003) |
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.
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]).
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.
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.
MinSpærring - Verifikation Service Interface Beskrivelse | Samtykkeservicen - Verifikation Service Interface Beskrivelse |
MinSpærring - Administration Service Interface Beskrivelse | |
Data Model |
Interface Beskrivelse
Snitfladerne for de to services er beskrevet i detaljer i dokumenterne Samtykkeservicen - Verifikation Service Interface Beskrivelse og MinSpærring - Administration Service Interface Description.
I dette afsnit er kun de enkelte komponenter, der er nødvendige for at beskrive brugen af de to tjenester beskrevet.
Fælles
Security header
For at kalde de to Samtykkeservicen services skal der anvendes et niveau 3 ID-kort udstedt af STS'en.
Det skal desuden sikres, at man har et angivet CVR-nummer og at dette er whitelisted i servicen. De to services bruger forskellige whitelisting tabeller, så CVR-nummer skal føjes til den ene eller begge, afhængigt af hvilken tjeneste man vil tilgå.
Der findes en admin-snitflade (til Samtykkeservicen administrationsservices), som er tilgængelig for sundhedspersoner, der er autentificeret med et niveau 4 ID-kort og som besidder den nationale rolle 'urn:dk:healthcare:national-federation-role:code:41001:value:SundAssistR1'.
Medcom header
I Medcom-headeren skal det sikres, at Flow-ID er sat korrekt. Hvis servicene kaldes fra et andet system der også anvender DGWS skal Flow-ID bevares fra dette opkald.
Medcom-headeren returneres fra alle operationer da den er indstillet som en ind / ud-parameter med flowstatus opdateret til 'afsluttet med succes'.
HSUID header
Hvis brugeren er en sundhedsfaglig person skal HSUID-headeren udfyldes med identifikation af den bruger, der udfører en given operation. Nogle af disse oplysninger genbruges muligvis i selve meddelelsen, og disse skal naturligvis være konsistente (jf. Samtykkeservicen - Verifikation Service Interface Beskrivelse og MinSpærring - Administration Service Interface Description). HSUID header skal ikke angives i admin-snitfladen og autentifikation og autorisation baserer sig udelukkende på oplysningerne i ID kortet.
Er det borgeren selv der ændre sine spærringer må HSUID-headeren gerne være tom (null) da de oplysninger der skal bruges fra headeren allerede findes i IDWS billetten.
Samtykkeservicen Verifikation
Samtykkeservicen Verifikation har to operationer til at verificere samtykke fra en sundhedsfaglig: ConsentForUserCheck og ConsentForDataCheck.
Formålet med ConsentForUserCheck-operationen er, at gøre det muligt for et brugersystem hurtigt at kontrollere, om en bruger har generelt samtykke eller generel spærring.
Hvis operationen vender tilbage positiv eller negativ, er det ikke nødvendigt at kalde yderlige for at afgøre om en sundhedsfaglig har lov til at tilgå data.
På et positivt svar antager brugersystemet, at brugeren har samtykke til at se sundhedsdata vedrørende den borger, som Samtykkeservicen databasen er ansvarlig for. Omvendt antages det på et negativt svar, at borgeren har oprettet en spærring vedrørende adgang til data.
Operationen ConsentForDataCheck accepterer en liste over metadataelementer og filtrerer dem baseret på borgerens samtykke eller spærring.
Hvis ID'erne er en SHAK-kode eller et Ydernummer forsøger verifikations servicen at slå de relaterede SOR koder op som vil blive anvendt i forbindelse med brugeresn spærring eller samtykke.
Derudover, hvis der er angivet en dataspecifikt spærring til en organisation, inkluderes de hierarkiske forældre til den organisation i dette samtykke. Medmindre der er givet et specifikt samtykke.
Dette illustreres i de følgende eksempler. Figur 1 viser borger, der har et generelt samtykke, men som har givet en dataspecifikt spærring til organisationen "Org". Hvis organisations id'er fra alle fire organisationer sendes til Samtykkeservicen Verifikation viser diagrammet svaret hvor rød er spærring og grøn er samtykke.
Figur 1: Spærring på ”Org” der har indflydelse på den overliggende organisation.
På den anden side, hvis borgeren har oprettet en general spærring og givet et specifikt samtykke til data fra "Org" for en given bruger, påvirkes overliggende organisation ikke. Se figur 2.
Figur 2: Specikt samtykke på ”Org” påvirker ikke overliggende organisation.
De ID'er der returneres fra servicen er de data som anvenderen har samtykke til at få vist.
It is the user systems responsibility to ensure that the used IDs are unique 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 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.
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.
Service Clients
A service client has been developed for each service which can be found as Maven-components:
| Code Block | ||
|---|---|---|
| ||
<dependency>
<groupId>dk.nsi.consentservices.verification</groupId>
<artifactId>consent-verification-client</artifactId>
<version><desired client version></version>
</dependency> |
and:
| Code Block | ||
|---|---|---|
| ||
<dependency>
<groupId>dk.nsi.consentservices.administration</groupId>
<artifactId>consent-administration-client</artifactId>
<version><desired client version></version>
</dependency> |
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:
| Code Block |
|---|
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.
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):
| Code Block |
|---|
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.
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.
| Code Block |
|---|
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.
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]:
The return value contains the IDs of the data elements that the user healthcareProfessional has consent from the citizen citizen to view.
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);
Client Generation from WSDL
...
.
Det er anvendersystemets ansvar at sikre, at de anvendte ID'er er unikke, så de kan skelnes på den returnerede liste. Tjenesten bruger ikke ID'erne til andet end returlisten.
Samtykkeservicen Administration
Opret- rediger- og sletoperationer accepterer alle samtykke/spærring-objekter som parametre. Indholdet af et objektet vises i MinSpærring - Datamodel afsnit 2.
Alle metoder i administrationen af samtykke og spærringer tillader den borger, der opretter en registrering (eller sletter / ændrer), at være forskellig fra den borger, som registreringen vedrører.
Dette betyder, at en borger kan oprette / redigere / slette registretring på vegne af en anden borger, så længe borgeren har tilladelse til det.
Ligeledes er det muligt for en sundhedsfaglig at oprette et samtykke eller spærring (men ikke redigere eller slette) på vegne af en borger.
Det er brugersystemets ansvar, at brugeren er godkendt og autoriseret til at udføre en handling på vegne af en anden.
Admin-snitfladen er til brug for sundhedsfaglige til hjælp for ikke digitale borgere. Sundhedsfaglige har i denne snitflade adgang til alle administrative services: Opret, rediger, slet og hent.
Notificeringer i NAS
| Anchor | ||||
|---|---|---|---|---|
|
For alle ændringer af en borgers spærringer (oprettelse, opdateringer og sletninger), sker der en notificering via NAS få sekunder efter ændringen er gemt. Se evt. NAS 2.0 Anvenderguide.
De enkelte notificeringer indholder ikke detaljer vedr. opdateringen eller spærring, men udelukkende oplysninger om det cprnummer, for hvilket opdateringen har fundet sted. Det er efterfølgende op til anvenderen at hente ændringerne ud via snitfladerne.
Følgende er et eksempel på en opdateringsnotificering:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<ns2:Body>
<ns8:Notify>
<ns8:NotificationMessage>
<ns8:TopicDialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple">MinSpærringTopic</ns8:Topic>
<ns8:Message>
<ns13:NotifyContentid="1208643298"idType="http://nsi.dk/advis/v10/CPR">
<ns14:ConsentUpdatedxmlns:ns14="http://nsp.dk/consent/2021/04/12">
<datevalue="2021-04-21"/>
<versionvalue="1"/>
</ns14:ConsentUpdated>
</ns13:NotifyContent>
</ns8:Message>
</ns8:NotificationMessage>
</ns8:Notify>
</ns2:Body> |
Topic der anvendes: http://sundhedsdatastyrelsen.dk/ConsentAdministration/2021/03/01:ConsentUpdated
Eksempler
I dette afsnit gives eksempler på, hvordan man kan bruge et Java-baseret systemet til at kalde de to services.
Kodeeksemplet er taget fra integrationstestene for servicen, og begge metodekald, variabler og parametre kommer fra integrationstesten.
Koden kan muligvis ikke være i stand til at kompilere eller køre i sin nuværende form, da den kun er beregnet som en guide til, hvordan man opretter et kald til tjenesten.
Eksempler på IDWS kald request og response
ConsentModifications
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version='1.0' encoding='UTF-8'?> <soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header
.. soap headers fjernet for overskueligehed...
</soap:Header>
<soap:Body
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"
wsu:Id="body">
<ns4:ConsentModifyConstraint
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04">
<ConsentModifications
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns2:consentId>
123498765532454
</ns2:consentId>
<ns2:citizenCPR>
1110734334
</ns2:citizenCPR>
<ns2:who>
<ns2:healthProfessionalCPR>
0307702555
</ns2:healthProfessionalCPR>
<ns2:includeSubOrganizations>
false
</ns2:includeSubOrganizations>
<ns2:foreignHealthProfessionals>
false
</ns2:foreignHealthProfessionals>
</ns2:who>
<ns2:what
xsi:nil="true"/>
<ns2:validFromDate>
2021-12-18T00:00:00.000+01:00
</ns2:validFromDate>
<ns2:validToDate>
2021-12-07T00:00:00.000+01:00
</ns2:validToDate>
</ConsentModifications>
</ns4:ConsentModifyConstraint>
</soap:Body>
</soap:Envelope>
|
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soapenv:Header
.. soap headers fjernet for overskueligehed...
</soapenv:Header>
<soap:Body
wsu:Id="body">
<ns4:ConsentModifyConstraintResponse
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"/>
</soap:Body>
</soap:Envelope> |
ConsentAddConstraint
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header
.. soap headers fjernet for overskueligehed...
</soap:Header>
<soap:Body
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"
wsu:Id="body">
<ns4:ConsentAddConstraint
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04">
<ConsentAdds
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns2:citizenCPR>
0804610417
</ns2:citizenCPR>
<ns2:who>
<ns2:healthProfessionalCPR>
0307702555
</ns2:healthProfessionalCPR>
<ns2:includeSubOrganizations>
false
</ns2:includeSubOrganizations>
<ns2:foreignHealthProfessionals>
false
</ns2:foreignHealthProfessionals>
</ns2:who>
<ns2:what
xsi:nil="true"/>
<ns2:validFromDate>
2021-12-17T07:35:51.906+01:00
</ns2:validFromDate>
<ns2:validToDate
xsi:nil="true"/>
</ConsentAdds>
</ns4:ConsentAddConstraint>
</soap:Body>
</soap:Envelope>
|
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soapenv:Header
.. soap headers fjernet for overskueligehed...
</soapenv:Header>
<soap:Body
wsu:Id="body">
<ns4:ConsentAddConstraintResponse
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"/>
</soap:Body>
</soap:Envelope> |
ConsentAddPositive
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header
.. soap headers fjernet for overskueligehed...
</soap:Header>
<soap:Body
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"
wsu:Id="body">
<ns4:ConsentAddPositive
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04">
<ConsentAdds
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns2:citizenCPR>
0804610417
</ns2:citizenCPR>
<ns2:who>
<ns2:healthProfessionalCPR>
0307702555
</ns2:healthProfessionalCPR>
<ns2:includeSubOrganizations>
false
</ns2:includeSubOrganizations>
<ns2:foreignHealthProfessionals>
false
</ns2:foreignHealthProfessionals>
</ns2:who>
<ns2:what
xsi:nil="true"/>
<ns2:validFromDate>
2021-12-17T07:35:52.133+01:00
</ns2:validFromDate>
<ns2:validToDate>
2022-02-05T00:00:00.000+01:00
</ns2:validToDate>
</ConsentAdds>
</ns4:ConsentAddPositive>
</soap:Body>
</soap:Envelope> |
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soapenv:Header
</soapenv:Header>
.. soap headers fjernet for overskueligehed...
<soap:Body
wsu:Id="body">
<ns4:ConsentAddPositiveResponse
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"/>
</soap:Body>
</soap:Envelope>
|
ConsentRevoke
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header
.. soap headers fjernet for overskueligehed...
</soap:Header>
<soap:Body
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"
wsu:Id="body">
<ns4:ConsentRevoke
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04">
<ConsentRevocations>
<ns2:consentId>
123498765532463
</ns2:consentId>
<ns2:citizenCPR>
1110734334
</ns2:citizenCPR>
<ns2:positiveConsent>
false
</ns2:positiveConsent>
<ns2:who>
<ns2:healthProfessionalCPR>
0307702555
</ns2:healthProfessionalCPR>
<ns2:includeSubOrganizations>
false
</ns2:includeSubOrganizations>
<ns2:foreignHealthProfessionals>
false
</ns2:foreignHealthProfessionals>
</ns2:who>
<ns2:validFromDate>
2021-12-17T07:35:53.000+01:00
</ns2:validFromDate>
</ConsentRevocations>
</ns4:ConsentRevoke>
</soap:Body>
</soap:Envelope>
|
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soapenv:Header
.. soap headers fj ernet for overskueligehed...
</soapenv:Header>
<soap:Body
wsu:Id="body">
<ns4:ConsentRevokeResponse
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"/>
</soap:Body>
</soap:Envelope> |
ConsentRegistrationsGet
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header
.. soap headers fj ernet for overskueligehed...
</soap:Header>
<soap:Body
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04"
wsu:Id="body">
<ns4:ConsentRegistrationsGet
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04">
<PatientPersonCivilRegistrationIdentifier>
0701979346
</PatientPersonCivilRegistrationIdentifier>
</ns4:ConsentRegistrationsGet>
</soap:Body>
</soap:Envelope> |
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:sbf="urn:liberty:sb"
xmlns:sbfprofile="urn:liberty:sb:profile"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soapenv:Header
.. soap headers fj ernet for overskueligehed...
</soapenv:Header>
<soap:Body
wsu:Id="body">
<ns4:ConsentRegistrationsGetResponse
xmlns:ns2="urn:dk:nsi:consentservices:types"
xmlns:ns3="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd"
xmlns:ns4="http://sundhedsdatastyrelsen.dk/minspaerring/2020/11/04">
<ConsentRegistrations>
<ns2:consentId>
123498765532463
</ns2:consentId>
<ns2:citizenCPR>
0701979346
</ns2:citizenCPR>
<ns2:positiveConsent>
false
</ns2:positiveConsent>
<ns2:who>
<ns2:healthProfessionalCPR>
0307702555
</ns2:healthProfessionalCPR>
<ns2:includeSubOrganizations>
false
</ns2:includeSubOrganizations>
<ns2:foreignHealthProfessionals>
false
</ns2:foreignHealthProfessionals>
</ns2:who>
<ns2:validFromDate>
2021-12-17T07:35:53.000+01:00
</ns2:validFromDate>
</ConsentRegistrations>
</ns4:ConsentRegistrationsGetResponse>
</soap:Body>
</soap:Envelope> |
Service Klienter
Der er udviklet en service klient til hver service. Klienterne kan findes som maven moduler.
| Code Block | ||
|---|---|---|
| ||
<dependency>
<groupId>dk.nsi.consentservices.verification</groupId>
<artifactId>consent-verification-client</artifactId>
<version><desired client version></version>
</dependency> |
og:
| Code Block | ||
|---|---|---|
| ||
<dependency>
<groupId>dk.nsi.consentservices.administration</groupId>
<artifactId>consent-administration-client</artifactId>
<version><desired client version></version>
</dependency> |
Oprettelse af service client
Disse serviceklienter konfigureres ved hjælp af en property fil, og klienten sørger for at få et gyldigt STS-token, indsætte korrekte headers osv.
Konfiguration af klienten sker via ClientConfig. ClientConfig's argument er navnet på den property fil der skal anvendes. Filen skal findes på classpath.
Koden nedenfor opretter en web service port til Samtykkeservicen Verifikation:
| Code Block |
|---|
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); |
Dette forudsætter, at en VerificationClient.properties-fil kan findes på classpath
Lignende kode skaber en klient til Samtykkeservicen Administration, klienten er bare klassen ConsentAdministrationService i stedet, og kaldet returnerer en web service port der er defineret i klassen ConsentAdministration.
Konfiguration
Den konfigurationsfil der gives til service klient skal definere en række properties som klienten anvender til at kommunikere med servicen.
| Code Block |
|---|
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 |
Værdierne er taget fra integrationstesten og skal tilpasses til det anvende systemet Det vil sige sti til certifikat, systemnavn osv.
Headers
Derefter kan service og port bruges til at oprette de nødvendige headers så det er muligt at kalde servicen.
Et flowID er angivet i headeren.
| Code Block |
|---|
DGWSHeaderWrapper signedHeaders = service.getSignedHeaders(flowID);
Holder<Header> medcomHeader =
new Holder<Header>(signedHeaders.getMedcomHeader());
HsuidHeader hsuidHeader = createHsuidHeader(); |
Værdierne i HSUID-headeren skal sættes manuelt ved at kalde en metode, der opretter objektet (se MinSpærring Healthcare Service User Identification Header Interface Description for en beskrivelse af headerindholdet).
Medcom-headeren er pakket ind i et holderobjekt, da det er en request/response-parameter.
Eksempel på kald af Samtykkeservicen Verifikation
Et eksempel på kald af ConsentForDataCheck er vist her.
| Code Block | ||
|---|---|---|
| ||
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);
|
Elementet consentData skal være en liste over ConsentDataRegistration-objekter, se MinSpærring - Administration Service Interface Beskrivelse.
Servicen returnerer en liste af ID'er som den sundhedsfaglige har samtukke til at få vist.
Eksempel på kald af Samtykkeservicen Administration
Her vises et eksempel på et kald til ConsentAdd i administrationsservicen. Indholdet af det faktiske samtykkeobjekt vises ikke her:
| Code Block | ||
|---|---|---|
| ||
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); |
Klient generering fra WSDL
Det er også muligt selv at generere en klient baseret på en WSDL.
Samtykkeservicen services versioner
Både den administrative og verifikationssnitfladen findes i flere versioner. Nedenstående liste er en fortegnelse over disse og deres endpoints og WSDL. Urlen skal tilpasses til det miljø, som anvenderen ønsker at ramme (se FAQ NSP miljøer).
| Verifikationsservice | URL | WSL |
|---|---|---|
| DGWS service til verfification af bruger og data | http://localhost:8080/consent-verification/service | http://localhost:8080/consent-verification/service?wsdl http://localhost:8080/consent-verification/service-contract/wsdl/consent-verification.wsdl |
| Administrationsservice | ||
| DGWS service til administration af spærringer | http://localhost:8081/consent-administration/service | http://localhost:8081/consent-administration/service?wsdl http://localhost:8081/consent-administration/service-contract/wsdl/consent-administration-dgws.wsdl |
| IDWS service til administration af spærringer | http://localhost:8081/consent-administration/serviceidws | http://localhost:8081/consent-administration/serviceidws?wsdl http://localhost:8081/consent-administration/service-contract/wsdl/consent-administration-idws.wsdl |
| DGWS service til administration af spærringer v2 | http://localhost:8081/consent-administration/service-2.0 | http://localhost:8081/consent-administration/service-2.0?wsdl http://localhost:8081/consent-administration/service-contract/wsdl/consent-administration-dgws-20201104.wsdl |
| IDWS service til administration af spærringer v2 | http://localhost:8081/consent-administration/serviceidws-2.0 | http://localhost:8081/consent-administration/serviceidws-2.0?wsdl http://localhost:8081/consent-administration/service-contract/wsdl/consent-administration-idws-20201104.wsdl |
| DGWS service til administration af spærringer for ikke digititale borgere | http://localhost:8081/consent-administration/service-adm-2.0 | http://localhost:8081/consent-administration/service-adm-2.0?wsdl http://localhost:8081/consent-administration/service-contract/wsdl/consent-administration-adm-20220207.wsdl |