Page History
| Navitabs | ||||
|---|---|---|---|---|
| ||||
| Anchor | ||||
|---|---|---|---|---|
|
SOSI-Gateway Guide til anvendere Indhold
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 |
...
| Excerpt Include | ||||||
|---|---|---|---|---|---|---|
|
| 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
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.
| Anchor | ||||
|---|---|---|---|---|
|
...
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 | |||
|---|---|---|---|
| |||
| 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 | ||||
|---|---|---|---|---|
|
...
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.
...
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#signIdCard | |
WSDL | sosigw.wsdl |
Namespace | http://sosi.dk/gw/2007.09.01 |
| SOAP-headers | DGWS id-kort sikkerhedsniveau 1 |
| Anchor | ||
|---|---|---|
|
...
|
...
|
...
Browserbaseret signering
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#requestIdCardDigestForSigning | |
WSDL | sosigw.wsdl |
Namespace | http://sosi.dk/gw/2007.09.01 |
SOAP-headers | DGWS |
...
id-kort sikkerhedsniveau 1 |
| Anchor | ||
|---|---|---|
|
...
|
...
|
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ånyDenne operation svarer til "login". Svaret indeholder en URL som kan anvendes til at starte en browsersession.
Adresse | http://<host>:<port>/sosigw/service/sosigw |
SOAP-action | http://sosi.dk/gw/2007.09. |
01#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
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Hvis der er et gyldigt, signeret id-kort I gateway'ens cache, vil denne metode viderestille til destinationen angivet i WsAddressing SOAP-headeren, eller til DCC, hvis informationen ikke findes i SOAP-headeren.
Hvis der ikke er et gyldigt signeret id-kort, vil en fejl blive returneret, indeholdende den samme information som returneres af requestIdCardDigestForSigning, dog placeret i en SOAP-header i response.
Bemærk at denne operation ikke findes i WSDL for SOSI-GW.
Adresse http://<host>:<port>/sosigw/proxy/soap-request
SOAP-headers DGWS id-kort sikkerhedsniveau 1, 2, 3 eller 4
| Anchor | ||||
|---|---|---|---|---|
|
Såfremt der anvendes browserbaseret signering er det også muligt helt at undlade at kalde requestIdCardDigestForSigning,
Hvis en NSP service forsøges kaldt igennem SOSI-GW med metoden proxy uden at der findes et signeret idkort i SOSI-GW, vil der blive returneret en fejl i form af en DGWSFault. Denne indeholder fejlkoden "sosigw_no_valid_idcard_in_cache", og der vil i svaret også findes en SOAP-header, som indeholder de samme data som requestIdCardDigestForSigning returnerer, blot i en header i stedet for i SOAP-body. Disse data kan anvendersystemet anvende til at åbne en browser, som beskrevet i afsnittet Browserbaseret signering.
Se venligst skemadefinition i "sosigw_implicitLoginHeader.xsd" for en schemabeskrivelse for dette response.
| Anchor | ||||
|---|---|---|---|---|
|
...
Fjerner id-kort fra cache. Operationen kan kaldes når en bruger logger af et anvendersystem, og også ønsker at logge af SOSI-GW.
Vælges at kalde logout vil brugeren af anvendersystemet skulle logge på, dvs. signere id-kort igen, næste gang der foretages kald til NSP services.
Adresse | http://<host>:<port>/sosigw/service/sosigw |
SOAP-action | http://sosi.dk/gw/2007.09.01#logout |
WSDL | sosigw.wsdl |
Namespace | http://sosi.dk/gw/2007.09.01 |
SOAP-headers | DGWS id-kort sikkerhedsniveau 1 |
| Anchor | ||||
|---|---|---|---|---|
|
Fjerner id-kort fra cache.
Denne operation er den samme som ovenfor, men der returneres "ok" eller DGWSFault, afhængigt af om pågældende id-kort blev fjernet fra cachen eller ej.
Adresse http://<host>:<port>/sosigw/service/sosigw
SOAP-action http://sosi.dk/gw/2007.09.01#logoutWithResponse
WSDL sosigw.wsdl
Namespace http://sosi.dk/gw/2007.09.01
SOAP-headers DGWS id-kort sikkerhedsniveau 1
| Anchor | ||||
|---|---|---|---|---|
|
Dette afsnit indeholder en liste med fejlkoder, som kan returneres fra SOSI-GW.
Bemærk at der også kan optræde andre fejlkoder I svar fra SOSI-GW, idet fejl fra STS og de NSP services der kaldes via proxy også returneres til anvendersystemet. Der henvises til dokumentationen for STS og øvrige NSP services såfremt der ønskes en komplet liste.
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 | ||||
|---|---|---|---|---|
|
...