•  

I forbindelse med udruldningen af KOMBITs støttesystemer, skal kommunerne (jvf KIGO 0500.0100.0050) tilslutte deres egen Identity Provider til støttesystemerne. Denne Identity Provider er ansvarlig for at logge kommunens egne brugere på de fælleskommunale it-systemer, og i den forbindelse stiller KOMBIT krav om at den tilsluttede Identity Provider skal overholde KOMBITs Attributprofil.

KOMBITs Attributprofil er beskrevet i detaljer i Appendix A af Bilag 2A, der kan hentes på KOMBITs Sharepoint side, og de vigtigste detaljer er beskrevet ved eksempel i denne artikel.

Formål og afgrænsninger

Det kan være svært at overskue omfanget af den konfiguration, og de udvidelser, der skal til for at få en Identity Provider til at overholde KOMBITs attributprofil. Denne artikel beskriver ved eksempel, hvordan dette gøres på en Microsoft Active Directory Federation Services (AD FS) Identity Provider komponent. Hvis ens kommune anvender AD FS, kan man anvende eksemplerne og koden i denne artikel direkte, men selv hvis man anvender en anden Identity Provider, kan man bruge denne artikel til at skabe sig et overblik over omfanget af arbejdsopgaven.

Microsoft AD FS er anvendt som eksempel, da produktet er tilgængelig som en standard service når man har installeret en Windows Server, og det formodes at være interessant for mange kommuner at anvende AD FS, da det ikke kræver nogen yderligere investering i software.

Da AD FS ikke opfylder KOMBITs Attributprofil uden tilpasninger, er formålet med denne artikel at beskrive den nødvendige opsætning af AD FS, samt at gøre et plugin tilgængelig, der gør det muligt for AD FS at udstede tokens med Jobfunktionsroller som krævet af KOMBIT Attributprofilen.

Kildekode til dette plugin er gjort frit tilgængelig.

KOMBITs støttesystemer understøtter muligheden for at delegere rettigheder (Jobfunktionsroller) på tværs af myndigheder, samt mulighed for at lave en dynamisk styring af de dataafgrænsninger der er koblet til en rettighed. Det plugin der anvendes i denne artikel understøtter uddelegering af rettigheder, men dynamisk styring af dataafgrænsninger vil kræve en udvidelse af pluginet.

Den Storkøbenhavnske Digitaliseringsforening (DSD)

I forlængelse af denne artikel har DSD hyret Digital Identity til at produktmodne og publisere en udgave af pluginet til AD FS, så den er frit tilgængelig for alle der ønsker at gøre brug af den. Kildekode, dokumentation m.m. kan hentes fra denne adresse

https://digitaliser.dk/group/3094254

Denne artikel, og den kode man kan hente her, er ikke opdateret i forhold til den udgave der er publiseret i DSD regi, og det anbefales at man tager udgangspunkt i DSD udgaven i stedet for denne artikel. Artiklens indhold kan dog stadig være relevant baggrundsviden i forhold til hvordan AD FS udvides.

Målgruppe

Den primære målgruppe for artiklen er tekniske kyndige personer, der har erfaring med opsætning og konfiguration af hhv Windows Server og AD FS. Artiklen dækker ikke installation af selve AD FS komponenten, og det formodes at læseren har en kørende AD FS installation, som de ønsker at koble til KOMBITs støttesystemer.

Forudsætninger

Installation af plugin i AD FS

  • En kørende Windows Server 2012 (eller tilsvarende)
  • Et Active Directory, der indeholder de brugere der skal tilgå de fælleskommunale it-systemer
  • En kørende AD FS installation

Udviklingsmiljø (ikke påkrævet)

Kildekoden til AD FS pluginet er tilgængelig, og den enkelte kommune kan tilpasse koden efter eget behov. Hvis dette er nødvendigt kræver det følgende (gratis) software

KOMBITs Attributprofil

De fulde detaljer for KOMBITs Attributprofil kan læses i KOMBITs dokumentation af samme, men for overblikkets skyld vises her et eksempel på et Assertion element (token) som en Identity Provider skal kunne udstede. Et token kan indeholde flere oplysninger, men de nedenstående attributter er krævede for at opfylde attributprofilen.

Attributprofilen stiller en række krav til formatet af enkelte elementer, samt hvilke attributter der SKAL udstedes. De relevante afsnit er fremhævet ovenfor, og beskrevet nedenunder

  • 2: Subject elementet skal opfylde et bestemt format, hvor specielt "Serial" feltet i NameID elementet bør fremhæves, da dette skal indeholde en unik identifikation af medarbejderen.
  • 9: KombitSpecVer attributten skal angive hvilken version af attributprofilen man overholder - her kan hardkodes værdien 1.0
  • 12: CvrNumberIdentifier attributten skal indeholde kommunens CVR nummer.
  • 15: AssuranceLevel skal indeholde en værdi der angiver det sikkerhedsniveau hvor med medarbejdernes identitet håndteres.
  • 18: SpecVer skal angive hvilken version af OIOSAML profilen man opfylder. Attributprofilen er baseret på DK-SAML-2.0, hvilket angives her.
  • 21: Privileges_intermediate indeholder en base64 enkodet XML struktur, der angiver hvilke Jobfunktionsroller som medarbejderen er tildelt.
Værdierne i 9, 12, 15 og 18 kan klares ved korrekt konfiguration af AD FS, men NameID formatet i 2 og Jobfunktionsrollerne i 21 kræver et plugin til AD FS.

Konfiguration af AD FS

AD FS kan konfigureres til at udstede attributter (kaldet Claims i AD FS), hvilket gøres via AD FS Claim Rules Language.

Efter gennemgang af dette afsnit vil Claims 1-6 være oprettet i AD FS, og alt pånær NameID formatet og Jobfunktionsroller (Claims 7-10) være opfyldt i forhold til attributprofilen.

Konfiguration af attributter med statiske værdier

Konfigurationen af disse elementer er ens, og nedenfor vises i detaljer hvordan man opsætter et enkelt claim.

Målet er at få AD FS til at udstede følgende attribut.

Claims konfigureres per Relying Party (modtager af tokens). I forbindelse med tilslutning af AD FS til KOMBITs støttesystemer, skal man oprette KOMBITs Context Handler som en Relying Party i AD FS. Dette gøres på samme måde som man opretter enhver anden Relying Party i AD FS, og er derfor ikke beskrevet i denne artikel.

For at tilføje AssuranceLevel som en attribut til KOMBITs Context Handler skal der oprettes 2 claim regler på følgende måde

  1. højre-klik på <Context Handler> under Relying Parties og vælg Edit Claim Rules menupunktet.
  2. Vælg herefter Send Claims Using a Custom Rule i dropdown menuen som vist nedenfor.

Giv den første regel navnet addAssuranceLevelClaim" og udfyld Custom rule feltet med følgende

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
   Issuer == "AD AUTHORITY"] => add(store = "Active Directory",
                                    types = ("http://di.dk/Version"),
                                    query = ";userPrincipalName;{0}",
                                    param = c.Value);

Hvilket gerne skulle se sådan her ud

Opret en regel mere på samme måde, og giv denne regel navnet modifyAssuranceLevelClaim som udfyldes med følgende (OBS! linie 4 angiver den tildelte AssuranceLevel værdi)

Hvilket gerne skulle se sådan her ud

Ovenstående 2 regler sikrer at der udstedes en AssuranceLevel attribut i tokenet med værdien 3

Gentag for SpecVer og KombitSpecVer

Ovenstående gentages for de 2 andre attributter med statiske værdier. Nedenstående regler kan anvendes til formålet.

SpecVer elementet skal indeholde værdien "DK-SAML-2.0", så attributten kommer til at se sådan her ud

Igen skal der oprettes en add og en modify regel, som har følgende regel værdier

addSpecVer

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
   Issuer == "AD AUTHORITY"] => add(store = "Active Directory",
                                    types = ("http://di.dk/SpecVer"),
                                    query = ";userPrincipalName;{0}",
                                    param = c.Value);

modifySpecVer

KombitSpecVer elementet skal indeholde værdien "1.0", så attributten kommer til at se sådan her ud

Igen skal der oprettes en add og en modify regel, som har følgende regel værdier

addKombitSpecVer

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
   Issuer == "AD AUTHORITY"] => add(store = "Active Directory",
                                    types = ("http://di.dk/KombitSpecVer"),
                                    query = ";userPrincipalName;{0}",
                                    param = c.Value);

modifyKombitSpecVer

Installation af plugin i AD FS

Dette afsnit beskriver hvordan man installerer og konfigurerer pluginet i AD FS, så de sidste claims regler kan konfigureres.

Pluginet består af en enkelt fil ved navn Custom Attribute Store.dll, der enten kan downloades fra denne side, eller bygges fra den kildekode der også er tilgængelig for download.

  1. Kopier plugin filen til AD FS installations folderen (fx C:\Windows\ADFS).
  2. Åben AD FS Management værktøjet og vælg ADFS > Trust Relationships > Add Custom Attribute Store.
  3. Giv AttributStored et navn (fx CustomAttributeStore) og indsæt CustomAttributeStore.MainClass, Custom Attribute Store i feltet Class Name.

Test korrekt installation

Åben Event Viewer > Applications and vælg Services Logs > AD FS > Admin og verificér der ikke er nogen fejl. Der bør være en Information med teskten "Attribute store 'CustomAttributeStore' is loaded successfully.".

OBS! Hvis det ikke er muligt at kopiere DLL'en til AD FS installations-folderen, så kan det være nødvendigt at slukke for AD FS servicen mens filen kopieres.

Konfiguration af NameID format

Attributprofilen kræver at brugerens identitet enkodes i et bestemt format (urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName), og nedenfor er beskrevet hvordan man får AD FS til at overholde dette format, og hvordan man mapper de relevante værdier for brugeren ind i dette format. Denne konfiguration anvender ovenstående plugin.

Claims i AD FS

Som ved attributterne med statiske værdier, skal der oprettes 2 claim regler. Dette gøres med følgende værdier, hvor linie 2 angiver at det er CustomAttributeStore der skal skaffe værdien, og linie 2 angiver den operation (subject) på CustomAttributeStore der skal afvikles. "subject" operationen sørger for at danne et korrekt formateret NameID element.

addNameID

modifyNameID

Konfiguration af Privileges_intermediate attributten til Jobfunktionsroller

Pluginet mapper en brugers gruppe-medlemskab i AD til Jobfunktionsroller. For ikke at alle grupper i AD bliver mappet til Jobfunktionsroller, er det kun Grupper der er indeholdt i gruppen Role der medtages når pluginet danner listen af Jobfunktionsroller. Navnet på den overordnede gruppe kan tilpasses ved at ændre i kildekoden til pluginet.

Nedenfor er vist et eksempel på en gruppe i AD ved navn Raadgiver, der er indeholdt i gruppen Role, og dermed bliver mappet til Jobfunktionsroller af pluginet.

Hver gruppe der opfylder ovenstående krav, som brugeren er medlem af, mappes til Jobfunktionsroller ved at aflæse 2 attributter fra gruppen

  • privilege: en komma-separeret liste af Jobfunktionsroller. Disse skal være på URI format, og indeholde kommunens navn, fx
    • urn:dk:herning:roller:socialforvaltningen:raadgiver
    • urn:dk:herning:roller:socialforvaltningen:sagsbehandler
  • cvr: Det CVR nummer som jobfunktionsrollerne er tilknyttet (typisk kommunens eget CVR nummer)

Eksempler på en rolle med disse attributter er vist nedenfor

Claims i AD FS

For at få AD FS til at udstede en Privileges_intermediate attribut, indeholdende de Jobfunktionsroller som en bruger er blevet tildelt på ovenstående måde, skal følgende claim regler opsættes i AD FS.

Igen angiver linie 2 at det er CustomAttributeStore der skal anvendes, og det er operationen base64 angivet i linie 4, der kaldes for at hente en base64 enkodet BasicPrivilegeList streng, der kan sættes ind i attributten.

addPrivileges

modifyPrivileges

Opsætningen fuldført

Med ovenstående på plads, er opsætningen af AD FS fuldført, og de tokens der udstedes af AD FS følger nu KOMBITs Attributprofil.

Tilpasning af plugin koden

Koden der kan hentes består af et Visual Studio projekt, der kan åbnes med Visual Studio 2013 eller nyere. Projektet indeholder følgende filer, hvor CustomAttributeStore.cs er den primære klasse

Plugin koden har 2 hardkodede værdier, der bør ændres inden pluginet tages i brug.

  • localDir: adressen på det Active Directory der indeholder kommunens brugere.
  • municipalityCVR: cvr nummeret på kommunen. Denne værdi anvendes til at sætte det korrekte NameID.

Der er også taget en række design valg ud fra nogle antagelser, som man bør forholde sig til, da ens egen opsætning af Active Directory kan afvige på visse områder. Disse antagelser og design valg er beskrevet nedenfor.

  1. SAMAccountName indeholder medarbejderens unikke bruger-id.
  2. DisplayName indeholder medarbejderens fulde navn.
  3. Der eksisterer en gruppe ved navn "Role", som indeholder alle de grupper som skal mappes til Jobfunktionsroller.
  4. Alle grupper der repræsenterer Jobfunktionsroller har 2 udfyldte attributter ved navn "cvr" og "privileges".

SAMAccountName

SAMAccountName anvendes typisk som login navn, og i en typisk AD installation vil denne værdi kunne anvendes som unik id på medarbejderen. Hvis det ikke er tilfældet, skal en anden attribut fra AD anvendes i koden til pluginet. I nedenstående kode er linie 8 fremhævet, hvor man skal angive hvilken attribut der indeholder brugerens unikke id.

DisplayName

DisplayName indeholder typisk brugerens fulde navn, og anvendes fx af fagsystemerne til visning i brugergrænsefladen. Hvis man anvender en anden attribut i AD til at gemme brugerens fulde navn, så skal koden til pluginet ændres tilsvarende. Dette sker samme sted i koden som ved SAMAccountName, denne gang på linie 7, fremhævet nedenfor.

Gruppen "Role"

Jobfunktionsroller tildeles til den enkelte medarbejder som gruppemedlemskaber i AD, da det er den mest almindelig måde at håndtere rettighedsstyring i AD. For at pluginet nemt kan afgøre hvilke grupper der skal mappes til Jobfunktionsroller, antager pluginet at der eksisterer en over-gruppe ved navn "Role", som indeholder alle "Jobfunktionsrolle"-grupperne. Hvis man ønsker at denne gruppe skal have et andet navn, skal linie 5 i følgende kode i pluginet ændres

Jobfunktionsrolle attributter

For at danne et Privilege element (Jobfunktionsrolle) i det token som AD FS skal udstede, skal der bruges 2 værdier, et CVR nummer der angiver hvilken myndighed som Jobfunktionsrollen er knyttet til, og et navn på selve Jobfunktionsrollen. CVR nummeret vil typisk være kommunens eget CVR nummer, men i de tilfælde hvor man ønsker at anvende en Jobfunktionsrolle som en anden kommune har uddelegeret til en, skal dette felt indeholder CVR nummeret på den anden kommune.

Ovenstående information udtrækkes ved at aflæse 2 attributter på gruppen, navnligt "cvr" og "privileges". Dette vil typisk kræve at man tilføjer ekstra attributter til ens roller. Hvis man ikke ønsker dette, og i stedet vil anvende andre attributnavne (evt eksisterende attributter), så skal linie x og y i denne metode (fundet i Helper.cs) rettes.

Med ovenstående tilpasninger, kan pluginet tilpasses den opsætning af Active Directory som anvendes i ens egen kommune, og pluginet er klart til brug.

Download

Nedenfor er links til at downloade hhv pluginet, og kildekoden til pluginet.