Specifikationen for Web Service interfacet for MinSpærring Verifikation beskriver de web services som MinSpærring Verifikation tilbyder henholdsvis sundhedsfaglige og borgere der vil udføre MinSpærring Verifikation.
En MinSpærring registrering beskrivelse sammenhængen mellem.
A consent describes a relationship between:
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.
Formålet med denne sektion er at give et overblik over definitioner og referencer anvendt i dette dokument.
| Definition | Beskrivelse |
|---|---|
NSI | National Sundheds IT |
NSP | National Service Platform |
SAML | Security Assertion Markup Language |
STS | Security Token Service |
NCP | National Contact Point |
| Reference | Beskrivelse |
|---|---|
OIO-NDR | OIO Navngivnings- og Designregler, OIO-NDR version 3.2, http://www.itst.dk/it-arkitektur-og-standarder/standardisering/datastandardisering/oioxml-udvikling/regler/ndr-3.2 |
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) |
OIO-WSDL | Guide for udvikling og anvendelse af OIOWSDL, http://www.itst.dk/it-arkitektur-og-standarder/standardisering/standarder-for-serviceorienteret-infrastruktur/standarder-for-webservices/filer-til-standarder-for-webservices/OIOWSDL_english.pdf |
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 anvender Web Services
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.
It is assumed that the reader understands the general use of SOAP-based Web services, why technical terms such as SOAP, WSDL etc. are not clarified. Kendskab til Den Gode Webservice (DGWS) 1.0.1beskrevet i [DGWS 1.0] og [DGWS 1.0.1] vil gøre forståelsen nemmere.
| Version | Date | Responsible | Description |
|---|---|---|---|
0.1 | 24.4.2012 | Systematic | Initial version. |
0.2 | 1.5.2012 | Systematic | Optimization of data elements by verification of consent for data elements. Addition of ConsentForForeignerCheck operation. |
0.9 | 14.5.2012 | Systematic | HSUID-header reference added, reading guide updated, web service semantics updated. |
1.0 | 29.6.2012 | Systematic | ConsentForForeignersCheck, SOAP-faults, table elaboration, general improvements. |
1.1 | 28.11.2014 | Systematic | References to National Patient Index (NPI) removed. |
1.2 | 09.09.2016 | Systematic | Changed nsi:skscode to nsi:skskode and nsi:sorcode to nsi:sor to fit XML schema |
1.3 | 13.06.2018 | Systematic | Migrated to NSPOP SVN |
| 22.10.2018 | KIT | Document moved from Word to Confluence. Original document name was: IFS0014 Consent Verification Service Interface Description.docx | |
| 10.11.2020 | KIT | Oversættelse til Dansk samt ajourføring |
Nedenstående beskriver brugerscenarier som service MinSpærring Verifikation understøtter.
En sundhedsperson kan kontrollere en borgeres samtykker og spærringer for at afgøre, om der findes et samtykke eller spærring for adgang til borgerens data. Dette brugsscenarie understøttes af operationen ConsentForUserCheck. Kontrollen udføres typisk inden der hentes oplysninger om borgeren.
Resultatet af operationen er en erklæring om, hvorvidt der er spærret eller givet samtykke til den sundhedsfaglige. Resultat er enten negative, positive eller DataSpecificConsent.
DataSpecificConsent betyder, at der findes et eller flere samtykker eller spærringer til udvalgte oplysninger om borgeren. Det er således ikke muligt at afgøre, om sundhedspersonalet har ret til al information om borgeren. Derfor skal yderligere verifikation af de enkelte dataelementer udføres, inden den sundhedsfaglige kan få oplysninger om borgeren. Ved positivt svar udføres der ikke yderligere verifikation af data. Ved negativt svar er al information om borgeren utilgængelig for den sundhedsfaglige.
En sundhedsfaglig ønsker at hente en række oplysninger om en borger. Et tidligere kald til operationen ConsentForUserCheck returnerede resultatet DataSpecificConsent. Det er således nødvendigt at kontrollere hvert enkelt dataelement for borgerens samtykke eller spærring med hensyn til den sundhedsfaglige persons adgang. Operationen ConsentForDataCheck understøtter dette scenarie.
Resultatet af operationen er en liste af data elementer som den sundhedsfaglige har lov til at se.
En sundhedsfaglig person, i et andet landt, ønsker at hente information om en dansk borger. Dette sker via et kald fra et andet lands NCP til den danske NCP. Før den danske NCP returnerer infomationer om den danske borger tjekkes der at borgeren har registreret et samtykke til den sundhedsfaglige person. Dette sker ved kald til operationen ConsentForForeignersCheck.
Resultatet af operationen er om den sundhedsfaglige har samtykke til a tilgå borgerens data.
Nedenstående skabelon dokumenterer operationenerne der er udstillet af MinSpærring Verifikation. De vigtigste elementer i forespørgsel og svar er beskrevet i sektion 5.
Navn: <operation header> | |
|---|---|
Beskrivelse | Beskriver operationens formål. |
Forespørgsel: | Parameter til input. |
Svar: | Parametre i svar. |
Fejlhåndtering: | Beskriver fejlhåndtering. Refererer typisk til den generelle beskrivelse af fejlhåndtering i afsnit 4.7. |
Roller: | Beskriver krævede roller. |
Forudsætninger: | Beskriver forudsætninger der skal være opfyldt for at operationen kan udføres. |
Nedenstående operationer udstullet af MinSpærring Verifikation.
Navn: ConsentForUserCheck | |
|---|---|
Beskrivelse: | Undersøger om en borger har oprettet generelt samtykke, spærring eller data specifik spærring for en bruger. |
Forespørgsel: | ConsentForUserCheckRequest består af: PatientPersonCivilRegistrationIdentifier Identifkation af den borger samtykke/spærring ønskes undersøgt. HealthcareProfessionalIdentifier HealthcareProfessionalIdentifierOnBehalfOf HealthcareProfessionalOrganization |
Svar: | ConsentForUserCheckResponse består af: ConsentIndication Samtykke, spærring eller dataspecifkt samtykke i nedenstående form: Positive – betyder at den sundhedsaglige har adgang til data. Negative – betyder at den sundhedsfaglige, eller dennes tilknyttede organisation, ikke har adgang til borgerens data. DataSpecificConsent - betyder at der er registreret dataspecikt samtykke eller spærring. Derfor er det ikke muligt at afgøre om den sundhedsfaglige har adgang til data. Derfor skal der laves opfølgende kald til operationen ConsentForDataCheck. |
Error handling: | Se afsnit 4.7. |
Roles: | Sundhedsffaglig. |
Prerequisites: | Både bruger og brugersystem skal godkendt som beskrevet i afsnit 4.2.1. |
Navn: ConsentForDataCheck | |
|---|---|
Beskrivelse: | Undersøger om en borger har oprettet data specifikke spærringer eller samtykker. |
Forespørgsel: | ConsentForDataCheckRequest består af: PatientPersonCivilRegistrationIdentifier Identifkation af den borger samtykke/spærring ønskes undersøgt. HealthcareProfessionalIdentifier HealthcareProfessionalIdentifierOnBehalfOf HealthcareProfessionalOrganization ConsentForDataRegistrations |
Svar: | ConsentForDataCheckResponse består af: PositiveConsentDataRegistrations Liste af dokument ID fra forespørgsel som den sundhedsfaglige har lov til at se. professional. |
Fejlhåndtering: | Se afsnit 4.7. |
Roller: | Sundhedsfaglig. |
Forudsætninger: | Både bruger og brugersystem skal godkendt som beskrevet i afsnit 4.2.1. |
Navn: ConsentForForeignersCheck | |
|---|---|
Beskrivelse: | Undersøger om en borger har givet samtykke til at en sundhedsfaglig i et andet land må tilgå borgerens data. |
Forespørgsel: | ConsentForForeignersCheckRequest består: PatientPersonCivilRegistrationIdentifier Identifkation af den borger samtykke/spærring ønskes undersøgt. |
Svar: | ConsentForForeignerCheckResponse består af: ConsentForForeigners om der er adgang til data. Positive – betyder at der er oprettet samtykke så den sundhedsfaglige må tilgå borgerens data. Negative - betyder at der ikke er adgang til borgerens data. |
Fejlhåndtering: | Se afsnit 4.7. |
Roller: | Sundhedsfaglig person |
Forudsætninger: | Både bruger og brugersystem skal godkendt som beskrevet i afsnit 4.2.1. |
Web servicen forventer SOAP beskeder. SOAP headeren indeholder sikkerheds header og Medcom header som krævet i DGWS 1.0.1. Udover dette skal der også være en HSUID header.
Figur 1 SOAP besked indeholdende sikkerhedsheader, Medcomheader samt HSUID header.
Formatet af sikkederhedsheader og Medcomheader er beskreivet i [DGWS 1.0] og [DGWS 1.0.1]. Formatet for HSUID-headeren er beskrevet i [HSUID-Header].
Når brugere er en sundhedsfaglig person er det nedenstående attributter der skal være i HSUID headeren.
| Element attribut | Underelement Attributværdi | |
|---|---|---|
Attributnavn | Attribuit format | - |
nsi:UserType | nsi:HealthcareProfessional | |
nsi:ActingUserCivilRegistrationNumber | Den sundhedsfaglige CPR nummer. | |
nsi:OrgUsingID | nsi:sor or nsi:skskode or nsi:ynumber | Identifikation af den organisation som den sundhedsfaglige er tilknyttet. Attributten skal være der mindst én gang og må maksimalt være angivet to tange. Hvis den er angivet to gange kan organisationen være identificeret ved en SOR kode og f.eks. en SHAK kode. |
nsi:ResponsibleUserCivilRegistrationNumber | CPR nummer på den sundhedsfaglige som brugeren agerer på vegne aaf. Hvis det er den samme person som brugeren er det samme CPR nummer angivet. | |
nsi:ResponsibleUserAuthorizationCode | Autorisationsnummer på den sundhedsfaglige som brugeren agerer på vegne af. Hvis brugeren er en sundhedsfaglig uden autorisationskode, arbejder på vegne af en sundhedsfaglig uden autorisationskode anvendes specialværdien '-'. | |
nsi:SystemOwnerName | Navn på systemejer af anvendersystemet. | |
nsi:SystemName | Navn på anvendersystem. | |
nsi:SystemVersion | Version af anvendersystem. | |
nsi:OrgResponsibleName | Navn på organisation ansvarlig for anvendersystem. | |
Tabel 1 Attributer i HSUID-header når bruger sundhedsfaglig.
Identifikation af organisationen sundhedsfaglig er tilknyttet kan angives som en enkelt kode i form af f.eks. en SHAK-kode:
<hsuid:Attribute Name="nsi:OrgUsingID" NameFormat="nsi:skskode"> <hsuid:AttributeValue>6620151</hsuid:AttributeValue> </hsuid:Attribute> |
Alternativt kan organisation angives med to værdier. Det kan f.eks. være en SOR kode og en SHAK kode:
<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> |
Bemærk at det er anvendersystemets ansvar at sikre konsistes mellem de angive organisationer.
Sikkerheden er baseret på SOSI-integrationsmønstret i Den Gode WebService (DGWS). Godkendelse sker via STS på NSP'en og er baseret på OCES digitale certifikater. Som udgangspunkt kræves der et medarbejdercertifikat (MOCES). Initielt kan visse systemer, i en overgangsperiode, anvende et VOCES certifikat.
Yderligere sikkerhedsaspekter, herunder autorisation, integritet, fortrolighed, tilgængelighed og fortrolighedshensyn, håndhæves kun i nogen grad af den tekniske service. De aspekter, der i øjeblikket ikke håndteres af den tekniske tjeneste, håndteres i serviceaftalen, som specificeret af den dataansvarlige myndighed (SDS) som forbrugere af tjenesten skal acceptere.
Når STS'en signatur af ID korter er valideret med succes har anvenderen adgang.
Udover dette skal anvendersystemet være whitelisted baseret på system delen af ID-kortet.
Når anvendersytemet er godkendt bliver brugeren godkendt via HSUID header attributen nsi:ActingUserCivilRegistrationNumber.
Om det er en borger eller sundhedsfaglig afgøres af HSUID header attributen nsi: UserType.
Web service opetaitoner hvor bruger er sundhedsfaglig
Servicen godkender all brugere der er sundhedsfaglige.
En request med et ID-kort der er mere end 24 timer gammelt i forhold til udstedelsestidspunkt afvises.
Som krævet i DGWS 1.0.1 anvendes kun HTTP status kode 200 og 500.
Ved HTTP status kode 200 er FlowStatus altid flow_finalized_succesfully.
Timeout er det samme som standard timeout på NSP platformen.
Alle kald håndteres i sin egen session.
Der forestages ikke check om et MessageId har været anvendt tidligere og der er ikke garanti for at samme svar returenres hvis MessageId anvendes igen.
Dette afviger fra DGWS 1.0.1 i forhold til håndtering af genfremsendelse.
If the request contains a flow ID, it is reused in the reply. Handling of flow ID complies with DGWS 1.0.1.
Digital signing of replies is not supported. On request for non-repudiation, a fault-error message is returned as described in [DGWS 1.0].
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:verification: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 faults returned from Web service operation. The example shows FaultCode used when the ID card has expired.
For all web service operations described in section 3 will be used SOAP Fault with FaultCode-values as listed in Table 2, originating from DGWS 1.0.1.
FaultCode | Description |
|---|---|
missing_required_header | One or more mandatory DGWS headers are missing in the enclosed message, e.g. ID card, which always must be provided. |
security_level_failed | Authentication or authorization error. Invalid choice of security level. |
invalid_idcard | Authentication or authorization error. Error in SOSI ID card. |
invalid_certificate | Authentication or authorization error. Certificate is not OCES or expired. |
expired_idcard | Authentication or authorization error. SOSI ID expired or too old for this Web service provider. |
not_authorized | User has insufficient rights to perform the Web service operation call. E.g., company registration number is not on whitelist. |
nonrepudiation_not_supported | Web service provider system cannot perform a digital signature on the reply. |
Table 2 Applied FaultCode-values originating from DGWS 1.0.1
Additionally, service specific FaultCode values as listed in Table 3 are used.
FaultCode | Description |
|---|---|
consent_service.ConsentDatabase | An internal server error has occurred in connection with consent database communication |
consent_service.SORLookup | An internal server error has occurred in connection with lookup in the SOR-table |
consent_service.ServiceInvocation | The service was called with invalid parameters: |
invalid_date_timezone | An attached date has invalid format, cf. DGWS 1.0.1. |
consent_service.UnknownError | An unknown server error resulted in failed call |
Table 3 Applied service-specific FaultCode-values
The WSDL that describes the Web service described in this document does not specify the SOAP Fault status codes for every operation.
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. 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
There will be performed:
No XML schema validation
No validation that stated authorization numbers are valid and found in National Board of Health authorization register
No validation that there is consistency between the health professional’s organization ID's when multiple ID and classification systems are provided.
No validation that a health care professional is affiliated with stated organization
No validation that the user is acting under responsibility of stated health professional
Consent verification service is based on the following standards:
SOAP version 1.1
Soap Fault version 1.1
WS-I Basic Profile 1.1
OIO namegivnings- og designregler
DGWS 1.0.1, with the exception of requirements regarding retransmission and control of reuse of messageID as described in section 4.5, and with the exception of structure used on errors as described in section 4.7.1.
This section provides a general description of the key elements in the XML schemas, which together with WSDL files define the Web service operations described in 3.2. Additionally, cardinality is provided when an element is not compulsory.
Element-name | Description |
HeathcareProfessionalIdentifierOnBehalfOf | Identification of the health professional who is acted on behalf of. The field is optional and can be provided without content. |
Element-name | Description |
ConsentDataRegistration[0..n] | Collection of data elements where consent must be verified. |
Element-name | Description |
Identifier[1] | Unique identification of data element (key value) as provided by the calling system. |
Origin[1] | SOR, SHAK or provider-number which states the origin of the data element |
CreationDateTime[1] | Time for creation of data element in question |
Element-name | Description |
ConsentIndication | Positive, negative or applicable to specific data. With value set: Positive, Negative, DataSpecificConsent |
Element-name | Description |
DataIdentifiers[0..n] | Collection of unique identification of data element (key-value) as provided by the calling system |
Element-name | Description |
ConsentForForeigners | Positive or negative with value set: Positive, Negative |
For the consent verification, the interface between the actor systems and consent verification is versioned.
The interface specification constitutes the contract that defines how the systems involved must act.
The interface specification consists of:
the technical specification of schemas and service descriptions (documented as a WSDL file, see section 7)
documentation of the semantic and functional meaning of data that is exchanged (documented in this document).
As part of the WSDL for ConsentVerification figures headers that are defined and versioned elsewhere. The body is specific for ConsentVerification and follows the naming
”urn:dk:nsi:consentservices:verification:service:<version>”
where the version changes on redefinition of the ConsentVerification interface.
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.