Installations- og konfigurationsvejledning

Transkript

1 Installations- og konfigurationsvejledning AD FS plugin til KOMBIT integration Version: Date: Author: BSG

2 Indholdsfortegnelse 1 Introduktion Målgruppe Tekniske krav Opsætning af AD FS Anvendelse af FOCES certifikat Bestilling af FOCES certifikat Registrering af FOCES certifikat i AD FS Krav til metadata Installation og konfiguration af plugin Installation af plugin på Windows Serveren Registrering af plugin i AD FS Test af korrekt installeret plugin Opretteles af KOMBITs Context Handler som Relying Party Konfiguration af plugin Konfiguration af audit log Validering af opsætning Tips og tricks Registrering af AD FS hos KOMBIT Support Versionshistorik Udgave sendt til review hos Vallensbæk Kommune Første release af dokumentet til alle kommuner Opdateret med en rettelse til anvendelsen af Scrubber scriptet, og tilføjelse af metadata URL til produktion Opdateret med link til midlertidig demo system samt adresse på support Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 2 / 19

3 1 Introduktion Nærværende dokument indeholder en fuld installations- og konfigurationsvejledning for det AD FS plugin der er udviklet til integrationen med KOMBITs støttesystem, Adgangsstyring for brugere, også kaldet Context Handleren. Dokumentationen er et følgedokument til hhv. plugin, konfigurationsfil samt diverse installationsscripts der følger med leverancen. 1.1 Målgruppe Dokumentet er teknisk af karakter, og er skrevet med drift- og it-medarbejdere som målgruppe. 1.2 Tekniske krav Leverancen er udviklet og testet mod Windows Server 2012R2 med Microsoft AD FS 3.0 installeret. Denne platform er nødvendig for at tage det leverede plugin i anvendelse. Leverancen indeholder et færdig-bygget plugin, og det er ikke nødvendigt at anvende kildekoden for at tage det leverede plugin i anvendelse. Kildekoden er udviklet i C#, og leveres med projektfiler m.m. til Visual Studio 2015, og bygger ovenpå Microsofts WIF rammeværk. Følgende udviklingsværktøjer er nødvendige for at anvende den leverede kildekode - Visual Studio WIF Runtime ( - WIF SDK 3.5 ( 2 Opsætning af AD FS I forbindelse med installationen af AD FS er der nogle tekniske krav fra KOMBITs side, som skal overholdes. Disse er uafhængige af selve plugin komponenten, men nævnes her for fuldstændighedens skyld. 2.1 Anvendelse af FOCES certifikat KOMBIT kræver at det certifikat der anvendes af AD FS en er et FOCES certifikat (Funktionscertifikat fra Nets/DanID). Hvis man integrerer mod KOMBITs testmiljø, er det ydermere et krav at dette FOCES certifikat kommer fra Nets/DanIDs testmiljø (i produktion anvendes der produktions-certifikater). FOCES produktionscertifikater kan bestilles hos DanID på samme måde som medarbejder certifikater og andre OCES certifikater, men test FOCES certifikater kræver at man har en adgang til DanIDs testmiljø. Hvis man ikke har en sådan adgang kan den bestilles hos DanID Bestilling af FOCES certifikat Nedenfor er vist det flow man skal igennem for at bestille et FOCES certifikat i produktion hos DanID. Flowet er identisk i test-miljøet, det er dog test-miljøets selvbetjeningsløsning man Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 3 / 19

4 skal logge på (kræver at man først har bestilt adgang til test-miljøet, og har fået DanID til at åbne i deres firewall). 1. Tilgå selvbetjeningsløsningen på dette websted. For at logge på skal man have en medarbejdersignatur der er registreret hos DanID som en certifikatadministrator. Den eller de personer i kommunen der kan bestille medarbejdersignaturer vil have denne adgang tjening 2. Klik på Øvrige signaturer efter at være logget på, og klik på menupunktet Bestil funktionssignatur. 3. Bestillingsblanketten udfyldes efterfølgende. Det er ikke så vigtigt hvad man indtaster i disse felter, så vælg et navn der er sigende for anvendelsen, fx AD FS. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 4 / 19

5 4. Efterfølgende skal man underskrive bestillingen med sin medarbejdersignatur, hvorefter man vil få vist en installationskode. Denne kode skal skrives ned, da den skal bruges senere. 5. Når DanID har behandlet bestillingen, bliver der sendt en med et oprettelseslink til certifikatadministratoren. Når man klikker på dette link startes en Java Applet, hvor man skal indtaste installationskoden, samt angive hvilken filtype som certifikatet skal gemmes som. Her vælges PKCS#12. Resultat vil være en fil med endelsen.p12 eller.pfx, som skal installeres på Windows Serveren. Dette gøres ved at dobbelt-klikke på filen (når den ligger på Windows Serveren), og vælge at certifikatet skal installeres på Local Machine (efterfølgende spørgsmål om kodeord udfyldes, og der trykkes ok/næste på alle efterfølgende spørgsmål). Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 5 / 19

6 2.1.2 Registrering af FOCES certifikat i AD FS Når certifikatet er installeret på Windows Serveren, skal AD FS konfigureres til at anvende dette certifikat. I AD FS gøres dette i følgende skærmbillede Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 6 / 19

7 1. Klik på Add Token-Signing Certificate og vælg det nyligt installerede FOCES certifikat 2. Klik på Add Token-Decrypting Certificate og vælg det nyligt installerede FOCES certifikat 3. I listen af registrerede certifikater (i midten af skærmbilledet ovenfor) markeres det installerede FOCES certifikat under Token-signing, og der klikkes på Set as Primary 4. I listen af registrerede certifikater (samme sted) markeres det installerede FOCES certifikat under Token-decrypting, og der klikkes på Set as Primary 5. Efterfølgende kan man vælge at slette de gamle certifikater under Token-Signing og Token-decrypting. Certifikatet under Service Communication er SSL certifikatet, og det skal ikke ændres. Obs! Man bør være opmærksom på, at hvis man har eksisterende integrationer til sin AD FS (andre tjenesteudbydere, fx Miljøportalen), så vil disse skulle have gen-registreret kommunens AD FS, da man nu har ændret certifikatopsætningen. Hvordan man gennemfører denne genregistrering afhænger af den enkelte tjenesteudbyder, og vil fremgå af de vejledninger der findes til disse tjenestudbydere. Hvis man ikke gør dette, vil kommunens medarbejdere ikke længere kunne logge på disse løsninger. Man kan også overveje at installere en selvstændig AD FS installation til KOMBIT, hvis dette resulterer i større udfordringer. 2.2 Krav til metadata KOMBIT stiller nogle krav til indholdet af de SAML metadata der skal registreres i støttesystemet Administrationsmodulet. KOMBIT baserer disse krav på NemLog-in føderations krav, og da AD FS ikke genererer metadata der overholder disse krav, er det nødvendigt at tilpasse metadata inden de registreres hos KOMBIT. Til dette formål er der leveret et Powershell script, der kan rense AD FS metadata for de felter og attributter som KOMBIT vil afvise. Denne rensning af metadata har ingen betydning for selve AD FS installationen, og er kun relevant for selve registreringen af metadata hos KOMBIT. AD FS metadata kan downloades fra den installerede AD FS server ved et link magen til nedenstående (selve domænenavnet skal tilpasses, så det matcher det domæne hvor AD FS er installeret, dvs den del der hedder adfs.kommune.dk skal matche den lokale installation) Hvis AD FS er korrekt installeret, vil man kunne downloade en XML fil fra denne adresse. Filen fylder ca 50 KB og indeholder det fulde sæt af metadata for AD FS installationen. Disse metadata skal renses inden de registreres hos KOMBIT. Dette gøres vha. det leverede script (scrubber.ps1) på følgende måde Powershell.exe ExecutionPolicy Unrestricted -File C:\scrubber.ps1 -in C:\FederationMetadata.xml -out C:\adfs.xml Placeringen af script, metadata filer m.m. tilpasses så det stemmer med de faktiske placeringer af filerne. Efter scriptet er afviklet, vil de rensede metadata være i filen adfs.xml, og det er denne metadata fil der skal registreres hos KOMBIT. De rensede metadata vil være ca 7-8 kb i størrelse. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 7 / 19

8 I praksis betyder det at man ikke laver noget om i sin egen AD FS installation, men alene ændrer i en kopi af metadata inden disse registreres hos KOMBIT. 3 Installation og konfiguration af plugin 3.1 Installation af plugin på Windows Serveren Leverancen består af to filer, CustomAttributeStore.dll (selve plugin filen) samt config.xml (konfigurationsfilen). Disse to filer skal installeres på Windows Serveren hvor AD FS er installeret. DLL filen skal kopieres til C:\Windows\ADFS og konfigurationsfilen skal kopieres til C:\ADFS. 3.2 Registrering af plugin i AD FS I AD FS skal man registrere det leverede plugin som et Attribute Store. Dette sker ved at åbne folderen Trust Relationships i AD FS, og vælge Attribute Store. Ved at højreklikke her, kan man i menuen vælge Add Attribute Store. Dette åbner et dialog vindue, der skal udfyldes med følgende værdi CustomAttributeStore.MainClass, Custom Attribute Store Hvilket vil resultere i følgende skærmbillede Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 8 / 19

9 Herefter er plugin registreret i AD FS, og kan anvendes som beskrevet nedenfor. OBS! Det kan være nødvendigt at genstarte AD FS servicen før denne registrering slår igennem Test af korrekt installeret plugin Når ovenstående registrering af gennemført, kan man validere at plugin er korrekt registreret (og at den konfigurationsfil der ligger i C:\ADFS folderen indeholder lovlige værdier). Ved at genstarte AD FS servicen, vil plugin blive initialiseret, og den vil forsøge at indlæse konfigurationsfilen. Hvis dette lykkes, bliver følgende logget i Eventloggen på maskinen. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 9 / 19

10 Hvis der derimod er fejl under indlæsningen af plugin eller konfigurationsfilen, vil der fremgå en advarsel i ovenstående log, med en beskrivelse af fejlen. 3.3 Opretteles af KOMBITs Context Handler som Relying Party Context Handleren skal registreres som et såkaldt Relying Party i AD FS, for at kommunens medarbejdere kan logge på KY, KSD og SAPA. Dette sker ved højreklikke på menuen Relying Party Trust i AD FS, og vælge Add Relying Party Trust. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 10 / 19

11 Herefter startes en opsætnings-guide, hvor man skal udvælge de metadata der udpeger Context Handleren. Disse metadata publiceres af KOMBIT, og er nødvendige for at gennemføre en installation. Hvis man gennemfører en integration med KOMBITs testmiljø, kan man hente Context Handlerens metadata fra dette websted. Når man skal gennemføre en integration til KOMBITs produktionsmiljø, skal man anvende metadata der kan hentes fra dette websted i stedet. Nedenstående skærmbillede viser hvordan man udpeger metadata filen fra Context Handleren i den nævnte opsætnings-guide. Her skal man anvende den fil man har downloadet fra ovenstående link, og importere (i skærmbilledet nedenfor er det filen metadata.xml) Når Context Handleren er registreret som en Relying Party i AD FS, skal der opsættes en række Claim Rules, der sikrer at de tokens der udstedes til Context Handleren overholder KOMBITs Attributprofil. Disse Claim Rules binder det leverede plugin sammen med den konfigurerede Relying Party. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 11 / 19

12 For at lette opsætningen af Claim Rules, er der leveret et installationsscript til dette formål. Dette installationsscript (rules.txt) placeres i folderen c:\adfs, og i Powershell udføres følgende kommando Set-AdfsRelyingPartyTrust -TargetName "NAME" -IssuanceTransformRulesFile "C:\ADFS\rules.txt" TargetName værdien skal erstattes med det navn some er angivet for Context Handleren da den blev oprettet som Relying Party. Efter import af Claim Rules, vil man kunne inspicere disse ved at højreklikke på den oprettede Relying Party i AD FS, og vælge Edit Claim Rules. Det skærmbillede der åbner sig skulle gerne ligne følgende 3.4 Konfiguration af plugin Som en del af leverancen medfølger et eksempel på en konfiguration af plugin. Denne fil hedder config.xml, og skal som nævnt installeres i folderen C:\ADFS. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 12 / 19

13 Dette afsnit beskriver konfigurationsfilen, og de muligheder der er for konfiguration. Det er vigtigt at denne fil tilpasses den aktuelle installation, da konfigurationsfilen blot er leveret med nogle eksempler på data, der næppe er anvendelige i en rigtig installation. Nedenfor vises et eksempel på konfigurationsfilen, og de enkelte værdiers funktion beskrives <ADFSConfiguration> <LocalDir>test.local</LocalDir> <CVR> </CVR> <AssuranceLevel>3</AssuranceLevel> <SpecVer>DK-SAML-2.0</SpecVer> <KombitSpecVer>1.0</KombitSpecVer> <Serial>objectGUID</Serial> <CommonName>displayName</CommonName> <SuperGroup>KOMBIT_ROLE</SuperGroup> <RoleTemplate> <DelegationConfiguration> <CVRGroupAttribute>extensionAttribute10</CVRGroupAttribute> <RoleNameGroupAttribute>extensionAttribute11</RoleNameGroupAttribute> </DelegationConfiguration> </ADFSConfiguration> Parameter LocalDir CVR SpecVer KombitSpecVer Serial CommonName SuperGroup RoleTemplate Beskrivelse Denne parameter skal indeholde adressen på Active Directoriet hvor AD FS skal lave opslag for at hente oplysninger om brugerens attributter og gruppemedlemskab Denne parameter skal indeholde kommunens CVR nummer. Alle de steder i de tokens AD FS en genererer, hvor der fremgår et CVR nummer, vil dette CVR nummer blive anvendt. Denne parameter skal have værdien DK-SAML-2.0, der peger på den version af OIOSAML profilen som anvendes. KOMBIT stiller krav om at DK- SAML-2.0 anvendes. Denne parameter skal have værdien 1.0, der peger på den version af KOMBITs Attributprofil som anvendes. KOMBIT stiller krav om at 1.0 anvendes. Denne parameter skal indeholde værdien på den bruger-attribut i Active Directory, der anvendes som unik nøgle for brugeren. KOMBIT stiller krav om at den unikke nøgle skal være på UUID v4 format, hvilket fx GUID værdierne i AD opfylder. Denne parameter skal indeholde værdien på den bruger-attribut i Active Directory, der anvendes som præsentationsnavn for brugeren. KOMBIT stiller ingen krav til indholdet af dette felt, men fagsystemerne formodes at ville anvende værdien til præsentation af brugerens navn i brugergrænsefladerne. Denne parameter skal indeholde navnet på en sikkerhedsgruppe i Active Directory. Når der laves opslag på en bruger i Active Directory, og der afgøres hvilke sikkerhedsgrupper en bruger er medlem af, så kigges der alene på de grupper der er medlem af (undergrupper af) denne gruppe. Formålet med denne parameter, er at reducere mængden af sikkerhedsgrupper som plugin et skal forholde sig til ved bruger-login, men også samtidig at give kommunen mulighed for at gruppere alle KOMBIT relevante sikkerhedsgrupper på en fornuftig måde. Denne parameter skal indeholde en URL streng på formen Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 13 / 19

14 Fx vil værdien for Vallensbæk kommune være Når AD FS udsteder et token til KOMBITs Context Handler, vil alle Jobfunktionsroller blive bygget ved at man tager sikkerhedsgruppens navn (fx MinJobfunktionsRolle) og sætter efter ovenstående værdi, og til sidst tilføjer et påkrævet versionsnummer. Resultatet vil være at Jobfunktionsrollen vil få ID et Da AD FS plugin et anvender sikkerhedsgruppens navn direkte, er det vigtigt at sikkerhedsgrupperne kun indeholder lovlige tegn i deres navn. DelegationConfiguration De lovlige tegn er bogstaverne A til Z, samt tallene 0 til 9 og specialtegnet _ (underscore). Denne parameter er optionel at udfylde, og skal efterlades blank i konfigurationsfilen hvis den ikke anvendes, dvs på følgende form <DelegationConfiguration> <CVRGroupAttribute></CVRGroupAttribute> <RoleNameGroupAttribute></RoleNameGroupAttribute> </DelegationConfiguration> Parameteren anvendes hvis man ønsker at anvende en anden kommunes Jobfunktionsrolle(r). Det antages at den anden kommune har givet tilladelse til dette via KOMBITs Administrationsmodul (ellers vil konfigurationen ikke have nogen effekt). Når man ønsker at anvende en Jobfunktionsrolle uddelegeret fra en anden kommune, skal man oprette en AD sikkerhedsgruppe på lige fod med ens egne Jobfunktionsroller, men der skal udfyldes 2 yderligere attributter på AD sikkerhedsgruppen, der angiver hhv. CVR nummer på den kommune der ejer Jobfunktionsrollen, samt det ID som Jobfunktionsrollen har i Administrationsmodulet. Hvis man fx vælger at anvende ExtensionAttribute10 og ExtensionAttribute11 til disse formål, så angiver man disse værdier i konfigurationsfilen, og så vil plugin et aflæse disse attributter på AD sikkerhedsgruppen, og hvis de er udfyldt, så vil de værdier anvendes i stedet for de konfigurerede <CVR> og <RoleTemplate> værdier beskrevet ovenfor. 3.5 Konfiguration af audit log En standard installation af AD FS vil ikke auditlogge specielt meget, men det er muligt at konfigurere AD FS til at auditlogge såvel sikkerhedshændelser (bruger login gennemført, bruger login afvist) samt indholdet af de udstedte tokens. Denne konfiguration af uafhængig af selve plugin installationen, og er en generel konfigurationsmulighed i AD FS 3.0. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 14 / 19

15 1. Højreklik på rod-menupunktet i AD FS og vælg Edit Federation Service Properties 2. Under fanen Events sæt flueben i samtlige muligheder 3. Kør følgende Powershell kommando AUDITPOL /SET /SUBCATEGORY:"Application Generated" /FAILURE:ENABLE /SUCCESS:ENABLE 4. Åben Edit Group Policies på Windows Serveren 5. Gå til Computer Configuration > Windows Settings > Security Settings > Local Policies > Audit Policy og vælg Audit object access Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 15 / 19

16 6. Åben værdien, og sæt flueben i begge muligheder Herefter vil AD FS auditlogge de nævnte sikkerhedshændelser og udstedte tokens. 3.6 Validering af opsætning KOMBIT leverer snarest et demo system til at teste at AD FS konfiguration er udført korrekt. Indtil da, kan man anvende følgende website til at afprøve et login. Ved at tilgå ovenstående URL i sin web-browser, får man mulighed for at foretage et login ind mod KOMBITs Context testmiljø, hvilket ved korrekt opsætning af AD FS, betyder at man kan gennemføre et fuldt login. Nedenfor er vist det forløb man bør forvente at gennemføre hvis alt er sat korrekt op. Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 16 / 19

17 1. Klik på Login via Adgangsstyring for Brugere 2. Vælg egen kommune i dropdown listen (hvis kommunen ikke optræder, så er AD FS installation ikke korrekt opsat hos KOMBIT) 3. Gennemfør et login i AD FS. Hvis AD FS er sat op til Windows Integrated Authentication, vil man ikke blive bedt om at indtaste brugernavn/kodeord, men vil i stedet blive automatisk logget på 4. Ved succesfuldt login, vil man se nedenstående resultat side Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 17 / 19

18 3.7 Tips og tricks Hvis man integrerer med KOMBITs testmiljø skal man anvende test certifikater fra DanID. Spærrelisterne for disse certifikater er gemt bag en firewall opsat af Nets, som det er lidt besværligt at få adgang gennem (man kan anmode Nets om at åbne op i deres firewall for udvalgte IP adresser). Her kan det være nemmere at slå spærreliste-check fra på AD FS serveren for udvalgte Relying Parties. Følgende kommando i powershell slår spærrecheck fra for den Relying Party der hedder KOMBIT TEST. Navnet skal tilpasses så den passer med den Relying Party hvor man ønsker at slå spærrecheck fra. Get-AdfsRelyingPartyTrust -Name "KOMBIT TEST" Set-AdfsRelyingPartyTrust - EncryptionCertificateRevocationCheck None -SigningCertificateRevocationCheck None OBS! Man skal kun gøre dette i forbindelse med integration til testmiljøet, og det er vigtigt at man ikke slår spærrecheck fra i en produktions-installation. 4 Registrering af AD FS hos KOMBIT Efter AD FS er installeret skal den registreres hos KOMBIT, så den kan anvendes som login mekanisme for kommunens medarbejdere. Denne registrering foregår i støttesystemet Administrationsmodulet, hvor følgende trin skal gennemføres 1. AD FS skal registreres som et IT-System i Administrationsmodulet. Dette gøres ved at udfylde en web-blanket med følgende oplysninger a. Navn og beskrivelse på AD FS installationen b. Upload af metadata fil (den rensede udgave beskrevet i tidligere afsnit) c. Oplysninger om hvorvidt installationen må tilgås fra en mobil enhed (smartphone og/eller tablet) d. Oplysninger om evt IP-filtrering i forbindelse med tilgangen til AD FS. Denne indtastning er ikke obligatorisk, og anvendes alene til at øge brugervenligheden i forbindelse med login (hvis en medarbejder forsøger login til KY, KSD eller SAPA Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 18 / 19

19 fra en af de nævnte IP adresser, vil man automatisk få valgt denne AD FS ved login, ellers skal man vælge fra en dropdown liste). 2. Herefter skal der anmodes om en Føderationsaftale mellem leverandøren af AD FS installationen og kommunen. I dette tilfælde er kommunen både leverandør og kommune, så anmodningen og godkendelsen af anmodningen har en ren formel karakter. Denne anmodning sker ved at udfylde en web-blanket med følgende oplysninger a. Hvilken AD FS installation anmodningen omfatter (vælges fra dropdown liste her vælges den AD FS der er registreret i trin 1) b. Hvilken kommune anmodningen skal sendes til (her vælges egen kommune) 3. Herefter skal anmodningen fra trin 2 godkendes. Dette sker også i Administrationsmodulet, hvor man vil modtage et advis om anmodningen. Denne anmodning åbnes og accepteres, hvorefter AD FS en er registreret hos KOMBIT og kan anvendes af kommunen OBS! Hvis man er pilot-kommune vil man opleve at brugergrænsefladen til Administrationsmodulet ikke er tilgængeligt, og at de ovennævnte web-blanketter er erstattet med word-blanketter. Disse word-blanketter bliver udleveret af KOMBIT, og skal sendes til KOMBIT når de er udfyldt, der efterfølgende står for selve registreringen. 5 Support Den storkøbenhavnske digitaliseringsforening har adgang til support hos Digital Identity i perioden Support-postkassen hedder adfs-support@digitalidentity.dk Digital Identity ApS, Klamsagervej 35, 8230 Åbyhøj 19 / 19