Ibrugtagning af Adgangsstyring for brugere V 0.11

Transkript

1 Ibrugtagning af Adgangsstyring for brugere V 0.11

2 Indhold Formål og målgruppe... 3 Leverancen... 3 Indhold... 3 Hvad er Context Handleren og hvad indbefatter en integration med den... 4 Miljøer... 4 Forudsætninger for anvendelse af Context Handler... 5 Registrering af SAML metadata i Administrationsmodulet... 5 OIOSAML.Net metadata download URL... 5 OIOSAML.Java metadata download URL Installation af Context Handlerens SAML metadata i det Brugervendte system... 5 Context Handler metadata i projektmiljøet... 5 Context Handler metadata i ekstern testmiljøet... 5 Context Handler metadata i produktionsmiljøet... 5 Brugere til test-formål... 6 Afprøvning af Context Handler via eksempel koden... 7 Trin-for-trin guide til at bygge og deploye Java udgaven af CH.WebsiteDemo... 7 Trin-for-trin guide til at bygge og deploye.net udgaven af CH.WebsiteDemo Håndtering af kompileringsfejl på login tidspunkt Håndtering af signaturvalideringsfejl Validering af egen integration med Context Handleren Teknisk beskrivelse af stubben til genudstedelse af tokens Forudsætninger for anvendelse af stubbe Appendiks A: Tips og tricks Appendiks B: Specielt for projektmiljøet Oprettelse af Brugervendt System Test-brugere

3 Formål og målgruppe Formålet med dette dokument, er at skabe et samlet overblik over de opgaver der skal udføres af itleverandører i forbindelse med ibrugtagning af Støttesystemet Adgangsstyring for brugere, specifikt med fokus på at integrere et Brugervendt system med Adgangsstyring for brugere. Dokumentet dækker dermed ikke myndighedens opgave med at integrere en lokal Identity Provider med Adgangsstyring for brugere. Målgruppen er arkitekter og udviklere, der skal arbejde med selve integrationen til Adgangsstyring for brugere. Dokumentet er et KOMBIT udarbejdet følgedokument til KMDs leverance af stubbe, eksempelkode og dokumentation for støttesystemet Adgangsstyring for brugere, og skal ses som et samlet overblik over de komponenter og de opgaver der er i forbindelse med ibrugtagningen af støttesystemet. Obs! Hvis man er en tidlig anvender af Støttesystemet Adgangsstyring for brugere, og dermed har brug for at integrere mod projektmiljøet, bør man læse Appendiks B i dette dokument, da der er en række forskelle i hvordan integrationen skal foretages. Leverancen Selve leverancen kan downloades på KOMBITs eksterne dokumentbibliotek. Her skal man være opmærksom på at den version der kan downloades peger på et gammelt testmiljø, der ikke længere eksisterer. Der vil komme en opdatering af eksempelkoden der peger på det nye testmiljø. Specifikt er der tale om den ZIP-fil man kan downloade under stubbe, kodeeksempler og guidelines Security Token Service (G) og Context Handler (H). Zip-filen indeholder dokumentation, kode-eksempler og stubbe. Vær dog opmærksom på at ZIP-filen indeholder dokumentation m.m. for begge adgangsstyringssystemer, hvor dette dokument kun dækker Adgangsstyring for brugere. Endeligt bemærkes det at den tekniske komponent i Adgangsstyring for brugere kaldet for Context Handleren, og det er det navn der anvendes i såvel dokumentation, kode-eksempler og stubbe, og derfor også anvendes i dette dokument. Indhold Leverancen for Adgangsstyring for brugere består af 2 centralt hostede komponenter, hhv. - Teststub til genudstedelse af token - Context Handler til bruger-logon Samt kildekode til teststubben, og eksempelkode der viser hvordan man integrerer et Brugervendt System med Context Handleren. Teststubben til genudstedelse af token er tiltænkt leverandører, der har brug for at automatisere testcases. Stubben kan tage et token der er udløbet, og udstede et nyt frisk token med samme indhold men med opdateret gyldighedsperiode og signatur. 3

4 Hvad er Context Handleren og hvad indbefatter en integration med den Context Handleren håndterer bruger-login for Brugervendte systemer (fx KY, KSD, SAPA og DHUV). Context Handleren opfylder dermed samme rolle som NemLog-in gør for offentlige hjemmesider, hvor NemLog-in håndterer login for en række offentlige hjemmesider (skat.dk, borger.dk, osv). Hvis man har erfaring med at integrere med NemLog-in, vil man opleve at det er den samme teknologi man skal anvende, og at det er de samme opgaver der skal udføres, dvs: - Det Brugervendte system skal være en SAML 2.0 Service Provider - Det Brugervendte system skal danne SAML 2.0 metadata, og udveksle disse med Context Handleren - Det Brugervendte system skal understøtte SAML 2.0 protokollen, og kunne håndtere såvel Single Sign-On og Single Logout requests Typisk vil et Brugervendt system håndtere dette ved at anvende et kode-framework (fx Digitaliseringsstyrelsens OIOSAML bibliotek). Her skal man dog være opmærksom på, at KOMBIT stiller yderligere tekniske krav beskrevet i KOMBITs Attributprofil (Se Appendix A i Bilag 2A på KOMBIT s dokumentbibliotek for detaljer omkring Attributprofilen). Disse krav omhandler primært håndtering af brugersystemroller og dataafgrænsninger, og kodeeksemplerne man kan hente fra ZIP-filen viser eksempler på, hvordan man håndterer dette. Miljøer Context Handleren deployeres i 3 miljøer - Projektmiljø - Ekstern testmiljø - Produktionsmiljø Integration til Context Handleren sker separat for hvert miljø, idet miljøerne ikke er forbundet eller på anden måde deler data. Der henvises til tidsplanen for Støttesystemsprojektet for datoer på hvornår de enkelte miljøer er klar. Dog skal man være opmærksom på at Projektmiljøet ikke er et blivende miljø, og alene eksisterer i projektets levetid. Hvis man har brug for at integrere mod Adgangsstyring for brugere før det eksterne testmiljø er klar, skal man anvende projektmiljøet. Her gælder der nogle specielle integrationsprocedurer, der er beskrevet i Appendiks B. 4

5 Forudsætninger for anvendelse af Context Handler For at et Brugervendt system kan integrere med Context Handleren, skal det oprettes i Støttesystem Administrationsmodulet. Det er Administrationsmodulet, der efterfølgende sørger for at registrere metadata om det Brugervendte system i Context Handleren, og leverandøren af det Brugervendte system skal ikke selv lave nogen opsætning direkte i Context Handleren. Registrering af SAML metadata i Administrationsmodulet Leverandøren af det Brugervendte system skal logge på Administrationsmodulet i det miljø, som der skal integreres til. Her skal det Brugervendte system oprettes som et it-system af typen Brugervendt System, og i den forbindelse kan man uploade SAML metadata til Administrationsmodulet. Der henvises til Administrationsmodulets dokumentation og brugervejledninger for en beskrivelse af hvordan denne opgave udføres, hvilket bl.a. også dækker registrering af hvilke brugersystemroller og dataafgrænsninger som det Brugervendte system understøtter. De SAML metadata, der skal uploades, bliver typisk generet af det SAML bibliotek man anvender. Hvis man fx anvender Digitaliseringsstyrelsens OIOSAML bibliotek, så vil man kunne downloade SAML metadata service-endpoints som biblioteket automatisk udstiller (example.com erstattes med det DNS navn som det Brugervendte System kører på) OIOSAML.Net metadata download URL OIOSAML.Java metadata download URL Installation af Context Handlerens SAML metadata i det Brugervendte system Som en del af opsætningen af SAML biblioteket i det Brugervendte system, skal der ske en indlæsning af Context Handlerens metadata. Formålet med dette er at skabe en tillidsrelation mellem det Brugervendte system og Context Handleren, så det Brugervendte system stoler på de tokens som udstedes af Context Handleren. Metadata indeholder også URL endpoints på de logon/logout håndtag som Context Handleren udstiller. Registreringen af Context Handlerens metadata sker typisk som en del af installation/opsætnings processen når man tager et SAML bibliotek i brug, og de præcise trin afhænger af det valgte bibliotek. Metadata for Context Handleren er forskelligt fra miljø til miljø, og de relevante metadata for hvert miljø kan hentes her Context Handler metadata i projektmiljøet Context Handler metadata i ekstern testmiljøet Context Handler metadata i produktionsmiljøet Pt. ukendt 5

6 Brugere til test-formål Når det Brugervendte system er blevet integreret til Context Handleren, er det muligt for Context Handleren at håndtere bruger-logon for det Brugervendte system. Typisk vil man ønske at have en række brugere til test-formål, som man kan logge på via Context Handleren. Dette kræver, at der eksisterer en myndigheds-specifik Identity Provider, der er integreret til Context Handleren, da det er Identity Provideren der håndterer de egentlige brugere. Brugervendt System Login request Context Handler Delegering af login Identity Provider Som leverandør har man flere muligheder for at få adgang til test-brugere: 1. Da alle kommuner skal integrere en Identity Provider til Context Handleren, kan en af leverandørens eksisterende kunder allerede have en Identity Provider integreret til Context Handleren, og så kunne leverandøren bede sin kunde om at oprette nogle test-brugere for sig. 2. Leverandøren kan i ekstern test-miljøet oprette en fiktiv myndighed, og tilslutte sin egen Identity Provider. 3. Endeligt er der i projektmiljøet oprettet en Identity Provider til demo formål. Man har ikke mulighed for at få oprettet egne brugere her, men for at teste hul-igennem, kan man anvende en af de brugere der findes i denne Identity Provider (se Appendix B). 6

7 Afprøvning af Context Handler via eksempel koden I ZIP-filen findes en række eksempel projekter skrevet i hhv Java og.net. Her findes der specifikt 2 projekter, der er eksempler på, hvordan Brugervendte systemer kan integrere med Context Handleren. Det er projekterne - Kombit.Samples.CH.WebsiteDemo (.NET udgaven) - Kombit.Samples.Java/CH.WebsiteDemo (Java udgaven) For begge projekter gælder, at de baserer sig på Digitaliseringsstyrelsens OIOSAML bibliotek, og at de kommer pre-konfigureret med en integration til Context Handleren. Denne integration KAN IKKE genbruges i andre projekter, og er kun til demonstrationsformål. Når et Brugervendt system skal integreres til Context Handleren, skal den anvende sit eget (test/prod FOCES) certifikat, og danne sine egne metadata. Ved korrekt deployment af eksempelprojekterne ovenfor, vil man ved at tilgå det deployede projekt i sin webbrowser, blive ledt igennem et login forløb, der efterlader en på en velkomstside. Trin-for-trin guide til at bygge og deploye Java udgaven af CH.WebsiteDemo Nedenstående trin beskriver, hvordan en udvikler kan tage eksempel koden i CH.WebsiteDemo folderen, og deployere en lokal udgave af projektet til test-formål. Det antages at udvikleren har Oracle JDK 7 samt Netbeans 8 IDE et installeret. Det anbefales at anvende Netbeans EE udgaven, da den har en indbygget Glassfish container (alternativt skal man lave et manuelt deployere i en separat installeret Glassfish). 1. Importer begge projekter (kombit-opensaml og Kombit.Samples.CH.WebsiteDemo) i Netbeans 8 IDE et (højreklik og vælg Open Project ). 2. Hvis Java 8 anvendes, så skal filen CH.WebsiteDemo/src/java/META- INF/services/javax.xml.validation.SchemaFactory tilrettes, da den ikke følger standarden (og Java 8 er noget mere striks med valideringen). Se mere her: 3. Sørg for at Java er opdateret med stærk krypto (Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files). De nødvendige filer kan hentes fra Oracles hjemmeside, man skal blot sørge for at hente den version der passer til den udgave af Java som man anvender Rediger fil "CH.WebsiteDemo/web/WEB-INF/web.xml", og tilpas stien til "oiosaml-j.home", så den peger på folderen "CH.WebsiteDemo/oiosaml-config/" i projektet (den fulde sti til denne folder) 5. Projektet kan nu bygges (højre-klik og vælg Clean and Build ) og deployeres (højreklik og vælg Deploy ) i Glassfish. 7

8 6. DNS navnet i de metadata som anvendes er claimapp.projekt-stoettesystemerne.dk, og under antagelse af at sample koden afvikles lokalt, skal følgende tilføjes til Windows hosts filen (typisk ligger den i c:\windows\system32\drivers\etc) claimapp.projekt-stoettesystemerne.dk 7. Åben websitet ( i en webbrowser, og klik på Page requiring login linket. 8. Vælg IDP upstream for WebsiteDemo i dropdown boksen og klik på OK. 8

9 9. Indtast brugernavnet admin og kodeordet VCfnYepizF3xTfziW2hbRwBdPhedDtXA og klik på OK. 10. Efter succesfuldt login, kommer denne resultatside 9

10 Trin-for-trin guide til at bygge og deploye.net udgaven af CH.WebsiteDemo Nedenstående trin beskriver hvordan man kan bygge og deploye.net udgaven af kode eksemplet i en IIS. Det antages at man har en Windows Server 2012 eller tilsvarende kørende (fx en Windows 7/8 Pro udgave), hvor der allerede er installeret en IIS 7.5,.NET frameworket samt en Visual Studio 2013 eller højere. 1. Start med at kompilere projektet i Visual Studio. 2. På filsystemet oprettes en folder under c:\inetpub, fx c:\inetpub\kombit.samples\ 3. Indholdet af kode-eksempel folderen Kombit.Samples.CH.WebsiteDemo kopieres ind i ovenstående folder 4. I IIS Manager programmet oprettes en ny applikation ved navn claimapp.projektstoettesystemerne.dk, der udfyldes som nedenstående screenshot. SSL certifikatet kan være et vilkårligt certifikat, evt IIS s indbyggede test-certifikat hvis dette ønskes. 10

11 5. Application Pool for den nyoprettede applikation sættes til Network Services, og det sikres at denne er sat til at anvende.net 4.5 Frameworket (burde være default) 6. Den lokale hosts fil tilrettes, så følgende DNS navn peger på (typisk ligger hosts filen i c:\windows\system32\drivers\etc) claimapp.projekt-stoettesystemerne.dk 7. I Certificates folderen der kom sammen med eksempel koden, ligger der nogle certifikater der skal installeres. Dette gøres via mmc.exe og Certificates snap-in et. a. Åben mmc (start -> kør -> mmc.exe) b. Klik på Filer og vælg Tilføj/Fjern snap-in c. Vælg Certificates i listen og klik Tilføj. d. Vælg Computerkonto når der spørges efter hvilket certificate-store der ønskes tilføjet. e. Højreklik under Personlig og vælg opgaven Importer. Følgende keystoret VOCES_valid.p12 skal importeres. Kodeordet er Test1234. f. Efter import skal OCES CA certifikatet flyttes ned i folderen Udgivere, der er tillid til. g. Herefter skal certifikatet Projektmiljø-adgangsstyring-T (funktionscertifikat).cer, der ligger i samme folder, importeres direkte under Udgivere, der er tillid til h. Det importerede keystore skal have ændret dets rettigheder, så Network Services kan tilgå nøglen. Dette gøres ved at højreklikke på certifikatet og vælge Administrer private nøgler. Her skal Network Services som minimum have læseadgang. 8. Når alt er på plads, genstartes IIS via IIS Manager programmet, og websitet kan tilgås via en webbrowser på denne URL 11

12 9. Herefter klikkes på Go to My Page, og man bliver bedt om at vælge Identity Provider 10. I skærmbilledet vælges IDP upstream for WebsiteDemo og klik på OK. Herefter bliver man bedt om at indtaste brugernavn og kodeord 12

13 11. Til test-formål kan man anvende brugernavnet admin og kodeordet VCfnYepizF3xTfziW2hbRwBdPhedDtXA 12. Herefter vil man være logget på applikationen, og vil se følgende skærmbillede Håndtering af kompileringsfejl på login tidspunkt Alt efter version af IIS og.net, kan man opleve at der opstår en kompileringsfejl af aspx siderne når man forsøger at tilgå dem første gang. Dette kan fixes ved at lave en mindre ændring i web.config filen i projektet. <add type="dk.nita.saml20.specification.defaultcertificatespecification, dk.nita.saml20, Version= , Culture=neutral" /> 13

14 I ovenstående linje er der angivet en Version og Culture attribut. Disse kan slettes, hvorefter fejlen forsvinder. Håndtering af signaturvalideringsfejl De test-certifikater der anvendes er udstedt i NETs test-miljø, hvor valideringstjenesterne til validering af certifikat gyldighed er bag en firewall der er lukket ned til udvalgte IP adresser. Hvis man ikke har adgang til NETs testmiljø, vil man sandsynligvis opleve signaturvalideringsfejl. Dette kan afhjælpes ved at lave følgende ændring i web.config filen Denne linje (samme som ovenfor), ændres fra Til denne <add type="dk.nita.saml20.specification.defaultcertificatespecification, dk.nita.saml20, Version= , Culture=neutral" /> <add type="dk.nita.saml20.specification. SelfIssuedCertificateSpecification, dk.nita.saml20, Version= , Culture=neutral" /> Validering af egen integration med Context Handleren Når man har udført en udveksling af metadata via Administrationsmodulet, kan man via eget Brugervendt system foretage et login på samme måde som vist ovenfor. Det anbefales at man får opsat sin egen Identity Provider, så man kan oprette og vedligeholde egne brugere, da den indbyggede Demo Identity Provider kun giver meget begrænset mulighed for at foretage login med brugere. 14

15 Teknisk beskrivelse af stubben til genudstedelse af tokens Stubben gør det muligt for leverandører at præfabrikere tokens i deres testcases, og så anvende stubben til at veksle tokenet til et nyt token (som ikke er udløbet), når testcasene afvikles. Koden til stubben er indeholdt i den ovennævnte ZIP fil, og man kan afvikle den lokalt. Stubben er også deployet i projektmiljøet, hvor den kan tilgås på følgende URL Forudsætninger for anvendelse af stubbe Det kræver ingen specielle forudsætninger at anvende stubben til token-veksling, og den anvendes blot som dokumenteret i ZIP-filen. ZIP-filen indeholder også eksempel kode på, hvordan man kan kalde stubben, som der kan tages udgangspunkt i. Kort beskrevet laver man et HTTP POST kald mod ovenstående endpoint, hvor det gamle token først base64 encodes, og dernæst URL-encodes, og sendes i kroppen. Nedenstående skærmbillede viser et eksempel på hvordan dette kan gøres (skærmbilledet er taget fra en REST klient til testformål, men det er ikke noget krav at man anvender en REST klient). 15

16 Vær opmærksom på, at token i kroppen skal være encodet på den korrekte måde, ellers fejler kaldet mod stubben, dvs hvis man har et token i klartekst, skal body udfyldes med følgende værdi (det foranstillede = tegn er nødvendigt) =URLEncode(Base64Encode(token)) Hvis man ønsker at teste mod stubben via et test-værktøj, kan man evt. vælge at anvende et af de tokens, der findes i ZIP filen til testformål. I filen Kombit.Samples.CHTestSigningService.Tests/Constants.cs Findes der en række præfabrikerede tokens, der allerede er base64 encodet. Disse tokens accepteres af stubben, og kan anvendes i kald dertil. Svaret fra stubben er en base64 enkodet XML struktur, som indeholder et SAML response som det ser ud, når det kommer frisk fra Context Handleren. 16

17 Appendiks A: Tips og tricks 1. Start med at få eksempel projektet på en integration med Context Handleren op at køre, så har man altid en reference-installation man kan sammenligne ens egen integration med, fx ved at kigge på request/responses mellem ens eget system og Context Handleren, og de tilsvarende request/responses i eksempel projektet. 2. Da integrationen til Context Handleren minder meget om integrationen til NemLog-in, vil man muligvis kunne finde hjælp og inspiration i sin egen organisation, hvis man der har erfaring med integration til NemLog-in. 3. Husk at anvende et FOCES certifikat fra DanID test-miljøet. Dette er noget, som ens lokale certifikat-administrator (tidligere kaldt en LRA hos DanID) kan hjælpe med at skaffe. 4. Context Handleren understøtter ikke SHA-1 algoritmen i forbindelse med signaturer, dvs at login requests der kommer fra det Brugervendte system (såkaldte AuthNRequests) skal være signeret med RSA-SHA256. Hvis man oplever at Context Handleren afviser login requests, bør man starte med at verificerer at man anvender den korrekte signatur algoritme. 17

18 Appendiks B: Specielt for projektmiljøet Projektmiljøet er et miljø, der anvendes i forbindelse med udviklingen af Støttesystemerne, og kan, indtil det eksterne test-miljø er tilgængeligt, bruges af tidlige anvendere af Støttesystemerne. Da ikke alle Støttesystemer er fuldt tilgængelige i projektmiljøet, er der en række procedurer der håndteres anderledes end i det eksterne testmiljø. Disse alternative procedurer er beskrevet nedenfor. Oprettelse af Brugervendt System Til projektmiljøet er der udarbejdet en bestillings-blanket i Excel, til at oprette et Brugervendt System. Her skal man udfylde stamdata oplysninger om sit Brugervendte System, dvs navn, SAML metadata, krævet AssuranceLevel samt hvilke Brugersystemroller og Dataafgrænsninger som systemet understøtter. Blanketten afleveret til KOMBIT, der bestiller en oprettelse af det Brugervendte System i Administrationsmodulet på baggrund af disse data. Test-brugere Den Identity Provider der findes i projektmiljøet, og som repræsenterer en kommunal Identity Provider, indeholder et begrænset antal test-brugere, og disse brugere vil ikke have tildelt nogen af de Brugersystemroller som er bestilt til det Brugervendte System. De kan derfor kun anvendes til en huligennem test. Leverandøren af det Brugervendte System bør derfor enten etablere en aftale med en kommune om at anvende deres Identity Provider i test-miljøet, eller etablere sin egen. Der er udarbejdet en bestillingsblanket i Excel til oprettelse af en Identity Provider i projektmiljøet, som kan udfyldes på lige fod med bestillingen af det Brugervendte System. Leverandøren skal så selv opsætte selve Identity Provider komponenten. 18