Kom godt i gang

Integrationsvejledning ift. sikkerhed og versionering af webservice

Version: 2.0 Dato: 15-02-2017

Her kan du læse om, hvordan man integrerer til DIADEM’s sikrede web services. DIADEM er systemet, der ligge bagved ejendomsdatarapporten.

1. Indledning

1.1 Formål

Formålet med dette dokument er at beskrive, hvorledes man integrerer til DIADEM’s sikrede web services. Dokumentet er henvendt til virksomheder, der skal foretage den tekniske systemintegration, herunder it-arkitekter og systemudviklere.

1.2 Sikre webservices

DIADEM indeholder en række ejendomsoplysninger, som er forbundet med fortrolighed, og som derfor kun må udleveres til ejeren eller en virksomhed/person, som har modtaget en fuldmagt fra denne ejer. Det har derfor været vigtigt for DIADEM, at basere løsningen og de udstillede webservices på et tillidsfuldt sikkerhedskoncept. Sikkerhedskonceptet i DIADEM er baseret på fællesoffentlige standarder og identitetsbaserede webservices (IDWS). Det er et simpelt og godt koncept – set med ikke-tekniker øjne.

Grundlæggende bygger det på tillid mellem to sikkerhedssystemer – et hos DIADEM og et hos kunden. DIADEM identificerer kundens sikkerhedssystem gennem et certifikat og giver dette sikkerhedssystem adgang til at tildele nogle forud definerede roller til en medarbejder. Kundens sikkerhedssystem tildeler disse roller til de relevante personer. Når en medarbejder så ønsker at anvende DIADEM, udsteder sikkerhedssystemet en billet (”token”) med en identifikation af medarbejderen samt de roller denne er tildelt. DIADEM stoler på denne billet (udstedt af en billetudsteder vi har tillid til) og giver brugeren adgang til de funktioner, som rollerne i billetten giver adgang til.

Udover muligheden for finkortnet adgangsstyring på medarbejderniveau, rummer IDWS konceptet to andre fordele:

  • Det bliver eksplicit for udbyderen af web servicen (DIADEM) hvilke brugere, der anvender servicen, hvilket giver øget sporbarhed.
  • Brugeradministrationen kan foregå i brugerens egen organisation, som har de bedste forudsætninger for at vedligeholde det korrekte sæt af rettigheder. Dermed undgår DIADEM at skulle påtage sig administration af de kaldende virksomheders medarbejdere.

Figur 1illustrerer trinene i et scenarie, hvor en virksomhed anvender en intern Security Token Service (STS) til at udstede et token til brugeren:

Figur 1illustrerer trinene i et scenarie, hvor en virksomhed anvender
                     en intern Security Token Service (STS) til at udstede et token til brugerenFigur 1: Koncept ift. kald af identitetsbaseret webservice.

Konceptet er nærmere beskrevet i de efterfølgende kapitler.

1.3 Dokumentets indhold

Udover dette indledende kapitel indeholder dokumentet følgende kapitler:

  • Kapitel 2 – Identitetsbaserede webservices. Heri er en introduktion til IDWS konceptet. For en mere uddybende beskrivelse henvises til digitaliser.dk.
  • Kapitel 3 – DIADEM sikkerhedsmodel. Indeholder en beskrivelse af konceptet anvendt i hhv. et scenarie, hvor kunden anvender sin egen tokenudsteder (STS) og i et scenarie, hvor dette overlades til DIADEM’s tokenudsteder (STS).
  • Kapitel 4 – Proces for tilslutning og opsætning Her beskrives de trin, der i praksis skal gennemføres for at tilslutte et system til DIADEM, før der er adgang til at kalde DIADEM web services
  • Kapitel 5 – Supplerende udviklervejledning til DIADEM test projekterne. Kapitlet beskriver, hvorledes referenceimplementeringerne i Java og .Net (testprojekterne) kan bruges til at integrere mod DIADEM.

2. Identitetsbaserede webservices

2.1 Introduktion

Dette kapitel giver en introduktion til identitetsbaserede webservices på konceptuelt niveau. Begrebet “identitetsbaserede” web services (IDWS) er den overordnede tilgang til sikring af SOAP-baserede web services, som anvendes af DIADEM.

Kort fortalt går identitetsbaserede web services ud på sikring af system-til-system kommunikation (SOAP-baserede web services) på en måde, hvor det kaldende system (Web Service Consumer) både beviser sin egen identitet (f.eks. via et OCES virksomhedscertifikat), men også beviser identiteten for den kaldende bruger, som kaldet udføres på vegne af. Kaldet udføres altså i kontekst af en specifik bruger (typisk medarbejder), som kan være tildelt individuelle rettigheder i relation til web servicen. Dermed adskiller IDWS sig fra traditionel system-integration, hvor adgangen til at kalde services typisk kun afgøres ud fra kalderens identitet (f.eks. CVR nummer), og hvor finkornet adgangskontrol på brugerniveau dermed er langt mere vanskelig.

Figur 2 illustrerer forskellen på identitetsbaserede web services og traditionel system-til-system integration:

Figur 2 illustrerer forskellen på identitetsbaserede web services og
                     traditionel system-til-system integrationFigur 2: Systemintegration – Traditionel og med anvendelse af IDWS.

Et SOAP kald sikret med IDWS rummer normalt flg. hovedelementer, der er beskrevet i Liberty Basic SOAP Binding profilen:

  • Der anvendes server-autentificeret TLS/SSL til sikring af kommunikationen på transportniveau (integritet og konfidentialitet).
  • SOAP kaldet signeres med en digital signatur (SOAP headere og SOAP body), og kalderens certifikat (typisk OCES Virksomhedscertifikat eller funktionscertifikat) indlejres i SOAP headeren.
  • SOAP headeren rummer en SAML Assertion udstedt af en betroet part (typisk en såkaldt Security Token Service), der indeholder information om brugeren, som kaldet skal afvikles i kontekst af. Dette kan dels være brugerens identitet (f.eks. medarbejder ID), brugerens roller/rettigheder, samt hvor stærkt brugeren er autentificeret hos kalderen (såkaldt assurance level).

Den fællesoffentlige standard for identitetsbaserede web services (”OIO IDWS”) bygger på åbne, internationale standarder som WS-Security, WS-Trust, SAML mv. OIOIDWS består af en række profiler, der findes publiceret på Digitaliser.dk.

For yderligere uddybning henvises til: http://digitaliser.dk/resource/329866

2.2 Kald af identitetsbaserede webservices

Før en Web Service Consumer kan kalde en Web Service Provider skal der udstedes en SAML Assertion (security token) for den aktuelle bruger. Til dette brug kan man anvende OIO WS-Trust profilen mod en Security Token Service.

Figur 3 illustrerer, hvor de forskellige profiler kommer i anvendelse i et scenarie, hvor en bruger logger sig ind på en serviceudbyder, hvorefter serviceudbyderen kalder videre til en webserviceudbyder på vegne af den bruger, der er logget ind.

Figur 3 illustrerer, hvor de forskellige profiler kommer i anvendelse
                     i et scenarie, hvor en bruger logger sig ind på en serviceudbyder, hvorefter serviceudbyderen
                     kalder videre til en webserviceudbyder på vegne af den bruger, der er logget ind.
                     Figur Figur 3 - Kald af identitetsbaserede webservices

OIO WS-Trust Profile:
Beskriver hvorledes en applikation kan anmode om at få udstedt et security token med henblik på et efterfølgende web service kald for en bruger. Profilen beskriver alene beskedformatet for de meddelelser, der udveksles.

OIO Bootstrap Token Profile:
Beskriver en attribut, der rummer et såkaldt ”bootstrap token”, der kan anvendes til at identificere brugeren overfor en STS, når der anmodes om et security token. Boostrap tokenet udtrækkes konkret af applikationen og anvendes i WS-Trust kaldet mod STS’en.

Liberty Basic SOAP Binding:
Beskriver hvad et web service kald fra en Web Service Consumer til Web Service Provider skal indeholde samt regler for behandling. Profilen detaljerer udseendet af SOAP meddelelsen med særlig vægt på SOAP headere, foreskriver transportniveaukryptering, signering af meddelelsen og medsendelse af security tokens.

3. Diadem sikkerhedsmodel

3.1 Indledning

DIADEM løsningen indeholder en Security Token Server (”DIADEM STS”), som anvendes til at sikre mod uautoriseret brug af DIADEM.

DIADEM’s STS er opbygget udfra følgende retningslinier:

  • Overholdelse af OIO IDWS standarden.
  • Forberedt bedst muligt til at kunne udskiftes med den fællesoffentlige STS (”KFOBS projektet”), når denne foreligger.
  • Validerering af signaturen på et request.
  • Udstedelse af en IDWS token på baggrund af et signeret request.

Omkring de sikkerhedsbelagte services (OIO IDWS) arbejder DIADEM med to grundlæggende modeller:

  1. Det anvendende system har sin egen STS eller tilsvarende løsning, som udsteder en SAML token med brugeridentitet, tildelte rettigheder m.m. Dette er den model DIADEM p.t. anvender over for S2S løsninger.
  2. Det anvendende system benytter DIADEM’s STS, hvilket betyder at brugere skal være registreret her. P.t. anvendes denne løsning over for administratorer, som skal have særlige rettigheder ift. DIADEM. DIADEM ønsker p.t. ikke at skulle administrere alle kundens brugere, men der kan oprettes en testbruger pr. kunde, som kan anvendes til en ”hul igennem test”. Når den nye fællesoffentlige brugerrettighedsstyring (”KFOBS projektet”) er idriftsat i en stabil drift, forventer DIADEM at åbne op for model 2 generelt gennem anvendelse af den STS - med tilhørende brugerrettighedsstyring - som stilles til rådighed derfra.

3.2 S2S anvendelse med egen STS

Figur 4 viser S2S anvendelse med egen STS

Figur 4: S2S anvendelse med egen STS

Brugeren logger på kundens system og autentificeres her gennem de normale procedurer herfor i kundens brugerrettighedssystem. Når brugeren efterfølgende gennem et S2S interface ønsker at anvende en DIADEM service, kalder anvendersystemet kundens egen STS, som udsteder en token med de DIADEM roller, som brugeren er tildelt i kundens brugerrettighedssystem. Det er således op til kunden selv, at tildele DIADEM roller til de enkelte brugere.

Ønsker kunden ikke denne administration (ikke at begrænse brugen af DIADEM til udvalgte brugere), kan kundens STS indsætte disse roller for alle kundens brugere. Anvendersystemet kalder derefter den ønskede DIADEM services.

DIADEM validerer det pågældende kald gennem følgende valideringer:

  • Certifikatet svarende til kundens STS (det kaldende system) skal være registreret i DIADEM. Er det tilfældet, baseres anvendelsen på et tillidsforhold mellem DIADEM og den kaldende STS. DIADEM har således tillid til, at den pågældende STS har sikret autentifikation af brugeren inkl. de tildelte DIADEM roller.
  • I DIADEM er registreret hvilke roller, som den pågældende STS må tildele. Det valideres at der ikke er tildelt roller (eksempelvis ”administrator29, som den pågældende STS ikke har rettighed til at tildele.)

Er ovenstående ok, gennemføres kaldet af den pågældende DIADEM service.

3.3 STS med DIADEM STS

Figur 5 viser S2S anvendelse med DIADEM STS

Figur 5: S2S anvendelse med DIADEM STS

Brugeren logger på kundens system og autentificeres her gennem de normale procedurer herfor i kundens brugerrettighedssystem. Når brugeren efterfølgende gennem et S2S interface ønsker at anvende en DIADEM service, kalder anvendersystemet den pågældende DIADEM service med angivelse af en brugeridentitet (eksempelvis et MOCES certifikat).

DIADEM validerer det pågældende kald gennem følgende valideringer:

  • Certifikatet svarende til det kaldende system skal være registreret i DIADEM.
  • Er det tilfældet, foretager DIADEM et kald til DIADEM STS, som dels validerer den pågældende bruger, dels udsteder en token med de tildelte DIADEM roller.

Er ovenstående ok, gennemføres kaldet af den pågældende DIADEM service.

4. Proces for tilslutning og opsætning

Dette kapitel beskriver de trin, der i praksis skal gennemføres for at tilslutte et system til DIADEM, før der er adgang til at kalde DIADEM web services.

Der er specifikt 8 trin, som beskrives i afsnittene 4.1 - 4.3 nedenfor.

4.1 Forudsætninger

For systemmæssigt at kunne kommunikere med DIADEM-webservices skal følgende forudsætninger være opfyldt af anvenderen:

  1. Anvenderen skal være i besiddelse af et OCES-funktionscertifikat. Funktionssignaturen skal identificere anvenderen (anvenderens STS) overfor DIADEM.
  2. Der skal være indgået en aftale med ERST om anvendelse af DIADEM webservices til tests.

Aftalen skal downloades fra support-sitet, udfyldes med de nødvendige informationer (fremgår af aftalen), udskrives, underskrives, skannes og returneres til ERST på supportmailadressen support@ejendomsdatarapport.dk.

Indgåelse af aftale medfører, at anvenderen i testperioden opnår et fastkundeforhold til ERST, hvilket er nødvendigt, da det alene er fastkunder, der kan bestille ejendomsdatarapporter i testperioden.

4.2 Registrering af signatur i DIADEM

Når forudsætningerne er på plads, er det næste skridt

  1. at sende signaturens offentlige nøgle til ERST på supportmailen.

Når ERST melder tilbage at signaturen er registreret og oprettelse som fastkunde er udført (vil normalt ske indenfor et døgn fra modtagelsen af signaturen/aftalen), er de formelle ting på plads.

4.3 Dokumentation og testklienter

Så snart oprettelsesproceduren som fastkunde er fuldført, vil ERST levere følgende:

  1. DIADEM Programmers’ Guide (IFS002 DIADEM Programmers Guide.pdf)
  2. DIADEM Web Service Interface (IFS001 DIADEM Web Service Interface.pdf)
  3. WSDL- og xsd-filerne, som er samlet i zip-filen „Wsdl_xsd.zip“
  4. Den ønskede testklientpakke (.Net eller Java). Testklienterne indeholder testkald til alle services. Testprojekterne er sat op til at afvikle fejlfrit uden kodeændringer, når de nødvendige sikkerhedsindstillinger er opsat korrekt. Vi anbefaler at testprojekterne bruges som de er, indtil der er hul igennem til alle services. Der ydes kode support, baseret på opbygningen af testklienterne.
  5. En supplerende udviklervejledning, der bl.a. beskriver, hvorledes referenceimplementeringerne i Java og .Net (testprojekterne) kan bruges til at integrere mod DIADEM.