D INTEGRATIONSDESIGN FOR DATAAFTAGERE

Transkript

1 DIGST ORKESTRERINGSKOMPONENT D INTEGRATIONSDESIGN FOR DATAAFTAGERE Version: 1.3 Status: Endelig Godkender: Forfatter: Copyright 2019 Netcompany. Alle rettigheder forbeholdes.

2 Dokumenthistorik Version Dato Forfatter Status Bemærkninger Endelig Endelig Endelig Endelig Tilføjet IDWSunderstøttelse Tilføjet CPR-nummer til request data i hent sagsdata-metode og hent ydelsesdatametode Opdateret pba. reviewkommentarer fra DIGST Referencer Reference Titel Forfatter Version FDM 1.3 Fælles datamodel 0.3 IFD D0180 Integrationsdesign for dataleverandør 1.4 IDWS OIO Identity Based Web Services 1.1 (OIO IDWS) (valideret 22. maj 2017) Netcompany 2

3 Indholdsfortegnelse 1 Introduktion Integration med Orkestreringskomponenten Metoder Hent data samlet Hent detaljeret sagsdata Hent detaljeret ydelsesdata Validering af borger-session Dataformater DataSourceResponse DataSourceRequest BorgerDataType BrugervendtSag Cpr-nummer-format Service-svartid Sikkerhed Forbindelsessikkerhed Yderligere mulighed IDWS Netcompany 3

4 1 Introduktion Dette dokument beskriver Orkestreringskomponent REST-snitflade for en applikation med en brugergrænseflade (f.eks. en portal), der benytter Orkestreringskomponenten til at hente data for en borger fra de forskellige dataleverandører, der udstiller data gennem Orkestreringskomponenten. 2 Integration med Orkestreringskomponenten Det er muligt for en applikation (f.eks. portal denne term anvendes fremadrettet for en aftager-komponent, der dog kan være af anden karakter end en reel portal) at hente data om en borger via Orkestreringskomponenten. Valider bruger OK-token Hent borgerdata PORTAL Data Hent sagsdata ORKESTRERINGS- KOMPONENT Sagsdata Hent ydelsesdata Ydelsesdata Orkestreringskomponenten udstiller metoderne beskrevet i de følgende afsnit. 2.1 Metoder Hent data samlet Titel Hent data samlet Henter data, der gælder for en borger med det cpr-nummer, der er angivet i kaldet. Det er muligt at specificere hvilke data fra hvilke datakilder skal hentes ved brug af datasources parameter. DataSources parameter kan indeholder en liste af DataSourceRequest objects, hvor man kan specificere: Beskrivelse fra hvilken datakilde data skal hentes, om detaljeret data skal hentes, for hvilken kommune data er gældende, om der skal returneres kun sager, kun ydelser eller begge dele på en gang Netcompany 4

5 URL Method URL params /borgerdata POST n.a. "X-TransactionId" : [string] "X-Auth-Token" : [string] Custom header X-TransactionId ID for transaktionen; dette ID medsendes i hele kald-kæden for at kunne spore et kald på tværs af systemer X-Auth-Token autentifikationstoken fra Orkestreringskomponent "cpr" : [string], "datasources" : [List<DataSourceRequest>] Data params cpr borgerens CPR-nummer datasources liste af DataSourceRequest-specifikationer; hvis listen er tom, hentes basisdata fra alle datakilder, som den kaldende part kan hente data fra Code: 200 (OK) Success response "data" : [List<DataSourceResponse>] data list af svar fra datakilder med borgerens data Code: 400 (Bad request) Error response Code: 401 (Unauthorized) 2019 Netcompany 5

6 Code: 500 (Internal Server Error) Sample call $.ajax( url : "/borgerdata", datatype : "json", data : "cpr" : " ", "datasources" : [ "datasourceid" : "ADDA", "detailedlevel" : false, "municipalitycode" : "101", "datatype" : 1, "datasourceid" : "ATP", "detailedlevel" : true, "datasourceid" : "SU", "datatype" : 0 ], type : "POST", success : function(r) console.log(r); ); 2019 Netcompany 6

7 2.1.2 Hent detaljeret sagsdata Titel Beskrivelse URL Method URL params Hent detaljeret sagsdata Henter detaljeret data om en sag, der har det ID, der er angivet i kaldet fra specifik datakilde. /sagsdata POST n.a. "X-TransactionId" : [string] "X-Auth-Token" : [string] Custom header X-TransactionId ID for transaktionen; dette ID medsendes i hele kald-kæden for at kunne spore et kald på tværs af systemer X-Auth-Token autentifikationstoken fra Orkestreringskomponent Data params "datasourceid" : [string], "sagsid" : [string], "cpr" : [string] datasourceid id for datakilden, hvor sagsdata skal hentes fra sagsid sagens id cpr borgerens CPR-nummer Code: 200 (OK) Success response "data" : [DataSourceResponse] data svar fra datakilde med sagsdata Code: 400 (Bad request) Error response Code: 401 (Unauthorized) 2019 Netcompany 7

8 Code: 500 (Internal Server Error) Sample call $.ajax( url : "/sagsdata", datatype : "json", data : "datasourceid" : "ADDA", "sagsid" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2", "cpr" : " ", type : "POST", success : function(r) console.log(r); ); Hent detaljeret ydelsesdata Titel Beskrivelse URL Method URL params Hent detaljeret ydelsesdata Henter detaljeret data om en ydelse, der har det ID, der er angivet i kaldet fra specifik datakilde. /ydelsesdata POST n.a. "X-TransactionId" : [string] "X-Auth-Token" : [string] Custom header X-TransactionId ID for transaktionen; dette ID medsendes i hele kald-kæden for at kunne spore et kald på tværs af systemer X-Auth-Token autentifikationstoken fra Orkestreringskomponent Data params "datasourceid" : [string], "ydelsesid" : [string], "cpr" : [string] 2019 Netcompany 8

9 datasourceid id for datakilden, hvor ydelsesdata skal hentes fra ydelsesid ydelsens id cpr borgerens CPR-nummer Code: 200 (OK) Success response "data" : [DataSourceResponse] data svar fra datakilde med ydelsesdata Code: 400 (Bad request) Code: 401 (Unauthorized) Error response Code: 500 (Internal Server Error) Sample call $.ajax( url : "/ydelsesdata", datatype : "json", data : "datasourceid" : "ADDA", "ydelsesid" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2", "cpr" : " ", type : "POST", 2019 Netcompany 9

10 success : function(r) console.log(r); ); Validering af borger-session Titel Beskrivelse URL Method URL params Validering af borger-session Veksler et medsendt IDWS-token til et Orkestreringskomponent-token, der kan benyttes i resten af borgerens indloggede session /validateuser POST n.a. "X-TransactionId" : [string] Custom header X-TransactionId ID for transaktionen; dette ID medsendes i hele kald-kæden for at kunne spore et kald på tværs af systemer Data params "cpr" : [string], "identitytoken" : [string] cpr borgerens CPR-nummer identitytoken token fra NemLog-in for borgeren angivet med cpr Code: 200 (OK) Success response "authenticationtoken" : [string] authenticationtoken token for den givne borger-session, som kaldende portal skal medsende i alle kald til Orkestreringskomponenten for den givne borger Code: 400 (Bad request) Error response 2019 Netcompany 10

11 Code: 401 (Unauthorized) Code: 500 (Internal Server Error) 2.2 Dataformater Dette afsnit indeholder beskivelse af de custom datatyper, der bliver brugt i Orkestreringskomponenten DataSourceResponse DataSourceResponse-klassen har følgende struktur: "datasourceid" : [string], "statuscode" : [string],, "data" : [Dictionary<BorgerDataType, List<BrugervendtSag>>] hvor: datasourceid datakildens id, der er defineret i Orkestreringskomponenten statuscode HTTP status code, som datakilden har svaret med message beskrivende tekst fra datakilden; benyttes kun til fejlsvar data svar fra servicen (tom, hvis der sker en fejl) Eksempel: 2019 Netcompany 11

12 "datasourceid" : "ADDA", "statuscode" : "200", "message" : "", "data" : "1" : [ "SagsId" : "1", "SagsTypeTitel" : "Kontanthjælp", "Status" : "Behandles", "SagsId" : "2", "SagsTypeTitel" : "Kontanthjælp", "Status" : "Afsluttet" ], "2" : [ "BevilgetYdelse" : [ "Status" : "Aktiv", "Ydelsesnavn" : "Tillæg", ] ] DataSourceRequest DataSourceRequest-klasse har følgende struktur: "datasourceid" : [string], "detailedlevel" : [boolean], "municipalitycode" : [string], "datatype" : [BorgerDataType] hvor: datasourceid datakildens id detailedlevel specificerer på hvilke niveau, der skal hentes data (true henter data på detaljeret niveau, false henter kun overbliksdata, default: false) municipalitycode borgerens kommunekode, der skal bruges til datafiltrering (benyttes kun af nogle datakilder) datatype - specificerer, hvilken type af data der skal returneres, f.eks. alt data, kun sager eller kun ydelser (OPTIONAL, default værdi: alt data) Eksempel: 2019 Netcompany 12

13 "datasourceid" : "ADDA", "detailedlevel" : true, "municipalitycode" : "101", "datatype" : 1 // kun sager BorgerDataType BorgerDataType er en flag-enum, der specificerer, hvilken datatype der skal hentes fra datakilden. [Flags] enum BorgerDataType Alle = 0, Sager = 1, Ydelser = BrugervendtSag BrugervendtSag er en klasse, der indeholder al information om sager, der er relevant til borgeren. Detaljeret beskrivelse af data er inkluderet i [FDM] Cpr-nummer-format Cpr-numre skal sendes som en tekststreng uden bindestreg, f.eks Service-svartid Orkestreringskomponentens svartider er afhængige af de forespurgte dataudbydere, og deres svaretider kan afhænge af niveauet af detaljering af data, der skal hentes fra dem. Kald til dataudbydere udføres som parallelle kald i Orkestreringskomponenten. Det betyder, at samling af svar fra alle datakilder afventer den datakilde, der er længst tid om at svare. Et eksempel: En portal kalder Orkestreringskomponenten for at hente data fra to datakilder, D1 og D2. Hentning af data fra D1 tager 2 sekunder, og fra D2 tager det 5 sekunder. Orkestreringskomponenten vil da returnere et svar efter ca. 6 sekunder, hvis det antages, at der samlet er 1 sekunds latency i netværk og processeringstid i Orkestreringskomponenten. 4 Sikkerhed Der opereres med to niveauer af sikkerhed ifm. integration med Orkestreringskomponenten. Det ene er forbindelsessikkerhed, der garanterer, at kun godkendte aftagere kan kalde og få svar fra Orkestreringskomponenten. Det andet niveau handler om at sikre, at der kun svares på forespørgelser på borger-data for borgere, når det kan valideres, at borgerne har en gyldig NemLog-insession for den kaldende portal. Begge niveauer er beskrevet i det følgende. 4.1 Forbindelsessikkerhed Følgende sikkerhedsmetoder er udviklet i Orkestreringskomponenten og gælder for alle applikationer, der skal hente data gennem Orkestreringskomponenten: SSL-certifikater understøttelse af sikker kommunikation 2019 Netcompany 13

14 FOCES klient-certifikater, der bruges til at identificere den kaldende applikation IP-Whitelisting for at sikre mod kald fra ikke- godkendte systemer eller direkte kald fra omverdenen Yderligere mulighed Et yderligere sikkerhedstiltag ift. autentificering kan være tilføjelse af en API-nøgle, der bliver givet af Orkestreringskomponenten. Dette vil endvidere kunne benyttes som en naturlig indikator i Orkestreringskomponenten ift. at udlede kalde-data/-statistik for portalers brug af Orkestreringskomponenten. 4.2 IDWS Orkestreringskomponenten benytter NemLog-ins IDWS-metodik til at sikre, at kaldende portaler kun kalder på vegne af reelle, indloggede borgere. Det betyder, at alle portaler, der ønsker integration med Orkestreringskomponenten, skal implementere IDWS-understøttelsen og for hver indlogget-borger-session sørge for veksling af borgerens IDWS-token til et Orkestreringskomponent-token inden første kald til Orkestreringskomponenten for borger-data for denne borger i den igangværende login-session. Token-veksling sker ved kald til Orkestreringskomponentens udstillede service for dette. Orkestreringskomponenten følger NemLog-ins best-practice-anbefalinger til gyldighedsperiode for Orkestreringskomponenttoken Netcompany 14