Introduktion

Formål

Denne specifikation af snitfladen til administration af samtykke og spærringer beskriver de services, der leveres til henholdsvis sundhedsfalige og borgere, der ønsker at udføre administration (oprettelse, ændring, sletning) af samtykke eller spærring.

Koncepter

En MinSpærring registrering beskriver sammenhængen mellem:

en borger,

(what) information om hvad en MinSpærring omhandler.

(who) sundhedsfaglig person eller organisation der er oprettet MinSpærring for.

For en detaljeret beskrivelse af datamodellen for MinSpærring og strukturen af MinSpærring elementerne se MinSpærring - Data Model

En spærring betyder at borgeren har afvist at data identificeret via what kan tilgås af personer eller organisationer identificaeret via who.

Et samtykke betyder at sundhedsfaglige personer eller organisation, identificeret via. who, kan tilgå data identificeret via what. Dette selvom der er oprettet en eller flere spæringer. Et samtykke kan også bruges i eksterne systemer til at tillade en given gruppe af personer adgang til til følsomme data der ellers er blevet markeret som private.

En registrering er enten aktive eller inaktive. En aktive registrering kan påvirke en sundhedsfagligs adgagn til følsom data om en borger. En inaktiv registrering har ikke nogen påvirkning på nuværende spærringer eller samtykker, men er udelukkende historik for en tidligere aktiv spærring eller samtykke.

En spærring eller samtykke kan oprettes for en gyldighedsperiode (when) der angiver hvilken periode der er spærret eller givet samtykke til data. Gyldighedsperioden angiver udelukkende hvornår der laves opslag på data og siger ikke noget om hvornår data var registreret eller oprettet. Samtykke skal have en gyldighedsperiode. En spærring kræber kun en startdato.

En sundhedsfagligs adgang til følsom data for en specifik borger er ikke påvirket hvis den oprettede spærring eller samtykke er for en anden sundhedsfaglig eller organisation. Dette er f.eks. hvis der er oprettet en spærring for en anden sundhedsfaglig end den der forespørger på data.

Definitioner og referencer

Formålet med denne sektion er at give et overblik over definitioner og referencer anvendt i dette dokument.

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 på sundhedspersonale med dansk autorisation, der er anført i Sundhedsstyrelsens autorisationsregister, vil det blive udtrykkeligt angivet.

Et system, der bruger webservices beskrevet i dette dokument, referes som et anvendersystem.

Det antages at læseren har general forståelse for SOAP-basterede Web Services. Derfor er tekniske termer som SOAP, WSDL osv. ikke beskrevet. Kendskab til  Den Gode Webservice (DGWS) 1.0.1beskrevet i  [DGWS 1.0] og [DGWS 1.0.1] vil gøre forståelsen nemmere.

Dokument historik

Bruger og anvendersystems ansvar

For nogle af brugsscenarierne (og dermed webserviceoperationerne) beskrevet i dette dokument er det tilladt for en anden person end borgeren selv at udføre handlingen (kaldet at udføre handlingen på borgerens vegne). I dette tilfælde er det anvendersystemets ansvar at sikre, at borgeren har givet sit samtykke til, at personen kan udføre denne handling, før den udføres.

Tilsvarende er det tilladt i visse brugsscenarier, at en sundhedsfaglig udfører handlingen på vegne af borgeren. Det er anvendersystemets ansvar at sikre, at borgeren har givet sit samtykke til, at den sundhedsfaglige har samtykke til at  udføre denne handling, inden den udføres.

Det er muligt via servicen at oprette to (eller flere) registreringer, der er identiske set fra borgernes synspunkt. For eksempel ved SOR-koder, der mappes til den samme afdeling, ved overlappende datoer eller simpelthen helt identiske registreringer.
Servicen kontrollerer ikke, om der oprettes identiske registreringer, og det er følgelig anvendersystemets ansvar at sikre, at der ikke oprettes nye registreringer, der er identiske med allerede eksisterende.

MinSpærring Administration Anvenderscenarier

I det følgende afsnit beskrives de brugsscenarier, som MinSpærring Administration understøtter.

En ny version af grænsefladen er tilføjet. I denne grænseflade er operationerne ConsentAdd og ConsentModify opdelt i to separate operationer - i alt fire operationer: ConsentAddPositiveV2, ConsentAddContraintV2, ConsentModifyPositiveV2, ConsentModifyConstraintV2

The following section describes the usage scenarios that the Web service for consent administration supports.

A new version of the interface has been added. In this interface the operations ConsentAdd and ConsentModify has been splitted into two seperate operations - four operations in total: ConsentAddPositiveV2, ConsentAddContraintV2, ConsentModifyPositiveV2, ConsentModifyConstraintV2

Health Professional Registers Consent in a Citizen’s Consent Registrations

A health professional is able to add positive and negative consent on behalf of the citizen to the citizen’s present consent registrations.

As the change entails an entry in the citizen’s Min-log, the citizen will be able to later learn this.

This usage scenario is supported by the operation ConsentAdd in the original version of the consent administration interface.

This usage scenario is supported by the operation ConsentAddPositiveV2 or ConsentAddConstraintV2 in the new version of the consent administration interface.

Citizen Retrieves an Overview of Present Consent Registrations

A citizen can retrieve a complete overview of the consents, that are registered for the citizen, whether they are registered by the citizen, a person on behalf of the citizen or by a health professional.

Another person than the citizen can, on behalf of the citizen, perform the activity. As the action entails an entry in the citizen’s Min-log, the citizen will later be able to learn of the action performed by the person.

This usage scenario is supported by the operation ConsentRegistrationsGet in the original version of the consent administration interface.

This usage scenario is supported by the operation ConsentRegistrationsGetV2 in the new version of the consent administration interface.

The result of the operation is a complete list of all active and inactive consent registrations for the citizen in question.

Registration of Negative Consent

A citizen can register negative consent covering:

1. (what) Possibly everything in regard to (who) everybody or a specific (named) person provided by social security number.

2. Or (what) selected information, originating from organization provided by SOR-code – with or without subordinate organizations - created in a certain period in respect to (who) everybody.

3. (when) a validity period for the consent provided by start and end date, where end date is not a requirement.

Another person than the citizen can, on behalf of the citizen, perform the activity. As the action entails an entry in the citizen’s Min-log, the citizen will later be able to learn of the action performed by the person.

This usage scenario is supported by the operation ConsentAdd in the original version of the consent administration interface.

This usage scenario is supported by the operation ConsentAddPositiveV2 in the new version of the consent administration interface.

Registration of Positive Consent

A citizen can register positive consent covering:

1. (what) Possibly everything in regard to (who) for a specific identified person provided by social security number or for an organization provided by SOR-code – with or without subordinate organization – or for foreign health professionals provided by positive marking.

1. Or (what) selected information originating from a specific organization provided by SOR-code – with or without subordinate organization - created in a certain period in respect to (who) either a specific named person provided by social security number or for a specific organization provided by SOR-code – with or without subordinate organization.

2. (when) a validity period for the consent provided by start and end time. The validity can at most cover one year.

The activity can be performed by a person other than the citizen, on behalf of the citizen. As the action entails an entry in the citizen’s Min-log, the citizen will be able to later learn of this person’s action.

This usage scenario is supported by the operation ConsentAdd in the original version of the consent administration interface.

This usage scenario is supported by the operation ConsentAddConstraintV2 in the new version of the consent administration interface.

Citizen Modifies Consent

A citizen can change one or more positive or negative consent registrations.

The activity can be performed by another person than the citizen, on behalf of the citizen. As the action entails an entry in the citizen’s Min-log, the citizen will be able to later learn of this person’s action.

This usage scenario is supported by the operation ConsentModify in the original version of the consent administration interface.

This usage scenario is supported by the operations ConsentModifyPositiveV2 or ConsentModifyConstraintV2 in the new version of the consent administration interface.

Citizen Nullifies Consent

A citizen can nullify positive and negative consent registrations.

The activity can be performed by another person than the citizen, on behalf of the citizen. As the action entails an entry in the citizen’s Min-log, the citizen will be able to later learn of this person’s action.

This usage scenario is supported by the operation ConsentRevoke in the original version of the consent administration interface.

This usage scenario is supported by the operation ConsentRevokeV2 in the new version of the consent administration interface.

Consent Administration Web Service

Reading Guide

The template below is used to document the operations that are offered in the Consent Administration Web Service. The most important elements for input and output are described in section 5.

Web Service - Consent_Administration (Original)

Operation – ConsentRegistrationsGet

Operation – ConsentAdd

Operation – ConsentModify

Operation – ConsentRevoke

Web Service - Consent_Administration (V2)

Operation – ConsentRegistrationsGetV2

Operation – ConsentAddPositiveV2

Operation – ConsentAddConstraintV2

Operation – ConsentModifyPositiveV2

Operation – ConsentModifyConstraintV2

Operation – ConsentRevokeV2

Consent Administration Web Service Semantics

Message Format

The Web service expects SOAP messages, where the SOAP header contains security header and Medcom header as required by DGWS 1.0.1, in addition to a Healthcare Service User Identification (HSUID) header.

Figure 1 SOAP message containing security header, Medcom header and HSUID header is used as message format.

The format of Security and Medcom headers are described in [DGWS 1.0] and [DGWS 1.0.1], while the format of the HSUID header is described in [HSUID-header].

Attributes in HSUID-header applied for user who is a citizen

When user of the service is a citizen, then the attributes in Table 1 from the HSUID-header are applied.

Table 1 Attributes in HSUID-header applied for user who is citizen.

Attributes in HSUID-header applied for user who is a health professional

When the user of the service is a health professional, then the attributes in Table 2 from the HSUID-header are applied.

Table 2 Attributes in the HSUID-header applied for user who is a health professional.

The identification of the organization for which the user is associated, may be provided as a single value and a single format, such as SHAK-code:

<hsuid:Attribute Name="nsi:OrgUsingID" NameFormat="nsi:skskode">
	<hsuid:AttributeValue>6620151</hsuid:AttributeValue>
</hsuid:Attribute>

Alternatively, the organization of which the user is affiliated can be specified by two values, e.g. as both SOR and SHAK-code:

<hsuid:Attribute Name="nsi:OrgUsingID" NameFormat="nsi:sor">
	<hsuid:AttributeValue>440081000016006</hsuid:AttributeValue>
</hsuid:Attribute>
<hsuid:Attribute Name="nsi:OrgUsingID" NameFormat="nsi:skskode">
	<hsuid:AttributeValue>6620151</hsuid:AttributeValue>
</hsuid:Attribute>

Note that it is the consumer system's responsibility to ensure that there is consistency between the given ID across SOR, SHAK, and Healthcare Provider Number (Danish: ydernummer) classification systems.

Web Service Security

The security of this Web service is based on the SOSI integration pattern in Den Gode Webservice (DGWS). Authentication is carried out by a trusted third party component on NSP (Security Token Service) and based on OCES digital certificates. As a rule, the service requires authentication with the STS component based on employee signature (MOCES). However, highly trusted systems - initially only Health journal - can during a transitional period gain access by level 3 based on company signature (VOCES).

Additional security aspects, including authorization, integrity, confidentiality, availability and privacy considerations are enforced to only some extent by the technical service. The aspects that are not currently handled by the technical service will be handled in the service agreement, as specified by the data-responsible authority (NSI), which consumers of the service must agree to.

Authentication and authorization

Authentication and authorization of consumer systems

When STS’ signature of the ID card has been validated successfully, then the consumer has been authenticated and a IDWS security context ticket is provided to the service.

Authorization of consumer system is performed using a whitelist in the web service based on information in the system-part of the ID card.

Authentication of user

When the user system is authenticated and authorized, the user is authenticated by the HSUID header attribute nsi: ActingUserCivilRegistrationNumber.

Authorisation of user

Whether the user is health professional or citizen is determined from either the IDWS ticket or the HSUID header attribute nsi: UserType.

Web service operation(s), where the user is health professional

The Web service authorizes all users who are health professionals to use its operations.

Web service operation(s), where the user is the citizen or a citizen, acting on behalf of another

The Web service authorize all users who are citizens to use its operations.

It is the user’s responsibility to ensure that the person is allowed to act on behalf of the citizen.

Timeout on ID card

A request with ID card is rejected when it has been more than 24 hours since the beginning of the ID card validity period.

Status Code

As required by DGWS 1.0.1, only HTTP-status codes 200 and 500 are used.

On HTTP status code 200 FlowStatus is always flow_finalized_succesfully.

Timeout on Web Service Operation

Timeout on web service-operations is the same as default timeout on the NSP platform.

Session

Each request is handled in its own session.

No check is performed whether MessageID in request has been received previously and no answer is guaranteed if a request with the same MessageID is received.

This deviates from DGWS 1.0.1 in regard to handling of retransmission.

Assignment and reuse respectively of flow ID

If the request contains a flow ID, it is reused in possible forward calls to Min-log. Handling of flow ID complies with DGWS 1.0.1.

Processing of Request for Non-repudiation

Digital signing of replies is not supported. On request for non-repudiation, a fault-error message is returned as described in [DGWS 1.0].

Error Handling

SOAP errors

SOAP errors are returned with the components as described hereinafter.  A structure has been chosen wherein both standard error codes as described in [DGWS 1.0] and service specific error codes can be returned.

<soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>Description of the error</faultstring>
         <detail>
            <FaultInfo xsi:type="ns2:dgwsInfo" xmlns="urn:dk:nsi:consent:admin:service:1" xmlns:ns2="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <ns2:FaultCode>expired_idcard</ns2:FaultCode>
            </FaultInfo>
         </detail>
      </soap:Fault>
</soap:Body>

Code listing 1 Structure of SOAP-errors returned from the Web service operation. The example shows FaultCode used when the ID card has expired.

SOAP Fault Status Codes

For all Web service operations described in section 3 will be used SOAP Fault with FaultCode-values as listed in Table 3, originating from DGWS 1.0.1.

Table 3 Applied FaultCode-values originating from DGWS 1.0.1

Additionally, Web service specific FaultCode values as listed in Table 4 are used.

Table 4 Applied service-specific FaultCode values

In WSDL, that describes the Web service described in this document, these SOAP Fault status codes are not specified for every operation.

Web Service Input Validation

It is validated that:

• Properly formatted HSUID header is included in the SOAP header, including the attributes that respectively may and must be present for a given user type, as described in section 4.1.1 and 4.1.2, are provided. Furthermore, it is validated that attribute values belong to established value sets and is not null or simply whitespaces

• ID card in security header is valid and signed by STS and that the additional conditions described in section 4.2 are met

• Social security numbers are valid and found in the National Board of Health authorization register.
• Organization identifiers are valid. Validity means that the identifier is a valid SOR-, SHAK- or Yder identifier.

There following is not performed:

• XML-schema validation

• Validation that given authorization numbers are valid and found National Board of Health authorization register

• Validation that there is consistency between the health professional’s organization ID's when multiple ID and classification systems are provided.

• Validation that a health care professional is affiliated with stated organization

• Validation that the user is acting under responsibility of stated health professional

Standards

Consent administration service is based on the following standards:

1. SOAP version 1.1

2. Soap Fault version 1.1

3. WS-I Basic Profile 1.1

4. OIO naming and design rules

5. DGWS 1.0.1, with the exception of requirements regarding retransmission and control of reuse of message ID as described in section 4.5.1, and with the exception of structure used on errors as described in section 4.7.

Consent Administration Web Service Schemas

This section provides a general description of the key elements in the XML schemas that together with WSDL define the Web service operations described in section 3.2. Where existing OIO-type is identified, it is provided in the parenthesis after the element name. Additionally, cardinality is provided when an element is not compulsory.

ConsentItem

WhatItem

WhoItem

ConsentAdds

ConsentRegistrations

ConsentModification

ConsentRevocation

Governance

Documentation

For consent administration, the interface between the actor systems and consent verification is versioned.

The interface specification constitutes the contract that defines how the involved systems must act.

The interface specification consists of:

• the technical specification of schema and service descriptions (documented as WSDL file, see section 7)

• documentation of the semantic and functional meaning of data that is exchanged (documented in this document).

Versioning

As part of the WSDL for ConsentAdministration are headers defined and versioned elsewhere. The body is specific for ConsentAdministration and follows the naming

”urn:dk:nsi:consentservices:administration:service:<version>”

where the version changes on redefinition of the ConsentAdministration interface.

WSDL

WSDL for the service can be obtained by runtime WSDL-generation towards a deployed service. If the service in NSP test environment cannot be accessed with a view to runtime WSDL-generation, then a locally built and deployed service can be used.