KNF:ADFSx-IdP

Entree Federatie Handleiding ADFS 3.x voor aansluiting als identity provider (DOCUMENT IN BEWERKING)

Inleiding

In deze handleiding leest u hoe u uw organisatie middels ADFS aansluit op de Entree Federatie, waarna gebruikers van uw organisatie met hun Active Directory account kunnen inloggen op alle aangesloten diensten, zoals WikiWijs en Teleblik.

De procedure voor het aansluiten als IdP bestaat uit de volgende onderdelen:

1. Een ADFS serversysteem inrichten, bijv. Windows Server 2016
2. De ADFS server configureren voor aansluiting als Identity Provider voor de Entree Federatie (hoofdstuk 3)
3. Een ADFS proxy inrichten (hoofdstuk 4)
4. Attributen vrijgeven aan de Kennisnet Federatie (hoofdstuk 5)

Meer over ADFS

Een volledige beschrijving over AD FS is te vinden op: https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services

Waarom server en proxy?

Naast het inrichten van een ADFS server is het noodzakelijk om 'voor' de ADFS-server, buiten het Windows-domein, een ADFS-proxy in te richten die het verkeer van buitenaf doorstuurt naar de ADFS-server. Dit houdt in dat er 2 aparte Windows Server machines geconfigureerd worden in deze setup.

Dit heeft de volgende reden: de ADFS-server moet in het Windows-domein worden opgenomen en daarom liever niet direct bereikbaar zijn van buitenaf. Door een ADFS-proxy in te richten en deze voor de ADFS-server te plaatsen, buiten het Windows-domein, is de ADFS-server minder kwetsbaar voor aanvallen van buitenaf.

Bijkomend voordeel is dat een proxy kan worden geconfigureerd om een loginpagina met de look-and-feel van de instelling te tonen aan de gebruiker, in plaats van de standaard popup-prompt die de ADFS-server laat zien. Dit verbetert de herkenbaarheid van de login voor de eindgebruiker en biedt de mogelijkheid extra informatie aan de gebruiker te tonen. Daarnaast kan phishing beter worden voorkomen door het door het toepassen van een geldig SSL-servercertificaat.

Aanmelden bij Entree Federatie

Alvorens u begint met de installatie van ADFS moet u eerst uw instelling aan melden. Ga hiervoor naar https://www.kennisnet.nl/entree-federatie/aanmelden/aanmelden-voor-scholen/.

Als uw aanmelding geaccepteerd is ontvangt u hiervan een bericht. U kunt met onze servicedesk afstemmen of u eerst op onze staging omgeving wilt aansluiten of direct op productie.

ADFS server inrichten

Voordat u de specifieke instellingen voor de Entree Federatie kunt invoeren, moet u een basisinstallatie van ADFS uitvoeren. Dat gaat in de volgende stappen:

1. Windows Server installeren en configureren (paragraaf 2.1)
2. De ADFS software installeren (paragraaf 2.2)
3. Basisinstellingen van ADFS configureren (paragraaf 2.3)

Windows Server installeren en configureren

Om een ADFS server te kunnen inrichten, moet u eerst Windows Server installeren en configureren:

• Installeer de juiste versie van het besturingssysteem op de server: bij voorkeur Windows Server 2016 of Windows Server 2012 R2.
• Stel de tijd op de server correct in zorg dat deze wordt gesynchroniseerd met een time server.
• Neem de server op in het domein van de Active Directory waaruit de accounts voor de federatie komen.
• AD FS bevat een eigen webserver implementatie en heeft voor veilige communicatie een geldig SSL- servercertificaat nodig. Vraag deze voortijdig aan als deze niet beschikbaar is. Deze zal bij installatie worden gevraagd.

ADFS software installeren

Voor het installeren van de rol AD FS volg de volgende online handleiding: https://docs.microsoft.com/nl-nl/windows-server/identity/ad-fs/deployment/install-the-ad-fs-role-service

Basisinstellingen ADFS configureren

TODO

1. Controleer of de SAML 2.0 metadata informatie van uw server beschikbaar is op de volgende URL: https://<hostnaam>/FederationMetadata/2007-06/FederationMetadata.xml (vul zelf de juiste hostnaam in).
2. Deel deze URL mee aan de servicedesk van Kennisnet.

ADFS server configureren als identity provider

Om uw gebruikers met hun instellingsaccount toegang te kunnen geven tot diensten van de Entree Federatie, moet u uw ADFS server configureren als Identity Provider.

Basisconfiguratie

1. Kies Start > AD FS Management om de ADFS configuratieapplicatie te starten.

   

2. Klik op Required: Add a trusted relying party.

   

3. Klik op Start.

   

4. Vul in het veld 'Federation metadata address (host name or URL)' onderstaande URL in en klik op Next. Wanneer een melding over missende onderdelen verschijnt, klik Ok, dit gaat over logout welke niet wordt ondersteund.

   Productie: https://aselect.entree.kennisnet.nl/openaselect/profiles/saml2

   Staging: https://aselect-s.entree.kennisnet.nl/openaselect/profiles/saml2

5. Vervang in het veld 'Display name' de default hostname (aselect.entree.kennisnet.nl) door de naam Entree Federatie en klik op Next.

   

6. Controleer of Permit everyone onder policy staat en klik op Next.

   

7. Klik in dit overzichtsvenster op Next.

   

8. Deselecteer Configure claims issuance policy for this application Hiermee worden de attributen geconfigureerd. Dit doet u later in het configuratieproces (zie hoofdstuk 5).
9. Klik op Close om deze configuratie af te ronden.

Instellen metadata ververs interval

1. Stel nu de 'MonitoringInterval' in zodat de metadata van Kennisnet vaker kan worden opgehaald. Microsoft heeft de 'MonitoringInterval' standaard op 24 uur (1440 minuten) ingesteld. Kennisnet adviseert de 'MonitoringInterval' op een maximum van 2 uur (120 minuten) in te stellen, om een (langdurige) onderbreking te voorkomen zodra Kennisnet haar certificaten wijzigt.
   Het instellen van de 'MonitoringInterval' kan worden gedaan met het volgende Powershell commando op de ADFS server:

Set-AdfsProperties -MonitoringInterval <tijd in minuten>
#Voor meer informatie over Set-AdfsProperties: https://technet.microsoft.com/en-us/library/dn479342%28v=wps.630%29.aspx

SHA1-algoritme inschakelen

In ADFS worden handtekeningen standaard gezet met behulp van het SHA256-algoritme. Dit algoritme werkt niet goed samen met de Entree Federatie. Voor een goede werking moet dit vervangen worden door het SHA1-algoritme.

1. Kies in de linkerkolom van het overzichtsvenster Relying Party Trusts.

   

2. Dubbelklik in de middelste kolom op Entree Federatie.
3. Selecteer het tabblad Advanced en kies in het veld 'Secure hash algorithm' de waarde SHA-1.

   

4. Klik op OK om de configuratie voor de Entree Federatie af te ronden.

Attributen vrijgeven

Attributen zijn gebruikerskenmerken die de ADFS server na een geslaagde authenticatie van een gebruiker kan toevoegen aan informatie die aan de Entree Federatie wordt doorgegeven. Voorbeelden van attributen zijn bijvoorbeeld de voornaam, achternaam, e-mailadres, geboortedatum en rol van de gebruiker of de naam en de BRIN van uw instelling.

De set van gestandaardiseerde attributen die binnen de Entree Federatie kunnen worden gebruikt, vindt u hier:

http://developers.wiki.kennisnet.nl/index.php?title=KNF:AttributenOverzicht

U dient tenminste de als verplicht aangemerkte attributen vrij te geven aan de Entree Federatie, anders werkt de koppeling niet.

Attributen definiëren

Als eerste dienen alle attributen welke u van plan bent door te geven aan de Entree Federatie gedefinieerd te worden. Volg hiertoe de volgende stappen.

1. Kies op de ADFS server Start > (tik) AD FS Management > (klik) AD FS Management om de ADFS configuratie applicatie te starten.
2. Selecteer Service > Claims Descriptions in de linker kolom van het overzichtsvenster.

   

3. Klik in de rechterkolom onder 'Actions' op Add Claim Description…

   

4. Vul in de velden 'Display name', 'Short name' en 'Claim identifier' de waarde in van het attribuut dat u wilt vrijgeven aan de Entree Federatie, bijvoorbeeld ‘employeeNumber’. Vul voor elk attribuut in beide velden exact hetzelfde in.
5. Klik op OK.
6. Herhaal stappen 3 t/m 5 tot tenminste de volgende attributen gedefinieerd zijn:

• uid
• employeeNumber
• givenName
• nlEduPersonTussenvoegsels
• sn
• mail
• eduPersonAffiliation
• nlEduPersonHomeOrganizationId
• nlEduPersonHomeOrganization

Indien u meer attributen wilt meesturen (bijvoorbeeld ‘nlEduPersonBirthDate’ omdat een bepaalde dienstaanbieder hier om vraagt) kunt u deze op dezelfde wijze definiëren.

AD attributen toewijzen

Vervolgens dient u de attributen vrij te geven aan de Entree Federatie. Als eerste beginnen we met de attributen die standaard aanwezig zijn in Active Directory. Dit zijn LDAP-attributen.

1. Kies in de linker kolom Relying Party Trusts.

   

2. Klik in de middelste kolom op Entree Federatie en vervolgens in de rechterkolom op Edit Claim Issuance Policy.

   

3. Klik op Add Rule…

   

4. Kies onder 'Claim rule template' voor Send LDAP Attributes as Claims klik op Next.

   

5. Vul een zinvolle naam in in het veld ‘Claim rule name’, bijvoorbeeld ‘Entree’.
6. Selecteer onder ‘Attribute store’ de optie Active Directory.
7. Voeg ten minste de volgende attribuutmappings toe en klik daarna op Finish:

LDAP Attribute (in de Active Directory)	Outgoing Claim Type (naar Kennisnet toe)
User Principal Name (UPN) *	Name ID
User Principal Name (UPN) *	uid
Employee-Number	employeeNumber
Given-Name	givenName
Surname	sn
E-Mail-Addresses	mail

User Principal Name (UPN) * Voor deze gids wordt de User Principal Name (UPN) geselecteerd als bron voor de waarde van de uitgaande ‘Name ID’ en ‘uid’ claims. Het is van essentieel belang dat de ‘Name ID’ en ‘uid’ dezelfde waarde bevatten, maar dit hoeft niet perse de User Principal Name (UPN) te zijn. De waarde moet voldoen aan de beschrijving zoals deze in de Federatieve Attributen documentatie is gegeven. Dit kan heel goed uit een alternatief attribuut afkomstig zijn, of een samengesteld attribuut zijn. Het formaat moet in ieder geval als volgt zijn userid@realm wat dus sterk lijkt op het mailadres.

Belangrijk is dat dit attribuut niet meer wijzigt omdat dit de unieke identifier is waarmee de gebruiker bekend is binnen de (aangesloten diensten van de) Entree Federatie.

Custom attributen toewijzen

Voor attributen die niet (of niet direct) in de Active Directory aanwezig zijn maar wel verplicht zijn voor de Entree Federatie kunt u custom rules aanmaken. Met behulp van custom rules kunt u een bepaalde statische waarde definiëren, of deze laten afhangen van een bepaalde groep.

Statische attributen

Als de ‘nlEduPersonHomeOrganizationId’ (de BRIN van de instelling) niet aanwezig is in de AD dient hiervoor een 'Custom Rule' worden aangemaakt. Hiermee kunt u het attribuut een statische waarde geven.

1. Klik op Add Rule

   

2. Kies onder 'Claim rule template' voor Send Claims Using a Custom Rule. Klik op Next

   

3. Geef hier een beschrijving op, bijvoorbeeld 'BRIN'.
4. Bij ‘Custom rule’ moet een rule ingesteld worden die er voor zorgt dat de BRIN wordt meegestuurd. Hier is 'abcd' als BRIN gekozen, deze moet vervangen worden door de daadwerkelijke BRIN. Voorbeeld Custom rule:

   => issue(Type = "nlEduPersonHomeOrganizationId", Value = "abcd");

5. Klik op OK.
6. Herhaal stappen 1 t/m 5 voor het attribuut nlEduPersonHomeOrganization (de naam van de school)

   => issue(Type = "nlEduPersonHomeOrganization", Value = "Regenboogcollege");

Lidmaatschapsattribuut

Voor het doorgeven van de EduPersonAffiliation (de rol van de gebruiker, 'student', 'employee' of 'staff') dienen drie Custom Rules te worden aangemaakt. Hiermee kunt u het attribuut een statische waarde geven afhankelijk van de groep van de gebruiker.

1. Klik op Add rule.

   

2. Kies onder 'Claim rule template' voor Send Group Membership as a Claim en klik op Next.

   

3. Kies een omschrijving en vul deze in bij ‘Claim rule name’, bijvoorbeeld ‘eduPersonAffiliation-staff’.
4. Selecteer bij ‘User's group’ de naam van de group die bij het type gebruiker 'staff' hoort.
5. Bij ‘Outgoing claim type’ moet 'eduPersonAffiliation' worden ingevuld.
6. Bij ‘Outgoing claim value’ moet 'staff' worden ingevuld.
7. Herhaal de stappen 3 t/m 6 voor ‘student’ en ‘employee’.
8. Klik op OK.
9. Klik op OK.

Testen

U kunt testen of de aansluiting en de vrijgave van de attributen is gelukt via de ReferentieSP:

• Productie: https://referentie.entree.kennisnet.nl/referentiesp
• Staging: https://referentie-s.entree.kennisnet.nl/referentiesp

1. Selecteer uw instelling in het Where Are You From gedeelte en druk op Verder
2. U komt nu uit op een inlogpagina van uw ADFS server
3. Log in met uw instellingsaccount
4. Als alles goed is gegaan ziet u een overzicht van de attributen die worden vrijgegeven door uw instelling.

Indien u in plaats daarvan een foutmelding ziet dient u contact op te nemen met onze servicedesk.