INDHOLD
Beskrivelse
SOSI-gw (ServiceOrienteret System Integration gateway): Teknologi til at håndtere en standardiseret form for integrationsmekanisme i sundhedssektoren for webservices og certifikater, baseret på nationale og internationale retningslinier og standarder.Der findes to forskellige setup.
- Et centralt NSP setup med SSL overbygning (cNSP), som f.eks. anvendes af kommunerne. I denne konfiguration er SOSI-GW placeret før afkoblingskomponenten (DCC) i et NSP-gateway miljø.
- SOSI-GW anvendes også decentralt (dNSP), 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.
Support ansvarlig: Trifork
NSP: NSP Gateway (NGW) - Leverancebeskrivelse
Forretningsanvendelse
Relaterede registre og services
Applikationsbeskrivelse
Centralt NSP Gateway setup
Her beskrives anvendelse af central SOSI-GW, som den der står foran de centrale NSP miljøer (cNSP).
Her er SOSI-GW placeret i et foranstillet miljø, NSP-gateway (NGW).
Diagrammet 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).
Netværkskomponent
-----------------------
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.
Security Token Service (STS)
-------------------------------
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.
Afkoblingskomponent
-------------------------
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.
NSP services
--------------
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 ved den optionale trigger (stiplede pil) fra SOSI-GW direkte til de forskellige services, uden om DCC komponenten.
Decentralt NSP Gateway setup
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å diagrammet.
Anvendersystemet kan her f.eks. være en elektronisk patientjournal (EPJ). Afkoblingskomponenten afgør 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 og efterfølgende kalde direkte til NSP servicen specificeret i "To".
SOSI-gateway applikationsbeskrivelse for både centralt og decentralt setup
FORMÅL:
=======
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.
Adresse http://<host>:<port>/sosigw/service/sosigw
WSDL https://wsdl.nspop.dk/sosigw/service/sosigw?wsdl
Namespace http://sosi.dk/gw/2007.09.01
SOAP-headers DGWS id-kort sikkerhedsniveau 1
SOSI-GW kræver ikke whitelisting
Anvendelse af SOSI-GW
================
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.
Signering af id-kort i anvendersystem
=========================
Hvis et anvendersystem selv ønsker at implementere signering af id-kort kan dette gøres ved at kalde følgende SOSI-GW operationer:
requestIdCardDigestForSigning
-----------------------------------
Denne operation svarer til "login". Der returneres et digest som kan RSA-signeres med et certifikat.
Denne benyttes til eksplicit oprettelse af et id-kort, klar til signering. Servicen kaldes af en klient for at etablere en session for en bruger, så der kan sendes signerede requests til andre services.
Servicen kræver et partielt id-kort, som SOSI-GW skal opbevare i signeret tilstand. I SOAPbody sendes derfor en SAMLassertion med samme indhold som for implicit oprettelse. Servicen returnerer den digestværdi som klienten skal signere sammen med en URL, der kan anvendes af en browser. Der skelnes ikke mellem URLrequests og WSrequests.
Usignerede id-kort fjernes automatisk fra serverne hvis der ikke er modtaget en signeret digest inden et vist interval. Dette interval er konfigurerbart.
SOAP-action http://sosi.dk/gw/2007.09.01#requestIdCardDigestForSigning
signIdCard
------------
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, checker at signaturen er gyldig og lagre det resulterende signerede niveau 4 id-kort I sin cache.
Argumenter til dette kald er NameID, SignatureValue og brugerens offentlige nøgle.
SOAP-action http://sosi.dk/gw/2007.09.01#signIdCard
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:
requestIdCardDigestForSigning
-----------------------------------
Denne operation svarer til "login". Svaret indeholder en URL som kan anvendes til at starte en browsersession.
SOAP-action http://sosi.dk/gw/2007.09.01#requestIdCardDigestForSigning
Anvendelse af implicit login
------------------------------
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.
getValidIdCard
-----------------
Afgør om der findes et signeret id-kort.
Denne metode henter id-kortet for en specifik bruger. Argumentet er NameID for brugeren, og returværdien er brugerens id-kort eller en fault.
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.
SOAP-action http://sosi.dk/gw/2007.09.01#getValidIdCard
logout
--------
Denne metode fjerner det signerede id-kort for en bestemt bruger. Som argument kræves NameID
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.
SOAP-action http://sosi.dk/gw/2007.09.01#logout
logoutWithResponse
-----------------------
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.
proxy
------
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.
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
SOSI-GW tillader nu alle id-kort niveauer, og proxy interfacet behandler de forskellige niveauer således:
Beskeder som videresendes uden udskiftning af id-kort:
Requests med niveau 2 id-kort
Requests med signeret niveau 3 og 4 id-kort
Øvrige beskeder behandles af SOSI-GW inden viderestilling:
Requests med niveau 1 id-kort
Requests med usigneret niveau 4 id-kort
Datastruktur, Intern register: SOSI-GW
Register properties:
Cache for ID-korts, konfiguration samt audit logning af SOSI-GW
Den lokale database anvendes udelukkende til at opsamle log-entries samt til lokal konfiguration
Den centrale database benyttes til opsamling og fletning af audit logs (log-merger).
Id-kort distribueres over en fælles cache, der drives af multicasting på lokalnettet
Entitetsbeskrivelser
lokal: runtimeconfig
Lokal konfiguration af SOSI-GW servicen
Den statiske, filbaserede konfiguration af SOSI-GW applikationen holdes på et minimum for at undgå omstændig kopiering af konfiguration, og for lettere at kunne honorere kravet om rullende opdateringer mm. Al anden konfiguration lægges i den lokale database på de enkelte servere og udveksles via multicast.
Konfigurationsdata gemmes altid som et komplet hele, der er forsynet med et tidsstempel, der identificerer og sammenbinder sammenhørende konfigurationsdata
Objektet indeholder informationen:
--------------------------------------
`configpk`
`moment` -- timestamp
lokal: runtimeconfig_data
Lokal konfiguration af SOSI-GW servicen
De enkelte værdier til hvert element i configurationen
Objektet indeholder informationen:
--------------------------------------
`datapk`
`elmpk` -- relation til runtimeconfig_element objektet
`idx`
`value`
lokal: runtimeconfig_element
Lokal konfiguration af SOSI-GW servicen
De enkelte elementer i configurationen
Objektet indeholder informationen:
--------------------------------------
`elmpk`
`configpk` -- relation til runtimeconfig objektet
`category`
`elmkey`
`valuecount`
lokal: sosigwlog
Auditlogning foretages lokalt på de enkelte servere (SOSGWLOG). Auditlogs persisteres lokalt i de decentrale databaser, der er installeret på alle SOSI-GW servere.
Med et konfigurerbart interval sender hver enkelt server opsamlede logs til den centrale log-merger database server (sosigwgloballog).
Til auditloggen logges følgende:
Proxyrequests Tidspunkt, NameID, Systemid, IP for afsender, endpoint, IDCardID (kortets) unikke id
Service requests Tidspunkt, NameID, Systemid, IP for afsender, operation, status (OK/ERR)
URL requests Tidspunkt, NameID, Systemid, IP for afsender, status (OK/ERR)
Objektet indeholder informationen:
--------------------------------------
`lpk` -- primær nøgle
`systemid` -- identifikation af serveren
`operation`
`cpr`
`moment` -- timestamp
`wsato` -- WSAddressing to, det endelige endpoint-URL
`wsaaction`
`clientip` -- identification af client som kalder SOSI-GW
lokal: Token Cache
SOSI-GW id-kort cache
Id-kort distribueres over en fælles cache, der drives af multicasting på lokalnettet
Når et id-kort skal signeres med føderationens certifikat, kalder SOSI-GW STS’en. Herefter indsætter SOSI-GW id-kortet i en cache.
Ved efterfølgende kald fra anvendersystemet erstattes det medsendte id-kort med det signerede id-kort fra cachen, inden viderestilling til den relevante NSP service.
central: clientip
IP identification af client som kalder SOSI-GW
Del af SOSI-GW audit logning.
Objektet indeholder informationen:
--------------------------------------
`pk`
`clientip` -- identification af client som kalder SOSI-GW
central: operation
operation
Del af SOSI-GW audit logning.
Objektet indeholder informationen:
--------------------------------------
`pk`
`operation`
central: sosigwgloballog
Auditlogning foretages lokalt på de enkelte servere (SOSGWLOG). Auditlogs persisteres lokalt i de decentrale databaser, der er installeret på alle SOSI-GW servere.
Med et konfigurerbart interval sender hver enkelt server opsamlede logs til den centrale log-merger database server (sosigwgloballog).
Til auditloggen logges følgende:
Proxyrequests Tidspunkt, NameID, Systemid, IP for afsender, endpoint, IDCardID (kortets) unikke id
Service requests Tidspunkt, NameID, Systemid, IP for afsender, operation, status (OK/ERR)
URL requests Tidspunkt, NameID, Systemid, IP for afsender, status (OK/ERR)
Del af SOSI-GW audit logning.
Objektet indeholder informationen:
--------------------------------------
`lpk` -- primær nøgle
`systemid` -- identifikation af serveren
`operation`
`cpr`
`moment` -- timestamp
`wsa` -- reference til "wsa" objektet som indeholder `wsato` og `wsaaction`
`clientip` -- identification af client som kalder SOSI-GW
central: systemid
identifikation af serveren hvor logningen blev foretaget.
Del af SOSI-GW audit logning.
Objektet indeholder informationen:
--------------------------------------
`pk`
`systemid` -- identifikation af serveren
central: wsa
Web Service Adressing (wsa)
Del af SOSI-GW audit logning.
Objektet indeholder informationen:
--------------------------------------
`pk`
`wsato` -- WSAddressing to, det endelige endpoint-URL
`wsaaction`
Tabelbeskrivelser
Cache: Token Cache
Id-kort distribueres over en fælles cache, der drives af multicasting på lokalnettet
Når et id-kort skal signeres med føderationens certifikat, kalder SOSI-GW STS’en. Herefter indsætter SOSI-GW id-kortet i en cache.
Ved efterfølgende kald fra anvendersystemet erstattes det medsendte id-kort med det signerede id-kort fra cachen, inden viderestilling til den relevante NSP service.
Tabel: clientip
DB: sosigwgloballog (fælles, delt, database til audit-logging)
CREATE TABLE `clientip` (
`pk` bigint(20) NOT NULL auto_increment,
`clientip` varchar(40) NOT NULL,
PRIMARY KEY (`pk`),
KEY `clientip_idx` (`clientip`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: operation
DB: sosigwgloballog (fælles, delt, database til audit-logging)
CREATE TABLE `operation` (
`pk` bigint(20) NOT NULL auto_increment,
`operation` varchar(32) NOT NULL,
PRIMARY KEY (`pk`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: RUNTIMECONFIG
DB: sosigwlog (Lokal database til audit-logging og konfigurationsdata for hver SOSI-GW instans)
CREATE TABLE `RUNTIMECONFIG` (
`configpk` bigint(20) NOT NULL auto_increment,
`moment` timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
PRIMARY KEY (`configpk`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: RUNTIMECONFIG_DATA
DB: sosigwlog (Lokal database til audit-logging og konfigurationsdata for hver SOSI-GW instans)
CREATE TABLE `RUNTIMECONFIG_DATA` (
`datapk` bigint(20) NOT NULL auto_increment,
`elmpk` bigint(20) NOT NULL,
`idx` int(11) NOT NULL,
`value` varchar(1000) default NULL,
PRIMARY KEY (`datapk`),
KEY `elmpk_idx` (`elmpk`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: RUNTIMECONFIG_ELM
DB: sosigwlog (Lokal database til audit-logging og konfigurationsdata for hver SOSI-GW instans)
CREATE TABLE `RUNTIMECONFIG_ELM` (
`elmpk` bigint(20) NOT NULL auto_increment,
`configpk` bigint(20) NOT NULL,
`category` varchar(64) NOT NULL,
`elmkey` varchar(64) NOT NULL,
`valuecount` int(11) NOT NULL,
PRIMARY KEY (`elmpk`),
KEY `configpk_idx` (`configpk`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: sosigwgloballog
DB: sosigwgloballog (fælles, delt, database til audit-logging)
CREATE TABLE `sosigwgloballog` (
`pk` bigint(20) NOT NULL auto_increment,
`systemid` int(11) NOT NULL,
`operation` int(11) NOT NULL,
`cpr` varchar(10) NOT NULL,
`moment` timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
`wsa` int(11) default NULL,
`clientip` int(11) default NULL,
PRIMARY KEY (`pk`),
KEY `moment_idx` (`moment`),
KEY `cpr_moment_idx` (`cpr`,`moment`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: SOSIGWLOG
DB: sosigwlog (Lokal database til audit-logging og konfigurationsdata for hver SOSI-GW instans)
CREATE TABLE `SOSIGWLOG` (
`lpk` bigint(20) NOT NULL auto_increment,
`systemid` varchar(64) NOT NULL,
`operation` varchar(32) NOT NULL,
`cpr` varchar(10) NOT NULL,
`moment` timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
`wsato` varchar(512) default NULL,
`wsaaction` varchar(512) default NULL,
`clientip` varchar(40) default NULL,
PRIMARY KEY (`lpk`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: systemid
DB: sosigwgloballog (fælles, delt, database til audit-logging)
CREATE TABLE `systemid` (
`pk` bigint(20) NOT NULL auto_increment,
`systemid` varchar(64) NOT NULL,
PRIMARY KEY (`pk`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Tabel: wsa
DB: sosigwgloballog (fælles, delt, database til audit-logging)
CREATE TABLE `wsa` (
`pk` bigint(20) NOT NULL auto_increment,
`wsato` varchar(512) default NULL,
`wsaaction` varchar(512) default NULL,
PRIMARY KEY (`pk`),
KEY `wsa_idx` (`wsato`(255))
) ENGINE=InnoDB DEFAULT CHARSET=utf8;