Besked format

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.

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 snitfladen 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

Sundhedsfaglig Registrerer på Vegne af en Borger

En sundhedsfaglig er i stand til at tilføje et samtykke eller en spærring på borgerens vegne til borgerens nuværende registreringer.

Da ændringen medfører en registrering i borgerens Min-log, vil borgeren senere kunne se dette.

Dette brugsscenarie understøttes af operationen ConsentAdd i den originale version af grænsefladen til MinSpærring Administration.

Dette brugsscenarie understøttes af operationen ConsentAddPositiveV2 eller ConsentAddConstraintV2 i den nye version af grænsefladen til administration afregistreringer.

Borger Henter en Oversigt Over Nuværende MinSpærring Registreringer

En borger kan hente et komplet overblik, over de registreringer der er for borgeren i MinSpærring, hvad enten de er registreret af borgeren, en person på vegne af borgeren eller af en sundhedsfaglig.

En anden person end borgeren kan på borgerens vegne udføre aktiviteten. Da handlingen indebærer en registrering i borgerens Min-log, vil borgeren senere være i stand til at se at handlingen er udført af en anden person.

Dette brugsscenarie understøttes af operationen ConsentRegistrationsGet i den oprindelige version af grænsefladen til MinSpærring Administration.

Dette brugsscenario understøttes af operationen ConsentRegistrationsGetV2 i den nye version af grænsefladen til MinSpærring Administration.

Resultatet af operationen er en komplet liste over alle aktive og inaktive registreringer for den pågældende borger.

Registrering af Spærring

En borger kan registrere en spærring, der dækker:

1. (hvad) Muligvis alt hvad angår (hvem) alle eller en bestemt (navngivet) person identificeret ved CPR-nummer.
2. Eller (hvad) valgte oplysninger, der stammer fra en organisation, der identificeres via en SOR-kode - med eller uden underordnede organisationer - oprettet i en bestemt periode i forhold til (hvem) alle.
3. (når) en gyldighedsperiode for samtykke fra start- og slutdato, hvor slutdato ikke er et krav.

En anden person end borgeren kan på borgerens vegne udføre aktiviteten. Da handlingen indebærer en registrering i borgerens Min-log, vil borgeren senere være i stand til at se at handlingen er udført af en anden person.

Dette brugsscenarie understøttes af operationen ConsentAdd i den originale version af grænsefladen til administration af samtykke.

Dette brugsscenarie understøttes af operationen ConsentAddPositiveV2 i den nye version af grænsefladen til MinSpærring Administrtation.

Registrering af Samtykke

En borger kan registrere samtykke, der dækker:

1. (hvad) Muligvis alt med hensyn til (hvem) for en bestemt identificeret person identificeret med CPR-nummer eller for en organisation identificeret via en SOR-kode - med eller uden underordnet organisationer - eller for udenlandske sundhedsfaglige.
2. Eller (hvilke) valgte oplysninger, der stammer fra en bestemt organisation identificeret via SOR-kode - med eller uden underordnet organisationer - oprettet i en bestemt periode i forhold til (hvem) enten en bestemt navngivet person, der er identificeret via CPR-nummer eller for en bestemt organisation, der er identificeret via SOR-kode - med eller uden underordnede organisationer.
3. (hvornår) en gyldighedsperiode for samtykke fra start- og sluttidspunkt. Gyldigheden kan højst dække et år.

Aktiviteten kan udføres af en anden person end borgeren, der har samtykke fra borgeren til at udføre handlingen. . Da handlingen indebærer en registrering i borgerens Min-log, vil borgeren senere være i stand til at se at handlingen er udført af en anden person.

Dette brugsscenarie understøttes af operationen ConsentAdd i den originale version af grænsefladen til MinSpærring Administration.

Dette brugsscenarie understøttes af operationen ConsentAddConstraintV2 i den nye version af grænsefladen til MinSpærring Administration.

Borger Ændrer Registrering

En borger kan ændre en eller flere samtykker eller spærringer.

Aktiviteten kan udføres af en anden person end borgeren, der har samtykke fra borgeren til at udføre handlingen. Da handlingen indebærer en registrering i borgerens Min-log, vil borgeren senere være i stand til at se at handlingen er udført af en anden person.

Dette brugsscenarie understøttes af operationen ConsentModify i den oprindelige version af grænsefladen til MinSpærring Administration.

Dette brugsscenarie understøttes af operationerne ConsentModifyPositiveV2 eller ConsentModifyConstraintV2 i den nye version af grænsefladen til MinSpærring Administration.

Borger Ophæver Spærring/Samtykke

En borger kan ophæve samtykker og spærringer.

Aktiviteten kan udføres af en anden person end borgeren, der har samtykke fra borgeren til at udføre handlingen. Da handlingen indebærer en registrering i borgerens Min-log, vil borgeren senere være i stand til at se at handlingen er udført af en anden person.

Dette brugsscenarie understøttes af operationen ConsentRevoke i den oprindelige version af grænsefladen til MinSpærring Administration.

Dette brugsscenarie understøttes af operationen ConsentRevokeV2 i den nye version af grænsefladen til MinSpærring Administration.

MinSpærring Administration Web Service

Læsevejledning

Skabelonen nedenfor bruges til at dokumentere de operationer, der tilbydes i MinSpærring Administration. De vigtigste elementer til input og output er beskrevet i MinSpærring Administration WebService Skemaer.

Web Service - ConsentAdministration (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

MinSpærring Verifikation Web Service Semantiker

Besked format

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 beskrevet i  [DGWS 1.0] og [DGWS 1.0.1]. Formatet for HSUID-headeren er beskrevet i  [HSUID-Header].

Attributter i HSUID headeren når bruger er borger

Når anvenderen af servicen er en borger så er det attributerne i tabel 1 der anvendes.

Tabel 1 Attributer i HSUID-header når bruger borger.

Attributter i HSUID headeren når bruger er sundhedsfaglig

Når brugere er en sundhedsfaglig person er det nedenstående attributter der skal være i HSUID headeren.

Tabel 2 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.

Web Service Sikkerhed

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.

Godkendelse

Godkendelse af anvendersystemer

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.

Godkendelse af bruger

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.

Web Service Operaioner hvor anvender er borger eller person på vegne af borger

Servicen godkender alle borgere.

Det er anvenders ansvar at sikre at personen må agere på vegne af borger. 

Udløb af ID-kort

En request med et ID-kort der er mere end 24 timer gammelt i forhold til udstedelsestidspunkt afvises.

Status koder og flow status

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 ved web-service operationer

Timeout er det samme som standard timeout på NSP platformen.

Session

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.

Tildeling og genbrug af flow-ID

Hvis request indeholder et flow-ID bliver det genbrugt i svaret. Håndtering af flow-ID sker i henhold til DGWS 1.0.1.

Behandling af anmodning om 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].

Digital signering af svar understøttes ikke. På anmodning om Non-Repudiation returneres en fejlfejlmeddelelse som beskrevet i [DGWS 1.0].

Fejlhåndtering

SOAP fejl

SOAP-fejl returneres som beskrevet nedenfor. Der er valgt en struktur, hvor både standardfejlkoder som beskrevet i [DGWS 1.0] og servicespecifikke fejlkoder kan returneres.

<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>

Kodeliste 1 Struktur af SOAP-fejl returneret fra Web Service Operation. Eksemplet viser FaultCode, der bruges, når ID-kortet er udløbet.

SOAP Fault Status Koder

For alle web service operationer, der er beskrevet i afsnit 3, anvendes SOAP-fejl med FaultCode-værdier som anført i tabel 2, der stammer fra DGWS 1.0.1.

Tabel 3 Anvendte Faultcode værdier stammende fra DGWS 1.0.1

Derudover anvendes tjenestespecifikke FaultCode værdier som anført i tabel 4.

Table 4 Applied service-specific FaultCode values

WSDL'en tilhørende servicen specificerer ikke SOAP fejlkoder for hver operation.

Web Service Input Validering

Nedenstående valideres:

• Korrekt formateret HSUID-header er inkluderet i SOAP-headeren, inklusive de attributter, der henholdsvis kan og skal være til stede for en given brugertype som beskrevet i afsnit 4.1.1. Desuden valideres det, at attributværdier hører til etablerede værdisæt og ikke er null eller simpelthen mellemrum

• ID kort i security header er valid og signeret af STS'en og yderlige krav i sektion 4.2 er opfyldt.

• CPR numre er gyldige og findes i enten autorisationsregistret (for sundhedspersoner) eller stamdataregistret (for borgere).
  
• Organisations ID'er er valide. Valid betyder at det er en valid SOR, SHAK eller Yder nummer.
  
• At ValidFrom ikke ligger i fortiden. Bemærk at man som anvender godt kan angive 'nu' som ValidFrom, systemet tillader værdier der ligger en lille smule før serverens tid (som udgangspunkt 60 sekunder).

Nedenstående udføres IKKE:

• XML skema validering.
  

• Validering af, at de angivne autorisationsnumre er gyldige og findes i autorisationsregisteret
  

• Validering af, at der er konsistens mellem sundhedspersonens organisations-id'er, når der gives flere ID- og klassificeringssystemer.

• Validering af, at en sundhedsperson er tilknyttet den angivne organisation

• Validering af, at brugeren handler på vegne af den erklærede sundhedsperson

Standarder

MinSpærring Verifikation er baseret på nedenstående standarder. :

1. SOAP version 1.1

2. Soap Fault version 1.1

3. WS-I Basic Profile 1.1

4. OIO navngivnings- og designregler

5. DGWS 1.0.1, med undtagelse af krav til videresendelse og kontrol af genbrug af meddelelses-ID som beskrevet i afsnit 4.5, og med undtagelse af struktur anvendt på fejl som beskrevet i afsnit 4.7.1.

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.

MinSpærring Administration WebService Skemaer

Dette afsnit giver en generel beskrivelse af nøgleelementerne i XML-skemaerne, der sammen med WSDL definerer de services der er beskrevet tidligere Hvor eksisterende OIO-typer identificeres, angives den i parentes efter elementnavnet. Derudover tilvejebringes kardinalitet, når et element ikke er obligatorisk.

ConsentItem

WhatItem

WhoItem

ConsentAdds

ConsentRegistrations

ConsentModification

ConsentRevocation

Styring

Dokumentation

Til MinSpærring Administration er grænsefladen mellem anvendersystemerne og administration versioneret.

Snitfladebeskrivelsen udgør kontrakten, der definerer, hvordan de involverede systemer skal handle.

Snitfladebeksrivelsen består af:

• den tekniske specifikation af skemaer og servicebeskrivelser (dokumenteret som en WSDL-fil, se afsnit 7)

• dokumentation for den semantiske og funktionelle betydning af data, der udveksles (dokumenteret i dette dokument).

Versionering

Som en del af WSDL for ConsentAdministration er der headers der er definereret i andre standarder. Selve request til ConsentVerification følger nedenstående navngivning.

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

Bemærk dog at hvis der laves nye versioner af snitfladen skal versioneringen ske ved hjælp af en datoangivelse som det kan ses i nyeste version af MinSpærring Aministration snitfladen.

WSDL

WSDL til servicen kan tilgås ved at tilgå det endpoint servicen udstiller WSDL på. I test2 miljøet er det http://test2-cnsp.ekstern-test.nspop.dk:8080/consent-administration/service?wsdl. Hvis tjenesten på NSP miljøet ikke er tilgængeligt kan servicen startes op ved hjælp af de leverede docker-compose filer og WSDL kan tilgås der.