In deze handleiding lees je hoe je jouw instelling of organisatie kunt aansluiten op SURFconext als Identity Provider, kortweg IdP,  met behulp van ADFS. In ADFS-terminologie wordt dit ook een Claims Provider genoemd. 

Deze procedure voor het aansluiten als Identity Provider op SURFconext bestaat uit de volgende onderdelen: 

Deze handleiding is gebaseerd op de release van ADFS 4 zoals voor Windows Server 2016. 

Waarom een server en een proxy inrichten? 

Om de ADFS-server minder kwetsbaar te maken voor aanvallen van buitenaf, moet je naast een ADFS server ook een ADFS-proxy inrichten buiten het Windows-domein. De ADFS-server moet namelijk bij voorkeur niet bereikbaar zijn van buitenaf. Je doet dit door een ADFS-proxy in te richten en deze ‘voor’ de ADFS-server te plaatsen. Dit houdt in dat je twee verschillende Windows Server machines moet configureren in deze opstelling. De proxy mag geen lid zijn van het domein en wordt bij voorkeur in de DMZ geplaatst. 

 


De proxy zorgt ervoor dat gebruikers die niet zijn ingelogd op het (windows-)domain, via een webpagina (username/ password formulier) kunnen inloggen. Dit formulier kan aan de look-and-feel van jouw organisatie worden aangepast. 

ADFS 4.0 Server inrichten 

Dit document beschrijft de installatie van een ADFS server op Windows Server 2016. Voordat je de specifieke instellingen voor SURFconext kunt invoeren, moet je een basisinstallatie op de ADFS server uitvoeren. Hiervoor moet je onderstaande stappen doorlopen: 

Windows Server 2016 installeren en configureren 

Om een ADFS 4.0 Server te kunnen inrichten, moet je eerst Windows Server 2016 installeren en configureren. Deze ADFS 4.0 Server dient lid te zijn van een domein. In deze handleiding installeren we de ADDS en ADFS rol op dezelfde server. Deze rollen zijn als volgt te omschrijven:

Je gaat de onderstaande stappen doorlopen om aan te sluiten op SURFconext: 

AD DS Server Rol installeren

Hieronder wordt ingegaan op het installeren van de AD DS Server Role op Windows Server 2016. Klik op hieronder op 'Click here to expand' om het stappenplan te zien.

  1. Start de Server Manager tool op de machine die als Domain Controller ingericht wordt.
  2. Klik op “Add Roles and Features”.
  3. Klik op “Next >”
  4. Klik op “Role-based or feature-based installation” en klik op “Next >”:
  5. Selecteer “Select a server from the server pool”, kies de juiste server en klik op “Next >”:
  6. Selecteer Active Directory Domain Services
  7. Klik vervolgens op ‘Add Features’
  8. Klik op ‘Next’
  9. Klik vervolgens nog een keer op ‘Next’
  10. Klik nog een keer op ‘Next’
  11. Vink het ‘Restart the destination server automatically if required’ vinkje aan en klik op ‘Install’.
  12. Klik op ‘Close’ wanneer de installatie succesvol is verlopen
  13. Klik in de Servermanager op het vlaggetje voor meldingen en kies voor de Post-deployment actie ‘Promote this server to a domain controller’
  14. In deze stap kan je kiezen of de machine wordt toegevoegd aan een bestaand domein of niet. Wij kiezen er in deze stap voor om een nieuwe forest aan te maken en geven de naam hiervoor op.
  15. Verander niets aan de settings, geeft een nieuw wachtwoord op en klik op ‘Next’
  16. Klik in deze stap op ‘Next’
  17. Controleer of de NETBIOS naam voor het domein klopt of pas hem aan naar de juiste en klik op ‘Next’
  18. In deze stap kan u de diverse paden wijzigen. Wij laten deze ongewijzigd en klikken hier op ‘Next’
  19. Er wordt een overzicht van de instellingen gegenereerd. Klik in deze stap op ‘Next’
  20. Wij krijg een aantal warnings, die wij in deze situatie mogen en kunnen negeren. Klik in deze stap op de knop ‘Install’
  21. De server zal een keer opnieuw opstarten en vanaf nu is uw server een Domain Controller en onderdeel van een domein.

ADFS Server Software installeren 

Onderstaand gedeelte van deze handleiding is te gebruiken voor het installeren van de ADFS Server Role op Windows Server 2016

  1. Start de Server Manager tool op de machine die als ADFS Server ingericht wordt.
  2.  Klik op “Add Roles and Features”.  
  3. Klik op “Next >”
  4. Klik op “Role-based or feature-based installation” en klik op “Next >”:
  5. Selecteer “Select a server from the server pool”, kies de juiste server en klik op “Next >”:
  6. Selecteer “Active Directory Federation Services” en klik op “Next >”:
    1. Procedure
  7. Klik “Next >” in het Features overzicht:
  8. Klik op “Next >”:
  9. Klik op “Install”:
  10. Wacht eventueel tot de installatie afgerond is. De wizard mag afgesloten worden, de installatie zal op de achtergrond doorgaan.
  11. Als de installatie afgerond is zal er een “Post-deployment” waarschuwing “Configuration required for Federation Service at ...” verschijnen in het Server Manager Dashboard. Klik op “Configure the federation service on this server” om de installatie van ADFS te voltooien.
  12. Klik “Next > “in het eerste scherm:
  13. Kies het AD Administrator account en klik op “Next > “:
  14. Kies het vooraf geïnstalleerde SSL certificaat (Appendix A) waarmee de ADFS dienst ontsloten zal worden en een handige “Displayname”  bijvoorbeeld Login Universiteit Harderwijk). Klik op “Next >”:
  15. De waarschuwing in de gele balk kan opgelost worden door op Show more” te klikken en het voorgestelde commando “Add-KdsRootKey -EffectiveTime (Get-Date).AddHours(-10)” in een Powershell uit te voeren. Kies voor een eenvoudige installatie een domain Administrator account voor het installeren van de ADFS service. Uit veiligheidsoogpunt en voor de beheersbaarheid kan er voor worden gekozen om een Group Managed Service Account te gebruiken:
  16. Selecteer “Create a database on this server using Windows Internal Database.” en klik op “Next >”:
  17. Klik op “Next >”:
  18. Klik op “Configure”:
  19. Wacht tot de installatie voltooid is en klik op “Close”:
  20. Om verder te gaan zijn er claim beschrijvingen nodig. “step 4” op de wiki (https://wiki.surfnet.nl/display/services/Configure+Office+365+with+AD FS+and+SURFconext+Step-by-Step) is hierbij nodig. Open PowerShell en voer de volgende commando’s uit:

    # Create AD FS Claim Descriptions 
    
    # ADD UID CLAIM DESCRIPTION
    Add-ADFSClaimDescription -Name urn:mace:dir:attribute-def:uid -ClaimType urn:mace:dir:attribute-def:uid -ShortName uid -IsAccepted $false -IsOffered $false
    
    # ADD MAIL CLAIM DESCRIPTION
    Add-ADFSClaimDescription -Name urn:mace:dir:attribute-def:mail -ClaimType urn:mace:dir:attribute-def:mail -ShortName mail -IsAccepted $false -IsOffered $false
    
    # ADD DISPLAYNAME CLAIM DESCRIPTION
    Add-ADFSClaimDescription -Name urn:mace:dir:attribute-def:displayName -ClaimType urn:mace:dir:attribute-def:displayName -ShortName displayName -IsAccepted $false -IsOffered $false
    
    # ADD schacHomeOrganization CLAIM DESCRIPTION
    Add-ADFSClaimDescription -Name schacHomeOrganization -ClaimType urn:mace:terena.org:attribute-def:schacHomeOrganization -ShortName schacHomeOrganization -IsAccepted $true -IsOffered $true
    
    # ADD eduPersonAffiliation CLAIM DESCRIPTION
    Add-ADFSClaimDescription -Name urn:mace:dir:attribute-def:eduPersonAffiliation -ClaimType urn:mace:dir:attribute-def:eduPersonAffiliation -ShortName eduPersonAffiliation -IsAccepted $true -IsOffered $true
     
    # ADD eduPersonEntitlement CLAIM DESCRIPTION
    Add-ADFSClaimDescription -Name urn:mace:dir:attribute-def:eduPersonEntitlement -ClaimType urn:mace:dir:attribute-def:eduPersonEntitlement -ShortName eduPersonEntitlement -IsAccepted $false -IsOffered $false
    
    # ADD employeeNumber CLAIM DESCRIPTION
    Add-ADFSClaimDescription -Name urn:mace:dir:attribute-def:employeeNumber -ClaimType urn:mace:dir:attribute-def:employeeNumber -ShortName employeeNumber -IsAccepted $false -IsOffered $false
  21. Stap 5 in de wiki beschrijft het toevoegen van de “SURFconext Relying Party Trust”. Download het configuratiebestand: ClaimIssuanceRules.txt (op https://edu.nl/grq3c)
  22. De url van de metadata ($MetaDataURL) is afhankelijk op welke omgeving van SURFconext wordt aangesloten (De productie- of testomgeving):
    1. De "productie omgeving van SURFconext" is t.b.v. productie diensten en productie IdP's. De Public SAML metadata (de entity descriptor) van de SURFconext SP Proxy voor deze omgeving staat op https://metadata.surfconext.nl/sp-metadata.xml.
    2. De "test omgeving van SURFconext" is voor het aansluiten van nieuwe diensten & IdP's. Deze omgeving heeft eigen SAML endpoint en staat geheel los van de "productie omgeving van SURFconext" omgeving van SURFconext". De metadata voor jouw IdP is hier te vinden: https://metadata.test.surfconext.nl/sp-metadata.xml
  23. De Public SAML metadata (de entity descriptor) van de SURFconext IdP Proxy voor deze omgeving is te vinden op onze metadata-pagina. Overweeg om te beginnen op onze testomgeving. Raadpleeg onze wiki wat deze omgevingen voor je kunnen betekenen. Gebruik de SURFconext SP proxy metadata van test of productie. Kopieer onderstaande PowerShell commando’s en voer deze uit nadat bij $MetaDataURL de juiste url is ingesteld (22.) en $ClaimIssuanceFile het pad naar het zojuist gedownloade bestand is ingesteld

    # CREATE SURFCONEXT RELYING PARTY TRUST
    $RelyingPartyTrustName = "SURFconext"
    $MetaDataURL = "https://metadata.surfconext.nl/sp-metadata.xml"
    $ClaimIssuanceFile = "THE LOCATION OF YOUR CLAIM ISSUANCE RULE FILE"
    $ACPName = "Permit everyone"
    
    Add-ADFSRelyingPartyTrust -Name $RelyingPartyTrustName -MetadataUrl $MetaDataURL -IssuanceTransformRulesFile $ClaimIssuanceFile -AutoUpdateEnabled:$true -MonitoringEnabled:$true -AccessControlPolicyName $ACPName
  24. Start “ADFS Management”:

  25. Ga naar “Relying Party Trust” en klik rechts op “SURFconext” > “Edit Claim Issuance Policy…”:
  26. Klik op “eduPersonEntitlement (SURFdrive)” en kies “Remove Rule…” > “OK”:
  27. Kies voor “schacHomeOrganization” > “Edit rule…”:
  28. Kies voor “Browse” bij “User’s  group” en vul “Domain Users” in > “OK” en weer “OK”:
  29. Doe hetzelfde voor de eduPersonAffiliation Student en Employee. Vul bij Student de studenten AD groep in. Bij Employee de medewerkers AD groep. Indien deze AD groepen nog niet bestaan maak deze dan aan. En Klik “OK” om dit scherm te sluiten.
  30. Custom claim rules. Het kan voorkomen dat de gewenste waarde van een bepaald attribuut niet beschikbaar is in AD maar wel daaruit afgeleid zou kunnen worden. Een voorbeeld is schacPersonalUniqueCode. De vereiste syntax van dit attribuut is: urn:schac:personalUniqueCode:nl:local:<schacHomeOrganisation>:<id_type>:<id_token>. Let op dat de waarde een URN is en daarom moet voeldoen aan de eisen die aan een URN gesteld worden. Een belangrijke eis is dat een URN geen spaties mag bevatten. Bijvoorbeeld: urn:schac:personalUniqueCode:nl:local:uniharderwijk.nl:employeeid:90210. Hiervan is het employeeid “90210” waarschijnlijk wel beschikbaar als medewerkernummer en kan het attribuut dus samengesteld worden uit de tekst “urn:schac:personalUniqueCode:nl:local:uniharderwijk.nl:employeeid:” en bijvoorbeeld (de waarde van) het AD attribuut Employee-Number. Hiervoor kennen we de waarde van het AD attribuut Employee-Number eerst toe aan “urn:mace:dir:attribute-def:employeeNumber” en stellen daarmee later de personalUniqueCode samen.
  31. Edit opnieuw de Claim Rules van de Relying Party SURFconext
  32. Edit opnieuw de “AD Attributen” rule.
  33. Voeg een regel toe die Employee-Number koppelt aan  “urn:mace:dir:attribute-def:employeeNumber”.
  34. Sla de rule op en voeg een Custom claim rule toe door op de “Add Rule...” knop te klikken.
  35. Kies in het volgende venster voor “Send Claims Using a Custom Rule” en klik op “Next”:
  36. Geef de rule een beschrijvende naam zoals “schacPersonalUniqueCode” en creëer de gewenste attribuutsamenstelling op basis van een tekst en één of meerdere bestaande attributen.

    c:[Type == "urn:mace:dir:attribute-def:employeeNumber"]
    
     => issue(Type = "urn:schac:attribute-def:schacPersonalUniqueCode", Value = "urn:schac:personalUniqueCode:nl:local:uniharderwijk.nl:employeeid:" + c.Value);
    
    # Bovenstaande code dient als volgt gelezen worden:
    
    #Als een attribuut van het type “urn:mace:dir:attribute-def:employeeNumber” bestaat, bewaar dit attribuut dan in variabele “c” en geef een nieuw attribuut van type “urn:schac:attribute-def:schacPersonalUniqueCode” uit met een samenstelling van de letterlijke tekst urn:schac:personalUniqueCode:nl:local:uniharderwijk.nl:employeeid:” en de waarde van het attribuut in variabele “c”.

    Het venster ziet er dan ongeveer zo uit:

  37. Als de Rule compleet is, klik dan op “OK”.
  38. Een meer geavanceerde rule, welke ook de “schacHomeOrganization” en de “affiliation” meeneemt, ziet er dan als volgt uit:


    c1:[Type == "urn:mace:dir:attribute-def:employeeNumber"] &&
    c2:[Type == "urn:mace:terena.org:attribute-def:schacHomeOrganization"] &&
    c3:[Type == "urn:mace:dir:attribute-def:eduPersonAffiliation"]
     => issue(Type = "urn:schac:attribute-def:schacPersonalUniqueCode", Value = "urn:schac:personalUniqueCode:nl:local:" + c2.Value + ":" + c3.Value + "id:" + c1.Value);
  39. eduPersonScopedAffiliation. Om eduPersonScopedAffiliation toe te voegen aan de ADFS claims kan de volgende Custom claims rule gebruikt worden, er vanuit gaande dat de claims "urn:mace:dir:attribute- def:eduPersonAffiliation" en "urn:mace:terena.org:attribute-def:schacHomeOrganization" zoals eerder in deze handleiding beschreven, correct gedefinieerd zijn. Kies weer voor "Edit Claim rules" en "Add Rule". Kies in het volgende scherm voor "Send Claims Using a Custom Rule" en klik op "Next". Geef de Rule een beschrijvende naam zoals "Create eduPersonScopedAffiliation" en plak de volgende code in het "Custom Rule" venster: 

    c1:[Type == "urn:mace:dir:attribute-def:eduPersonAffiliation"] &&
       c2:[Type == "urn:mace:terena.org:attribute-def:schacHomeOrganization"]
       => issue(Type = "urn:mace:dir:attribute-
       def:eduPersonScopedAffiliation", Value = c1.Value + "@" + c2.Value);

    Klik "Finish" en klik "Ok" in de "Edit Claims Rules" dialoog. Test hierna de uitgifte van het nieuwe attribuut.

  40. Toevoegen claim op basis van groepslidmaatschap, bv eduPersonEntitlement:
    c:[Type == http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid, Value == "<Type hier het SID van de juiste AD groep>" Issuer == "AD AUTHORITY"]
    => issue(Type = "urn:mace:dir:attribute-def:eduPersonEntitlement", Value = "urn:mace:surfnet.nl:surfconext.nl:surfnet.nl:eduvpn:admin", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);



  41. Klik "Finish" en klik "Ok" in de "Edit Claims Rules" dialoog. Test hierna de uitgifte van het nieuwe attribuut. 
  42. Klik rechts op “SURFconext” en kies “Enable”:
  43. De Server Manager moet eruitzien zoals onderstaand:


ADFS Proxy installeren 

Algemeen 

Het is belangrijk dat de ADFS Proxy de ADFS server onder de voor de ADFS service gekozen DNS naam kan bereiken. De Proxy zelf moet echter onder dezelfde naam voor de buitenwereld (het internet) bereikbaar zijn. Hiervoor kan een split-DNS configuratie ingericht worden. Dit is een Domain Name System (DNS) implementatie waarbij verschillende verzamelingen DNS gegevens worden geleverd afhankelijk van de bron van het DNS verzoek. In de praktijk komt het er op neer dat de DNS server voor een computer binnen het intranet een private adres van de server binnen de intranet grenzen geeft en voor gebruikers van buitenaf (het internet) het adres van de server in de DMZ of de firewall/router die verbonden is met de server. Als dat niet mogelijk is, moet de Proxy op een andere manier verteld worden wat het IP adres van de ADFS server is. Dit kan met behulp van de hosts file (C:\Windows\System32\Drivers\etc). Voeg hiervoor een regel toe met vooraan het fysieke adres van de ADFS server en daarachter de servicenaam waaronder de ADFS dienst beschikbaar is: 


# Copyright (c) 1993-2009 Microsoft Corp.
#
# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
#
# This file contains the mappings of IP addresses to host names. Each
# entry should be kept on an individual line. The IP address should
# be placed in the first column followed by the corresponding host name.
# The IP address and the host name should be separated by at least one
# space.
#
# Additionally, comments (such as these) may be inserted on individual
# lines or following the machine name denoted by a '#' symbol.
#
# For example:
#
#      102.54.94.97     rhino.acme.com          # source server
#       38.25.63.10     x.acme.com              # x client host
# localhost name resolution is handled within DNS itself.
#127.0.0.1       localhost
#::1             localhost
145.0.6.22 login2.wind.surfnet.nl

Let op: dit bestand is alleen als Administrator te bewerken. Start hiervoor een Notepad op onder “run as Adminstrator” conditie. 

ADFS Proxy installeren

We gaan nu de ADFS Proxy installeren. Volg de stappen zoals hieronder aangegeven.

  1. Kies in het Server Manager Dashboard weer voor “Add roles and features” en klik zoals hiervoor beschreven door de eerste schermen en selecteer ditmaal “Remote Access”:
  2. Klik “Next >” tot je bij “Role Services” bent en kies “Web Application Proxy” > “Next >”:
  3. Klik op “Install”, wacht eventueel de installatie af en klik op “Close”:
  4. De Proxy configuratie vereist een geldig en werkend SSL certificaat. Installeer hiervoor eerst het SSL certificaat dat ook op de ADFS Server geïnstalleerd is door het daar bijvoorbeeld als .pfx bestand te exporteren. Zie voor de installatie van een SSL certificaat “Appendix A: Certificaat Installeren”.
  5. Na installatie verschijnt een Post-deployment alert “Configuration required for the Federation Service Proxy at ...” in het Server Manager Dashboard. Klik op deze link:
  6. De “Web Application Proxy Configuration Wizard” wordt geopend, klik op “Next > “:
  7. Kies dezelfde DNS naam als de ADFS Server voor “Federation Service Name” en vul de username en password in:
  8. Selecteer het certificaat (Appendix A) en klik op “Next >”:
  9. Klik op “Configure”:
  10. Klik op “Close”:
  11. Surf ter controle naar de ADFS service URL (zowel vanuit een plek die op de ADFS Server uitkomt als vanaf een plek die op de Proxy uitkomt) en controleer de inhoud van de volgende URL: https://<servicenaam>/federationmetadata/2007-06/federationmetadata.xml. Deze URL dient zoals hieronder te zien is een XML document te bevatten. Als de browser geen document laat zien kan met “View Source” het document in een editor getoond worden
  12. Als deze test slaagt kan de metadata URL aan SURFconext doorgegeven worden zoals beschreven in het hoofdstuk “Metadata doorgeven aan SURFconext”. 




Op de ADFS Proxy is deze URL nu nog plaintext (http) beschikbaar. Dit kan geen kwaad, maar kan voor de zekerheid uitgeschakeld worden door de binding van de default site in IIS met poort 80 ongedaan te maken.

Metadata doorgeven aan SURFconext

Als de ADFS server en ADFS Proxy of Web Application Proxy geïnstalleerd zijn en hun werking gecontroleerd kan de metadata URL doorgeven worden aan SURFconext. Om er voor te zorgen dat de metadata voor de Identity Provider langer houdbaar is verlengen we de duur van het Token Signing certificaat op de ADFS server eerst even door in een Powershell de volgende commando's uit te voeren: 


Set-ADFSProperties -CertificateDuration 1825 

 

Als er nog geen andere Relying Party Trusts configuraties bestonden voor deze installatie: 

Update-ADFSCertificate -CertificateType Token-Signing -Urgent 

(deze worden namelijk onbruikbaar door het uitvoeren van bovenstaande commando) 

En ter controle:  

Get-ADFSCertificate -CertificateType Token-Signing 



Het Token-Signing certificaat is nu als het goed is vijf jaar geldig. 

 

Aanleveren Metadata 

Vervolgens kan een mail naar SURFconext gestuurd worden (support@surfconext.nl) met daarin de volgende informatie:  

 En alle onder deze URL genoemde extra gegevens: https://wiki.surfnet.nl/display/surfconextdev/Vereiste+metadata. Het advies is om Appendix B door te nemen over openstaande poorten op de server.

Appendix A Certificaat installeren 

Deze handleiding gaat er vanuit dat het certificaat plus private key beschikbaar is in de vorm van een .pfx bestand. Als het certificaat en de private key alleen los beschikbaar zijn als respectievelijk cert.pem en cert.key met certificate chain chain.pem, is daar met het volgende openssl commando een cert.pfx bestand van te maken: 

#openssl pkcs12 -export -passout pass:123welkom -in cert.pem -certfile chain.pem -inkey cert.key -out cert.pfx 

Het cert.pfx bestand heeft nu als voorbeeld wachtwoord 123welkom


Volg het stappenplan zoals hieronder aangegeven.


  1. Open MMC in het start menu.
  2.  Ga naar “File” -> “Add/Remove Snap-in”.
  3. Klik links op “Certificates” en op “Add”:
  4. Kies voor “Computer account” en klik op “Next”.
  5. Klik op “Finish”.
  6. En klik op “OK”.
  7. Klik rechts op “Personal” -> “All Tasks” -> “Import…”:
  8. Klik op “Next”:
  9. Klik op “Browse” en selecteer het certificaat en klik op “Next”:
  10. Vul het wachtwoord in en klik op “Next”:
  11. Kies de “Personal store” en klik op “Next”:
  12. Klik op “Finish”:
  13. Klik op “OK” als aangegeven wordt dat de import succesvol is.
  14. Controleer of het certificaat, inclusief private key, correct geïmporteerd is. Aanwezigheid van de private key is te herkennen aan het sleuteltje linksboven het icoontje van het certificaat.


Appendix B Poorten dichtzetten

Om verkeerd gebruik van je proxy te voorkomen kun je Outbound en Inbound regels definieren. Doorloop onderstaande stappen en maak aanpassingen waar nodig om poorten dicht te zetten of regels te definieren. 

  1. Ga naar de ADFS server
  2. Open “Windows Firewall”. 
  3. Ga naar “Inbound Rules":
  4. Disable de volgende regels:
    1. Active Directory Domain Controller - LDAP (TCP-In)
    2. Active Directory Domain Controller - LDAP (UDP-In)
    3. Active Directory Domain Controller - LDAP for Global Catalog (UDP-In)
    4. Active Directory Web Services (TCP-In)
    5. DNS (TCP, Incoming)
    6. DNS (UDP, Incoming)
  5. Ga naar Outbound rules en disable de volgende regels:
    1. Xbox Game UI
  6. Ga nu naar de ADFS Proxy en open daar ook Windows Firewall
  7. Ga naar Outbound rules en disable de volgende regels:
    1. Xbox Game UI