d0180 - integrationsdesign for dataaftagere

© Copyright 2019 Netcompany. Alle rettigheder forbeholdes.

D0180 - INTEGRATIONSDESIGN FOR DATAAFTAGERE

Version:

1.3

Status:

Endelig

Godkender:

Forfatter:

DIGST – ORKESTRERINGSKOMPONENT

D0180 - Integrationsdesign for dataaftagere

© 2019 Netcompany 2

Dokumenthistorik

Version Dato Forfatter Status Bemærkninger

1.0 23-04-2019 Endelig -

1.1 22-05-2019 Endelig Tilføjet IDWS-understøttelse

1.2 22-05-2019 Endelig

Tilføjet CPR-nummer til request data i hent sagsdata-metode og hent ydelsesdata-metode

1.3 12.06.2019 Endelig Opdateret pba. review-kommentarer 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)

https://www.digitaliser.dk/resource/3457606

(valideret 22. maj 2017)

1.1

https://www.digitaliser.dk/resource/3457606



Indholdsfortegnelse

1 Introduktion....................................................................................................................................................... 4

2 Integration med Orkestreringskomponenten ..................................................................................................... 4 2.1 Metoder ....................................................................................................................................................... 4

2.1.1 Hent data samlet ........................................................................................................................................... 4 2.1.2 Hent detaljeret sagsdata ............................................................................................................................... 7 2.1.3 Hent detaljeret ydelsesdata .......................................................................................................................... 8 2.1.4 Validering af borger-session .......................................................................................................................... 10

2.2 Dataformater ............................................................................................................................................... 11 2.2.1 DataSourceResponse ..................................................................................................................................... 11 2.2.2 DataSourceRequest ....................................................................................................................................... 12 2.2.3 BorgerDataType ............................................................................................................................................ 13 2.2.4 BrugervendtSag ............................................................................................................................................. 13 2.2.5 Cpr-nummer-format ...................................................................................................................................... 13

3 Service-svartid ................................................................................................................................................... 13

4 Sikkerhed ........................................................................................................................................................... 13 4.1 Forbindelsessikkerhed .................................................................................................................................. 13

4.1.1 Yderligere mulighed ...................................................................................................................................... 14 4.2 IDWS ............................................................................................................................................................ 14



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.

Orkestreringskomponenten udstiller metoderne beskrevet i de følgende afsnit.

2.1 Metoder

2.1.1 Hent data samlet

Titel Hent data samlet

Beskrivelse

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:

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.

PORTAL ORKESTRERINGS-

KOMPONENT

Hent borgerdata

Data

Hent sagsdata

Sagsdata

Hent ydelsesdata

Ydelsesdata

Valider bruger

OK-token



URL /borgerdata

Method POST

URL params n.a.

Custom header

"X-TransactionId" : [string]

"X-Auth-Token" : [string]

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

{

"cpr" : [string],

"dataSources" : [List<DataSourceRequest>]

}

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

Success response

Code: 200 (OK)

Content:

{

"data" : [List<DataSourceResponse>]

}

data – list af svar fra datakilder med borgerens data

Error response

Code: 400 (Bad request)

Content:

{

"message" : [string]

}

message – besked, der beskriver fejlen

Code: 401 (Unauthorized)

Content:

{


}




Code: 500 (Internal Server Error)

Content:

{


}


Sample call

$.ajax({

url : "/borgerdata",

dataType : "json",

data : {

"cpr" : "1501999511",

"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);

}

});



2.1.2 Hent detaljeret sagsdata

Titel Hent detaljeret sagsdata

Beskrivelse Henter detaljeret data om en sag, der har det ID, der er angivet i kaldet fra specifik datakilde.

URL /sagsdata

Method POST

URL params n.a.

Custom header






Data params

{

"dataSourceId" : [string],

"sagsId" : [string],

"cpr" : [string]

}

dataSourceId – id for datakilden, hvor sagsdata skal hentes fra

sagsId – sagens id


Success response

Code: 200 (OK)

Content:

{

"data" : [DataSourceResponse]

}

data – svar fra datakilde med sagsdata

Error response


Content:

{


}



Content:



{


}



Content:

{


}


Sample call

$.ajax({

url : "/sagsdata",

dataType : "json",

data : {


"sagsId" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2",

"cpr" : "1501999511"

},

type : "POST",


console.log(r);

}

});

2.1.3 Hent detaljeret ydelsesdata

Titel Hent detaljeret ydelsesdata

Beskrivelse Henter detaljeret data om en ydelse, der har det ID, der er angivet i kaldet fra specifik datakilde.

URL /ydelsesdata

Method POST

URL params n.a.

Custom header






Data params {


"ydelsesId" : [string],

"cpr" : [string]



}

dataSourceId – id for datakilden, hvor ydelsesdata skal hentes fra

ydelsesId – ydelsens id


Success response

Code: 200 (OK)

Content:

{

"data" : [DataSourceResponse]

}

data – svar fra datakilde med ydelsesdata

Error response


Content:

{


}



Content:

{


}



Content:

{


}


Sample call

$.ajax({

url : "/ydelsesdata",

dataType : "json",

data : {


"ydelsesId" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2",

"cpr" : "1501999511"

},

type : "POST",




console.log(r);

}

});

2.1.4 Validering af borger-session

Titel Validering af borger-session

Beskrivelse Veksler et medsendt IDWS-token til et Orkestreringskomponent-token, der kan benyttes i resten

af borgerens indloggede session

URL /validateuser

Method POST

URL params n.a.

Custom header




Data params

{

"cpr" : [string],

"identityToken" : [string]

}


identityToken – token fra NemLog-in for borgeren angivet med ”cpr”

Success response

Code: 200 (OK)

Content:

{

"authenticationToken" : [string]

}

authenticationToken – token for den givne borger-session, som kaldende portal skal medsende i

alle kald til Orkestreringskomponenten for den givne borger

Error response


Content:

{


}





Content:

{


}



Content:

{


}


2.2 Dataformater

Dette afsnit indeholder beskivelse af de custom datatyper, der bliver brugt i Orkestreringskomponenten.

2.2.1 DataSourceResponse

DataSourceResponse-klassen har følgende struktur:

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:

{


"statusCode" : [string],

"message" : [string],

"data" : [Dictionary<BorgerDataType, List<BrugervendtSag>>]

}



2.2.2 DataSourceRequest

DataSourceRequest-klasse har følgende struktur:

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:

{


"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",

}

]

}

]

}

}

{


"detailedLevel" : [boolean],

"municipalityCode" : [string],

"dataType" : [BorgerDataType]

}



2.2.3 BorgerDataType

BorgerDataType er en flag-enum, der specificerer, hvilken datatype der skal hentes fra datakilden.

2.2.4 BrugervendtSag

BrugervendtSag er en klasse, der indeholder al information om sager, der er relevant til borgeren. Detaljeret beskrivelse af data

er inkluderet i [FDM].

2.2.5 Cpr-nummer-format

Cpr-numre skal sendes som en tekststreng uden bindestreg, f.eks. ”2703980243”.

3 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-in-

session 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

{


"detailedLevel" : true,

"municipalityCode" : "101",

"dataType" : 1 // kun sager

}

[Flags]

enum BorgerDataType

{

Alle = 0,

Sager = 1,

Ydelser = 2

}



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

4.1.1 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 Orkestreringskomponent-

token.

d0180 - integrationsdesign for dataaftagere

Documents