DIADEM KOM GODT I GANG INTEGRATIONSVEJLEDNING IFT. SIKKERHED OG VERSIONERING AF WEBSERVICES VERSION: STATUS: FRIGIVET DATO: 22.

Transkript

1 DIADEM KOM GODT I GANG INTEGRATIONSVEJLEDNING IFT. SIKKERHED OG VERSIONERING AF WEBSERVICES VERSION: STATUS: FRIGIVET DATO: 22. AUGUST 2013 Fil: DIADEM - Kom godt igang - Ver docx

2 Indhold 1. INDLEDNING FORMÅL SIKRE WEBSERVICES DOKUMENTETS INDHOLD IDENTITETSBASEREDE WEBSERVICES INTRODUKTION KALD AF IDENTITETSBASEREDE WEBSERVICES DIADEM SIKKERHEDSMODEL INDLEDNING S2S ANVENDELSE MED EGEN STS STS MED DIADEM STS PROCES FOR TILSLUTNING OG OPSÆTNING FORUDSÆTNINGER REGISTRERING AF SIGNATUR I DIADEM DOWNLOAD AF DOKUMENTATION OG TESTKLIENTER SUPPLERENDE UDVIKLERVEJLEDNING TIL DIADEM TEST PROJEKTERNE OVERBLIK VERSIONERING AF XSD OG WSDL CSHARP (.NET) JAVA SNITFLADEÆNDRINGER SIDEN SIDSTE VERSION

3 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 1, 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. Nedenstående figur illustrerer trinene i et scenarie, hvor en virksomhed anvender en intern Security Token Service (STS) til at udstede et token til brugeren: 1 Brugerne kan evt. identificeres via et pseudonym, der kun er kendt indenfor deres egen organisation. Dette giver stadig sporbarhed i forhold til at efterforske, hvem der har udført en specifik transaktion

4 Figur 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. Derudover er følgende bilag knyttet til dokumentet her: DIADEM Programmers Guide (IFS002 DIADEM Programmers Guide.pdf ) DIADEM Web Service Interface (IFS001 DIADEM Web Service Interface.pdf) WSDL- og xsd-filer (Wsdl_xsd.zip) - 4 -

5 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. Figuren nedenfor illustrerer forskellen på identitetsbaserede web services og traditionel system-til-system integration: Figur 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

6 OIOIDWS består af en række profiler, der findes publiceret på Digitaliser.dk. For yderligere uddybning henvises til: 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. Nedenstående figur 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. Kald af identitetsbaseret webservice. 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. OIO SAML Profile for Identity Tokens: Beskriver indholdet af de security tokens (i form af SAML 2.0 assertions), som udstedes af en STS til brug for et efterfølgende servicekald

7 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. S2S anvendelse med egen STS

8 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. 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)

9 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

10 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 7 trin, som beskrives i afsnittene 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 MBBL om anvendelse af DIADEMwebservices til tests. Aftalen skal downloades fra support-sitet, udfyldes med de nødvendige informationer (fremgår af aftalen), udskrives, underskrives, skannes og returneres til MBBL på supportmailadressen diademtest@mbbl.dk. Indgåelse af aftale medfører, at anvenderen i testperioden opnår et fastkundeforhold til MBBL, 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 3. at sende signaturens offentlige nøgle til MBBL på supportmailen. Når MBBL 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 Download af dokumentation og testklienter Hvis ikke det allerede er gjort, er de næste trin at hente 4. DIADEM Programmers Guide (IFS002 DIADEM Programmers Guide.pdf) 5. DIADEM Web Service Interface (IFS001 DIADEM Web Service Interface.pdf) 6. WSDL- og xsd-filerne, som er samlet i zip-filen Wsdl_xsd.zip 7. den ønskede testklientpakke (.Net eller Java). Testklienterne indeholder testkald til alle services. Alle dokumenter og filpakker findes på support-sitet. Følg herefter den udviklervejledning, der dels findes i kapitel 5 nedenfor og dels findes i den øvrige dokumentation

11 5. Supplerende udviklervejledning til DIADEM test projekterne. 5.1 Overblik Dette kapitel beskriver, hvorledes referenceimplementeringerne i Java og.net (testprojekterne) kan bruges til at integrere mod DIADEM. Fokus er på, hvordan virksomhederne kan konfigurere referenceimplementeringerne samt indbygge dem i egne applikationer. 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.2 Versionering af XSD og WSDL Startende i version 1.4.0, er der versionering af webservices og tilhørende skemaer. Skemaerne er versionsstyret via løbenummer i namespaces, mens webservices er versioneret via versionsnummer på endpoint og i de tilhørende kode klasser. En given webservice version er aktiv i stage og produktion, indtil der kommer 2 nye versioner af samme service. Eks: Version 1 aktiv 1. oktober. Version 2 aktiv 1. januar, version 1 fortsat aktiv. Version 3 aktiv 1. april, version 2 fortsat aktiv, version 1 ikke længere aktiv. 5.3 CSharp (.Net) CSharp klienten leveres som en Microsoft Visual Studio solution. Testene forudsætter desuden at NUnit er installeret (kan downloades fra Projektet består af 3 dele: app.config, der indeholder endpoint prefix til servicerne og til sts en samt de nødvendige referencer til MBBL s funktionscertifikat. (endpoint prefix er konfigureret til testmiljøet stage.diademservices.dk, det skal opdateres til diademservices.dk før anvendelse i produktion). CertificateUtilities.cs, der indeholder hjælpe metoder til at hente certifikater fra certifikat storen. CodeExamples.cs, der indeholder 1 kald til hver af de DIADEM services, I har adgang til. MBBL s funktionscertifikat (offentlig del) er vedlagt klienten og skal installeres i Local Machine\Trusted People, som det fremgår af DIADEM Programmers Guide. Testprojektet forventer at jeres eget private certifikat, der skal anvendes til SSL godkendelsen mod DIADEM, ligger i Local Machine\My. Dette kan ændres i metoden getcertificate i CertificateUtilities.cs

12 Øverst i CodeExamples.cs fremgår 4 variabler, der skal udfyldes korrekt: SecurityIdentifier, skal indeholde den tekst jeres certifikat er oprettet med på STS en (CVR:xxxxxxxx-RIDxxxxxxxxxxxx). Det er denne identifier STS anvender til validering af roller. useridentifier, skal indeholde en unik brugerid (anvendes til logning) CVR, skal indeholde CVR nummeret på den slutkunde, der anvender DIADEM. CVR-nummeret skal have en fastkundeaftale med MBBL, for at kunne bestille ejendomsdatarapporter. Anvend evt. eget CVR-nummer. certificatename, skal indeholde navnet på jeres eget certifikat. Variablen anvendes til at finde jeres certifikat i certificate store via getcertificate. Alle 4 variable anvendes i alle kald, bemærk dog at cvr er udskiftet med et fast cvr i metoden EjendomSoegViaEjerforhold, dette er for at sikre et positivt resultat i testen. CVR nummeret fremgår 2 gange i metoden, begge skal være ens for at metoden fungerer. 5.4 Java Java klienten leveres som et eclipse projekt, med alle nødvendige biblioteker i de versioner, der var tilgængelige på tidspunktet for udarbejdelsen af testprojektet. Links fremgår af DIADEM Programmers Guide. Testene er baseret på JUnit, nødvendige biblioteker er ligeledes vedlagt. Projektet består af følgende: Truststore indeholdende offentlige certifikater til SSL identifikation overfor STS en og DIADEM. En properties fil, der skal opdateres, før testen kan afvikles (se nedenfor), klienten er konfigureret til testmiljøet stage.diademservices.dk, for at anvende projektet i produktion, skal endpoints ændres til diademservices.dk. 7 source filer, 1 pr. Service samt en generel test fil. 4 hjælpe klasser til anvendelse af property filen samt load af certifikater. Property filen skal opdateres 6 steder, før I kan anvende testprojektet: Keystore.path, hvor ligger jeres eget certifikat (privat nøgle til SSL identifikation). Vær opmærksom på at Java ikke er glad for alle certifikat formater. Projektet har kun været testet med et PKCS12 certifikat. Keystore.pw, password til ovenstående Key. Pw, samme som keystore.pw Test.myCVR, skal indeholde CVR nummeret på den slutkunde, der anvender DIADEM. CVR-nummeret skal have en fastkundeaftale med MBBL, for at kunne bestille ejendomsdatarapporter. Anvend evt. eget CVR-nummer. Test.securityIdentifier, skal indeholde den tekst jeres certifikat er oprettet med på STS en (CVR:xxxxxxxx-RIDxxxxxxxxxxxx). Det er denne identifier STS anvender til validering af roller. Test.userIdentifier, skal indeholde en unik brugerid (anvendes til logning) Alle 3 Test.* variable anvendes i alle kald, bemærk dog at mycvr er udskiftet med et fast cvr i metoden EjendomSoegViaEjerforhold, dette er for at sikre et positivt resultat i testen. CVR nummeret fremgår både i EjendomSoegViaEjerfor

13 holdrequest.xml og metoden ejendomsoegviaejerforholdtest, begge skal være ens for at metoden fungerer. 5.5 Snitfladeændringer siden sidste version Følgende services er opdateret eller udgået i denne leverance. RapportService: Der er kommet en version 5, version 3 udgår. RapportStatus er udvidet med status Deaktiveret RapportElementStatus er udvidet med status UdeladesAfRapport og status IkkeTilgaengelig I RapportListeHent hentes ikke deaktiverede rapporter Versionering af rapporterne: Med den nye version af RapportHent, vil der altid returneres en rapport, der overholder den nyeste version af det tilhørende skema. Det vil sige at det ikke længere er nødvendigt at understøtte tidligere versioner, da de konverteres til nyeste version, når de hentes. Kompatibilitet: Såvel.Net som Java klienten understøtter kun nyeste versioner, hvis I ønsker at kalde en tidligere version, skal I anvende en tidligere version af klienterne..net opsætningen kræver ikke længere de enkelte endpoints, men blot et generelt prefix, der angiver hvilket miljø, der skal anvendes