Page History
...
| Excerpt Include | ||||||
|---|---|---|---|---|---|---|
|
Formål
Baggrund
Hvorfor SOSI-GW?
SOSI-GW kontekst
NSP Gateway
Netværkskomponent
Security Token Service (STS)
Afkoblingskomponent
NSP services
Decentral anvendelse
Anvendelse af SOSI-GW
Signering af id-kort i anvendersystem
requestIdCardDigestForSigning
signIdCard
Browserbaseret signering
requestIdCardDigestForSigning
getValidIdCard
Gateway Proxy
proxy
Anvendelse af implicit login
Logge ud af SOSI-GW
logout
logoutWithResponse
Fejlkoder
Brug af SOSI-GW et delt miljø
Brug af PassThrough-header
Brug af signerede id-kort i proxy-kald
Version | Dato | Beskrivelse | Forfatter |
1 | 21-06-2016 | Første version, udarbejdet med udgangspunkt i "programmers guide - SOSI-GW" | OBJ |
...
Nærværende dokument udgør en guide til anvendere af SOSI-GW. Guiden er hovedsageligt målrettet eksterne anvendere af den centrale SOSI gateway som indgår i NSP platformen.
...
En hyppigt forekommende eksempel på anvendelse af en NSP service er, når en privatpraktiserende læge ønsker at hente en borgers medicinkort fra Det Fælles Medicinkort (FMK). Dette vil i praksis ske igennem lægens eget lægepraksissystem, som skal foretage et webservicekald med SOAP-action " http://www.dkma.dk/medicinecard/xml.schema/2015/01/01/E1#GetMedicineCard" til FMK for at hente medicinkortet.
FMK er blot en af mange NSP services. Overfor NSP er pågældende lægepraksissystem et af mange anvendersystemer.
NSP webservices er opbygget efter Den Gode WebService[ |http://medcom.dk/standarder/webservice-standarder/den-gode-webservice](DGWS), hvilket bl.a. betyder at der skal medsendes signerede id-kort i webservice-kald. I mange tilfælde er der krav om at anvende sikkerhedsniveau 4, hvor den enkelte bruger skal underskrive et id-kort med sin egen personlige digitale signatur. Hvis anvendersystemerne skulle kalde NSP webservices direkte, ville hvert enkelt system således være nødt til at håndtere signering af SOSI id-kort, og kende brugerens MOCES certifikat, hvilket kan være komplekst.
Det er her SOSI-GW kommer ind i billedet.
...
Formålet med SOSI¬GW er at flytte ansvaret for signering af SOSI id-kort fra de enkelte anvendersystemer til en central service. Denne service kan modtage requests og automatisk vedhæfte et signeret id-kort inden requests sendes videre til de endelige NSP service endpoints. Dermed behøver de enkelte anvendersystemer ikke at bekymre sig om at implementere signering af SOSI id-kort selv. I stedet håndteres dette af SOSI-GW.
Måden det foregår på er, at SOSI-GW gemmer selve id-kortet, men får en underskrift fra brugeren. Underskriften kan enten komme fra anvendersystemet eller via en browser-applet, der kan signere kortet via en normal browser. Anvendes browser-metoden, behøver anvendersystemet ikke at kende til brugerens certifikater eller signeringen af id-kort, men skal i stedet blot bekymre sig om at håndtere requests på den rette måde.
Der er dermed stadig er behov for, at brugeren selv signerer id-kortet. Men når et id-kort først er signeret, gemmes det i SOSI-GW indtil det udløber. Dette resulterer i, at NSP kan tilbyde Single Signon, da brugeren typisk kun bliver bedt om at signere id-kortet én gang i løbet af en normal arbejdsdag, selvom der foretages kald på tværs af NSP services.
...
SOSI-GW anvendes i forskellige konfigurationer. I dette afsnit beskrives hovedsageligt anvendelse af central SOSI-GW, som den der står foran de centrale NSP miljøer (cNSP).
...
Figur 1 illustrerer et centralt NSP setup med SSL overbygning, som f.eks. anvendes af kommunerne. I denne konfiguration er SOSI-GW placeret før afkoblingskomponenten (DCC). 
Figur 1: Central SOSI-GW på NSP-platform (NSP-Gateway/NGW).
Der er etableret et antal centrale NSP miljøer med dette setup, både drift-, test- og uddannelsesmiljøer. Der henvises til www.nspop.dk[ |http://www.nspop.dk/]for mere information om NSP platform og miljøer.
...
Anvendersystemets kald foretages med HTTPS. Komponenten der kaldes sikrer at der kaldes med et korrekt SSL-klientcertifikat, og at anvendersystemet er whitelistet til at kalde den ønskede service. Hvis dette er i orden viderestilles til SOSI-GW.
...
Beskeden fra anvendersystemet kan i første omgang blot være et kald til en NSP service, som indeholder et sikkerhedsniveau 1 id-kort. SOSI-GW vil så undersøge sin id-kort cache for at se om der findes et gyldigt signeret niveau 4 id-kort. Hvis dette er tilfældet erstattes niveau 1 id-kortet i beskeden med det signerede niveau 4-kort, og der stilles videre gennem DCC.
Hvis der ikke findes et signeret id-kort, eller det signerede id-kort et udløbet, sendes en DGWSFault tilbage til anvendersystemet som svar. Svaret vil udover fejlkode også indeholde SOAP-headers med en digest samt en URL til en webside, som kan anvendes til at signere et id-kort med. Anvendersystemet kan så vælge en af to muligheder:
- Anvendersystemet starter en almindelig browser med pågældende URL, hvorefter brugeren kan signere id-kortet ved at anvende sit personlige MOCES certifikat. Dette er den simpleste løsning for anvendersystemet.
- Anvendersystemet dekoder og RSA-signerer den returnerede digest, og foretager derefter kald til SOSI-GW's metode signIdCard kaldes.
SOSI-GW kalder i begge tilfælde STS for at få foretaget signering med føderationens certifikat. Hvis signeringen blev gennemført med succes, cacher SOSI-GW efterfølgende det signerede id-kort, som er gyldigt i et antal timer. Herefter kan anvendersystemet foretage kald igen, hvor der denne gang findes et signeret niveau 4 id-kort i SOSI-GW's id-kort cache.
...
Som udgangspunkt kalder SOSI-GW videre til den relevante NSP service igennem en afkoblingskomponent kaldet DCC (Decoupling Component). Afkoblingskomponenten vil ud fra beskedens SOAP-action afgøre hvilket konkret endpoint, der skal kaldes. Eksempelvis vil DCC'en kalde Det Fælles Medicinkort (FMK) når SOAP action er GetMedineCard.
...
Den konkrete NSP service, f.eks. FMK, vil som nævnt oftest blive kaldt igennem DCC.
Såfremt beskeden fra anvendersystemet indeholder en WsAddressing SOAP-header, hvor "To" er udfyldt, vil SOSI-GW kalde den pågældende URL direkte i stedet for at viderestille gennem DCC. Dette er illustreret på Figur 1 ved den stiplede pil fra SOSI-GW direkte til de forskellige NSP services.
...
Det foregående afsnit beskriver en konfiguration hvor NGW står foran cNSP, hvilket i praksis betyder at SOSI-GW kaldes først, og typisk viderestiller gennem DCC.
SOSI-GW anvendes også decentralt, hovedsageligt af regionerne, hvor der er etableret systemintegration mellem NSP og regional IT. Dette setup adskiller sig bl.a. ved at DCC her står før SOSI-GW, som vist på Figur 2: 
Figur 2: Decentral NSP (dNSP), med SOSI-GW placeret efter DCC
Anvendersystemet kan her f.eks. være en elektronisk patientjournal (EPJ). Afkoblingskomponenten afgør igen adressen på NSP service endpoint ud fra SOAP-action, og indsætter en WsAddressing SOAP-header med adresse i feltet "To" og SOAP-action i feltet "Action ". Herefter kaldes videre til SOSI-GW. SOSI-GW vil så håndtere signering vha. STS som beskrevet i forrige afsnit, og efterfølgende kalde direkte til NSP servicen specificeret i "To".
Der henvises til www.nspop.dk[ |http://www.nspop.dk/]for mere information om NSP platform og miljøer.
...
For at kalde NSP services igennem SOSI-GW skal der anvendes webservice-kald som indeholder et gyldigt niveau 1 id-kort i SOAP-headeren.
Dette er krævet for alle kald til og gennem SOSI-GW. Det er også muligt at anvende højere niveau id-kort, se venligt afsnittet "Brug af signerede id-kort i proxy-kald" for mere information om dette.
Signering af id-kort kan enten foretages af anvendersystemet, eller man kan overlade det til SOSI-GW ved at åbne en webside til signering i en browser. Hvilke metoder der skal kaldes for at anvende de 2 muligheder beskrives nærmere i dette afsnit.
...
| Table of Contents |
|---|
Version | Dato | Beskrivelse | Forfatter |
1 | 21-06-2016 | Første version, udarbejdet med udgangspunkt i "programmers guide - SOSI-GW" | OBJ |
| Anchor | ||||
|---|---|---|---|---|
|
Nærværende dokument udgør en guide til anvendere af SOSI-GW. Guiden er hovedsageligt målrettet eksterne anvendere af den centrale SOSI gateway som indgår i NSP platformen.
| Anchor | ||||
|---|---|---|---|---|
|
En hyppigt forekommende eksempel på anvendelse af en NSP service er, når en privatpraktiserende læge ønsker at hente en borgers medicinkort fra Det Fælles Medicinkort (FMK). Dette vil i praksis ske igennem lægens eget lægepraksissystem, som skal foretage et webservicekald med SOAP-action " http://www.dkma.dk/medicinecard/xml.schema/2015/01/01/E1#GetMedicineCard" til FMK for at hente medicinkortet.
FMK er blot en af mange NSP services. Overfor NSP er pågældende lægepraksissystem et af mange anvendersystemer.
NSP webservices er opbygget efter Den Gode WebService[ |http://medcom.dk/standarder/webservice-standarder/den-gode-webservice](DGWS), hvilket bl.a. betyder at der skal medsendes signerede id-kort i webservice-kald. I mange tilfælde er der krav om at anvende sikkerhedsniveau 4, hvor den enkelte bruger skal underskrive et id-kort med sin egen personlige digitale signatur. Hvis anvendersystemerne skulle kalde NSP webservices direkte, ville hvert enkelt system således være nødt til at håndtere signering af SOSI id-kort, og kende brugerens MOCES certifikat, hvilket kan være komplekst.
Det er her SOSI-GW kommer ind i billedet.
| Anchor | ||||
|---|---|---|---|---|
|
Formålet med SOSI¬GW er at flytte ansvaret for signering af SOSI id-kort fra de enkelte anvendersystemer til en central service. Denne service kan modtage requests og automatisk vedhæfte et signeret id-kort inden requests sendes videre til de endelige NSP service endpoints. Dermed behøver de enkelte anvendersystemer ikke at bekymre sig om at implementere signering af SOSI id-kort selv. I stedet håndteres dette af SOSI-GW.
Måden det foregår på er, at SOSI-GW gemmer selve id-kortet, men får en underskrift fra brugeren. Underskriften kan enten komme fra anvendersystemet eller via en browser-applet, der kan signere kortet via en normal browser. Anvendes browser-metoden, behøver anvendersystemet ikke at kende til brugerens certifikater eller signeringen af id-kort, men skal i stedet blot bekymre sig om at håndtere requests på den rette måde.
Der er dermed stadig er behov for, at brugeren selv signerer id-kortet. Men når et id-kort først er signeret, gemmes det i SOSI-GW indtil det udløber. Dette resulterer i, at NSP kan tilbyde Single Signon, da brugeren typisk kun bliver bedt om at signere id-kortet én gang i løbet af en normal arbejdsdag, selvom der foretages kald på tværs af NSP services.
| Anchor | ||||
|---|---|---|---|---|
|
SOSI-GW anvendes i forskellige konfigurationer. I dette afsnit beskrives hovedsageligt anvendelse af central SOSI-GW, som den der står foran de centrale NSP miljøer (cNSP).
| Anchor | ||||
|---|---|---|---|---|
|
Figur 1 illustrerer et centralt NSP setup med SSL overbygning, som f.eks. anvendes af kommunerne. I denne konfiguration er SOSI-GW placeret før afkoblingskomponenten (DCC).
Figur 1: Central SOSI-GW på NSP-platform (NSP-Gateway/NGW).
Der er etableret et antal centrale NSP miljøer med dette setup, både drift-, test- og uddannelsesmiljøer. Der henvises til www.nspop.dk[ |http://www.nspop.dk/]for mere information om NSP platform og miljøer.
| Anchor | ||||
|---|---|---|---|---|
|
Anvendersystemets kald foretages med HTTPS. Komponenten der kaldes sikrer at der kaldes med et korrekt SSL-klientcertifikat, og at anvendersystemet er whitelistet til at kalde den ønskede service. Hvis dette er i orden viderestilles til SOSI-GW.
| Anchor | ||||
|---|---|---|---|---|
|
Beskeden fra anvendersystemet kan i første omgang blot være et kald til en NSP service, som indeholder et sikkerhedsniveau 1 id-kort. SOSI-GW vil så undersøge sin id-kort cache for at se om der findes et gyldigt signeret niveau 4 id-kort. Hvis dette er tilfældet erstattes niveau 1 id-kortet i beskeden med det signerede niveau 4-kort, og der stilles videre gennem DCC.
Hvis der ikke findes et signeret id-kort, eller det signerede id-kort et udløbet, sendes en DGWSFault tilbage til anvendersystemet som svar. Svaret vil udover fejlkode også indeholde SOAP-headers med en digest samt en URL til en webside, som kan anvendes til at signere et id-kort med. Anvendersystemet kan så vælge en af to muligheder:
- Anvendersystemet starter en almindelig browser med pågældende URL, hvorefter brugeren kan signere id-kortet ved at anvende sit personlige MOCES certifikat. Dette er den simpleste løsning for anvendersystemet.
- Anvendersystemet dekoder og RSA-signerer den returnerede digest, og foretager derefter kald til SOSI-GW's metode signIdCard kaldes.
SOSI-GW kalder i begge tilfælde STS for at få foretaget signering med føderationens certifikat. Hvis signeringen blev gennemført med succes, cacher SOSI-GW efterfølgende det signerede id-kort, som er gyldigt i et antal timer. Herefter kan anvendersystemet foretage kald igen, hvor der denne gang findes et signeret niveau 4 id-kort i SOSI-GW's id-kort cache.
En alternativ måde at få et signeret id-kort, er ved at få foretaget en omveksling fra et signeret bootstraptoken til et id-kort. Hertil benyttes SOSI-GW's metode createIdCardFromBST, som viderestiller omvekslingsbeskeden direkte til STS'en.
| Anchor | ||||
|---|---|---|---|---|
|
Som udgangspunkt kalder SOSI-GW videre til den relevante NSP service igennem en afkoblingskomponent kaldet DCC (Decoupling Component). Afkoblingskomponenten vil ud fra beskedens SOAP-action afgøre hvilket konkret endpoint, der skal kaldes. Eksempelvis vil DCC'en kalde Det Fælles Medicinkort (FMK) når SOAP action er GetMedineCard.
| Anchor | ||||
|---|---|---|---|---|
|
Den konkrete NSP service, f.eks. FMK, vil som nævnt oftest blive kaldt igennem DCC.
Såfremt beskeden fra anvendersystemet indeholder en WsAddressing SOAP-header, hvor "To" er udfyldt, vil SOSI-GW kalde den pågældende URL direkte i stedet for at viderestille gennem DCC. Dette er illustreret på Figur 1 ved den stiplede pil fra SOSI-GW direkte til de forskellige NSP services.
| Anchor | ||||
|---|---|---|---|---|
|
Det foregående afsnit beskriver en konfiguration hvor NGW står foran cNSP, hvilket i praksis betyder at SOSI-GW kaldes først, og typisk viderestiller gennem DCC.
SOSI-GW anvendes også decentralt, hovedsageligt af regionerne, hvor der er etableret systemintegration mellem NSP og regional IT. Dette setup adskiller sig bl.a. ved at DCC her står før SOSI-GW, som vist på Figur 2:
Figur 2: Decentral NSP (dNSP), med SOSI-GW placeret efter DCC
Anvendersystemet kan her f.eks. være en elektronisk patientjournal (EPJ). Afkoblingskomponenten afgør igen adressen på NSP service endpoint ud fra SOAP-action, og indsætter en WsAddressing SOAP-header med adresse i feltet "To" og SOAP-action i feltet "Action ". Herefter kaldes videre til SOSI-GW. SOSI-GW vil så håndtere signering vha. STS som beskrevet i forrige afsnit, og efterfølgende kalde direkte til NSP servicen specificeret i "To".
Der henvises til www.nspop.dk[ |http://www.nspop.dk/]for mere information om NSP platform og miljøer.
| Anchor | ||||
|---|---|---|---|---|
|
For at kalde NSP services igennem SOSI-GW skal der anvendes webservice-kald som indeholder et gyldigt niveau 1 id-kort i SOAP-headeren.
Dette er krævet for alle kald til og gennem SOSI-GW, undtagen 'createIdCardFromBST'. Det er også muligt at anvende højere niveau id-kort, se venligt afsnittet "Brug af signerede id-kort i proxy-kald" for mere information om dette.
Signering af id-kort kan enten foretages af anvendersystemet, eller man kan overlade det til SOSI-GW ved at åbne en webside til signering i en browser. Hvilke metoder der skal kaldes for at anvende de 2 muligheder beskrives nærmere i dette afsnit.
| Anchor | ||||
|---|---|---|---|---|
|
Hvis et anvendersystem selv ønsker at implementere signering af id-kort kan dette gøres ved at kalde følgende SOSI-GW operationer:
| Anchor | ||||
|---|---|---|---|---|
|
Denne operation svarer til "login". Der returneres et digest som kan RSA-signeres med et certifikat.
Adresse | http://<host>:<port>/sosigw/service/sosigw |
SOAP-action | http://sosi.dk/gw/2007.09.01#requestIdCardDigestForSigning |
WSDL | sosigw.wsdl |
Namespace | http://sosi.dk/gw/2007.09.01 |
SOAP-headers | DGWS id-kort sikkerhedsniveau 1 |
| Anchor | ||||
|---|---|---|---|---|
|
Anvendes til signering af et id-kort.
Som input gives det RSA-signerede digest som der blev returneret til anvendersystemet af requestIdCardDigestForSigning, samt det certifikat som blev anvendt til signering.
Herefter vil SOSI-GW kalde STS, som signerer med føderationens certifikat, og lagre det resulterende signerede niveau 4 id-kort I sin cache
Hvis et anvendersystem selv ønsker at implementere signering af id-kort kan dette gøres ved at kalde følgende SOSI-GW operationer:
...
Denne operation svarer til "login". Der returneres et digest som kan RSA-signeres med et certifikat.
Adresse | http://<host>:<port>/sosigw/service/sosigw |
SOAP-action | http://sosi.dk/gw/2007.09.01#requestIdCardDigestForSigning01#signIdCard |
WSDL | sosigw.wsdl |
Namespace | http://sosi.dk/gw/2007.09.01 |
| SOAP-headers | DGWS id-kort sikkerhedsniveau 1 |
| Anchor | ||
|---|---|---|
|
...
|
...
|
Hvis man ikke ønsker at implementere signering af id-kort I anvendersystemet kan browserbaseret signering anvendes i stedet. Til dette kan følgende operationer anvendes:
| Anchor | ||||
|---|---|---|---|---|
|
Denne operation svarer til "login". Svaret indeholder en URL som kan anvendes til at starte en browsersessionAnvendes til signering af et id-kort.
Som input gives det RSA-signerede digest som der blev returneret til anvendersystemet af requestIdCardDigestForSigning, samt det certifikat som blev anvendt til signering.
Herefter vil SOSI-GW kalde STS, som signerer med føderationens certifikat, og lagre det resulterende signerede niveau 4 id-kort I sin cache.
Adresse | http://<host>:<port>/sosigw/service/sosigw |
SOAP-action | http://sosi.dk/gw/2007.09.01#signIdCard01#requestIdCardDigestForSigning |
WSDL | sosigw.wsdl |
Namespace | http://sosi.dk/gw/2007.09.01 |
SOAP-headers | DGWS id-kort sikkerhedsniveau 1 |
| Anchor | ||
|---|---|---|
|
...
|
...
|
...
getValidIdCard
Afgør om der findes et signeret Hvis man ikke ønsker at implementere signering af id-kort I anvendersystemet kan browserbaseret signering anvendes i stedet. Til dette kan følgende operationer anvendes:
...
Denne operation svarer til "login". Svaret indeholder en URL som kan anvendes til at starte en browsersession.
Denne operation kan kaldes af anvendersystemet, f.eks. hvert sekund, mens brugeren signerer id-kortet i browseren.
Såfremt brugeren ikke signerer id-kortet alligevel, men f.eks. kommer til at lukke browseren ved en fejl, er det vigtigt at tillade at processen kan afbrydes, og at der kan foretages forsøg på signering påny.
Adresse | http://<host>:<port>/sosigw/service/sosigw |
SOAP-action | http://sosi.dk/gw/2007.09.01#requestIdCardDigestForSigning01#getValidIdCard |
WSDL | sosigw.wsdl |
Namespace | http://sosi.dk/gw/2007.09.01 |
SOAP-headers | DGWS id-kort sikkerhedsniveau 1 |
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||
|---|---|---|
|
...
|
...
|
...
createIdCardFromBST
Anvendes til omveksling af et bootstrap token til et Afgør om der findes et signeret id-kort.
Denne operation kan kaldes af anvendersystemet, f.eks. hvert sekund, mens brugeren signerer id-kortet i browseren.
Såfremt brugeren ikke signerer id-kortet alligevel, men f.eks. kommer til at lukke browseren ved en fejl, er det vigtigt at tillade at processen kan afbrydes, og at der kan foretages forsøg på signering påny.
...
Adresse
Input er en omvekslingsbesked med indlejret bootstraptoken, som viderestilles i uforandret form til SOSI-STS’ens BST2SOSI snitflade.
Det resulterende idkort gemmes i idkort-cachen og returneres (uden signaturer).
Bemærk at denne operation ikke findes i WSDL for SOSI-GW.
Adresse: http://<host>:<port>/sosigw/service/sosigw
...
SOAP-action
/createIdCardFromBST
SOAPAction: http://
...
sundhedsdatastyrelsen.dk/
...
WSDL
sosigw
...
Namespace
...
/2022/
...
08/17#CreateIdCardFromBST
Se detaljer om omvekslingen i STS dokumentationen: STS Guide til anvendere og STS Guide til anvendere: Medarbejderomvekslinger
...
SOAP-headers
...
DGWS id-kort sikkerhedsniveau 1
| Anchor | ||||
|---|---|---|---|---|
|
...
Fejlkode | Beskrivelse |
sosigw_no_valid_idcard_in_request | Returneres hvis der mangler et UserIDCard i requestets SOAPheader. |
sosigw_missing_signinginfo_in_request | Retureneres hvis signeret digest eller certifikat mangler i kaldet til signIdCard. |
sosigw_syntax_error_in_request | Returneres når SOAP-headers ikke kan parses korrekt. |
sosigw_awaiting_signing | Returneres af getValidIdCard når der er et id-kort i cachen, som endnu ikke er signeret. |
sosigw_no_valid_idcard_in_cache | Returneres når der ikke findes et id-kort i cachen som matcher nameID i input. |
sosigw_internal_error | Generel fejlkode når der opstår uventede fejl. Se venligst serverens logfil for mere information. |
sosigw_proxy_error | Returneres hvis der opstår et problem med at kalde det ønskede endpoint gennem et proxy kald. |
sosigw_access_denied | Kaldende klient eller service er ikke whitelistet. |
| sosigw_invalid_request | Returneres af createIdCardFromBST hvis input requestet er ugyldigt. Fx hvis:
|
| Anchor | ||||
|---|---|---|---|---|
|
...