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
LogEntry
Logentry for hændelsen med angivelse af borger, bruger og evt. ansvarlig, organisation og system samt anvender session og tidspunkt.
Objektet indeholder følgende information:
---------------------------------------------
id
regKode -- Unique enforced af constraint
cprNrBorger -- CPR-nummer for den borger, hvis data der er forsøgt tilgået.
bruger -- CPR for person som har tilgået eller forsøgt at tilgå borgerens data. CPR 0000000000 kan benyttes efter aftale med NSI, hvor registrator så har ansvaret for at kunne fremfinde personens identitet.
ansvarlig -- CPR på sundhedsperson eller borger, der er handlet på vegne af ifbm. tilgang til eller forsøg på tilgang til borgerens data. CPR 0000000000 kan benyttes efter aftale med NSI, hvor registrator så har ansvaret for at kunne fremfinde personens identitet. Kan være tom.
orgUsingID -- Identifikation af tilknyttet organisation ved hjælp af SOR-kode, SHAK-kode, ydernummer, p-nummer, cvr-nummer eller kommunekode samt angivelse af hvilken af disse typer, der anvendes som identifikation. Anvendes kun, når bruger er sundhedsperson. Når registreringen omhandler sundhedspersons adgang til borgers data er elementet krævet, medmindre andet er aftalt i den serviceaftale, som anvender af servicen har indgået med den dataansvarlige myndighed (NSI).
orgUsingName_id -- relation til OrganisationName
systemName -- Identifikation eller navn på kildesystem hvorfra forsøg på tilgang til borgers data er sket.
handling -- Tekstuel beskrivelse af den handling, bruger har udført i forbindelse med forsøg på tilgang til borgers data.
sessionId -- Et teknisk sessions id, der i kontekst af anvendersystemet unikt identificerer den session, som bruger var i, da handlingen blev gennemført.
tidspunkt -- Tidspunktet for tilgang eller forsøg på tilgang til borgers data. Dato og tid skal anføres i Zulu-tid og med millisekunder.
OrganisationName
Indeholder organisations navnet som brugeren tilhører
Objektet indeholder følgende information:
---------------------------------------------
name -- Navn på sundhedspersonens organisation. Når registreringen (LogDataEntry) omhandler sundhedspersons adgang til borgers data er elementet krævet. Bemærk, at navnet skal være meningsfyldt for en borger.
digest -- relation fra LogEntry
Status
Benyttes til at optimere oprydningen af Minlog data.
Objektet indeholder følgende information:
---------------------------------------------
`id` --
`lastUpdated` --
Whitelist config (BRS)
Objektet indeholder de CVR som er whitelisted til brug på test/prod for BRS servicen
Objektet indeholder informationen:
---------------------------------------
service_key
-- BRS behandlingsrelationsservice:
+ dk.nsi.auth.query.type.cvr.list - BRS
+ dk.nsi.auth.create.type.cvr.list - BRS
+ dk.nsi.auth.brs.cvr.list - NO_TYPE
-- Min Log:
+ dk.nsi.minlog.registration (registration service)
+ minlogws (opslags service)
service_type
-- NO_TYPE
-- BRS
-- CPRSUBSCRIPTION
cvr -- CVR nummer
comment -- Her anføres NSP Jira nummer som relaterer den enkelte whitelisting
Tabelbeskrivelser
Tabel: LogEntry
CREATE TABLE LogEntry (
id bigint NOT NULL AUTO_INCREMENT,
regKode varchar(36) NOT NULL,
cprNrBorger varchar(10) NOT NULL,
bruger varchar(20),
ansvarlig varchar(20),
orgUsingID varchar(25),
orgUsingName_id int,
systemName varchar(25),
handling varchar(75),
sessionId varchar(46),
tidspunkt datetime NOT NULL,
PRIMARY KEY (id),
CONSTRAINT unique_constraint_regKode UNIQUE (regKode),
INDEX log_cpr_and_timestamp_index (cprNrBorger, tidspunkt))
ENGINE=InnoDB DEFAULT CHARSET=latin1 DEFAULT COLLATE=latin1_swedish_ci;
Tabel: OrganisationName
CREATE TABLE OrganisationName (
id int(11) NOT NULL AUTO_INCREMENT,
name varchar(256) NOT NULL,
digest bigint NOT NULL,
PRIMARY KEY (id),
INDEX organisation_name_digest_idx (digest))
ENGINE=InnoDB DEFAULT CHARSET=latin1 DEFAULT COLLATE=latin1_swedish_ci;
Tabel: status
CREATE TABLE `status` (
`id` int NOT NULL,
`lastUpdated` datetime not null,
PRIMARY KEY (`id`)
);
Fil: Minlog.log
Entries sendt til MinLogRegistrationService formatteres og gemmes i en logfil.
Fil: MinlogTransfer.log
Entries sendt til MinLogRegistrationService formatteres og gemmes i en logfil.
Sendes fra dNSP/cNSP til Backend via Minlog Transfer
Tabel: whitelist_config (BRS)
CREATE TABLE whitelist_config (
service_key VARCHAR(50) NOT NULL,
service_type VARCHAR(20) NOT NULL,
cvr CHAR(8) NOT NULL,
comment VARCHAR(100) NULL,
PRIMARY KEY (service_key, service_type, cvr)
); -- ENGINE=InnoDB COLLATE=utf8_bin;