SURFnet heeft een multifactor authenticatie (MFA) extensie ontwikkeld voor Microsoft AD FS voor gebruik met SURFconext Sterke Authenticatie (SA). Met deze extensie kan de tweede factor van een gebruiker in SURFconext SA worden gebruikt voor MFA authenticatie in AD FS. De registratie, vetting en het beheer van de tweede factors blijft via SURFconext SA lopen. De authenticatie van een relying party (RP) die aangesloten is op de AD FS server blijft lopen via de AD FS server. Op de AD FS server wordt geconfigureerd wanneer er voor RP MFA authenticatie nodig is. Als de ADFS MFA extensie voor SURFconext SA door AD FS wordt aangeroepen, dan verzorgd deze de authenticatie van de tweede factor van een gebruiker bij SURFconext SA.

Op deze pagina staat de installatie procedure van deze extensie beschreven. Ook geven we aan waar meer informatie over de extensie gevonden kan worden. Deze pagina beschrijft installatie van versie 1.0 van de MFA extensie op ADFS 3.0 (Windows 2012 R2) en ADFS 4.0 (Windows 2016). Eerdere versies van de extensie (0.1 en 0.2) worden niet meer ondersteund.

Voor gebruik van de plugin zijn nodig:

Een productie koppeling van een eigen identity provider op SURFconext
Een koppeling op SURFconext SA productie of SURFconext SA pilot omgeving
Een Microsoft Windows domain met AD FS

We werken momenteel aan een nieuwe installatiehandleiding en een nieuwe installatie methode voor de ADFS MFA extensie voor SURFconext SA.

Installatieprocedure

De MFA extensie moet op iedere AD FS server worden geïnstalleerd waarop MFA plaats moet vinden. De installatie procedure voor de 2e, 3e etc AD FS server wijkt af van de eerste.

Stap 1 - Download SetupPackage.zip

Download SetupPackage.zip van https://github.com/SURFnet/ADFS-MFA-SAML2.0-Extension/releases/download/1.0/SetupPackage.zip en pak deze uit op de eerste AD FS server.

Stap 2 - Pas SurfnetMfaPluginConfiguration.json aan

In de Setup directory van de uitgepakte SetupPackage.zip staat SurfnetMfaPluginConfiguration.json. Hierin staan de configuratie parameters die door het installatie script gebruikt worden om de plugin te installeren. Pas dit bestand aan.

Hieronder staat een gedeeltelijk ingevulde SurfnetMfaPluginConfiguration.json voor gebruik met de SURFconext SA Pilot omgeving, de lege waarden zijn specifiek voor de organisatie. Behalve SigningCertificate moeten deze allemaal ingevuld worden.

SurfnetMfaPluginConfiguration.json voor SURFconext SA Pilot

{
  "Settings": {
    "SecondFactorEndpoint": "https://gateway.pilot.stepup.surfconext.nl/second-factor-only/single-sign-on",
    "MinimalLoa": "http://pilot.surfconext.nl/assurance/sfo-level2",
    "schacHomeOrganization": "",
    "ActiveDirectoryName": "",
    "ActiveDirectoryUserIdAttribute": ""
  },
  "ServiceProvider": {
    "SigningCertificate": "",
    "EntityId": ""
  },
  "IdentityProvider": {
    "EntityId": "https://gateway.pilot.stepup.surfconext.nl/second-factor-only/metadata",
    "Certificate": "sa_pilot_saml_signing_certificate_pem.crt"
  }
}

Waarde		Beschrijving
Settings
	SecondFactorEndpoint	Dit is de SingleSignOnService Location van de SA gateway. Deze staat in de SAML metadata van de omgeving en is verschillend voor de test, pilot en productie omgevingen.
	MinimalLoa	Dit is geeft aan welk nivo van authenticatie vereist is. De ondersteunde identifiers zijn verschillend voor de test, pilot en productie omgevingen. "level2" staat alle type tokens toe, "level3" alleen YubiKey.
	schacHomeOrganization	Dit is de waarde voor schacHomeOrganization die voor de gebruiker is geregistreerd tijdens de registratie van het token in SURFconext SA. Deze waarde wordt de de extensie gebruikt om de SURFconext identifier van de gebruiker te bepalen voor authenticatie op de gateway. Dit heeft de vorm van een domeinnaam. Bijvoorbeeld: `catharijnecollege.nl`.
	ActiveDirectoryName	Dit is de DNS naam van de locale active directory (AD) server. Deze AD wordt gebruikt voor het opzoeken van het `uid` van de gebruiker. Bijvoorbeeld: `corp.contoso.com`
	ActiveDirectoryUserIdAttribute	Dit is de naam van het attribuut in de locale active directory (AD) server welke het `uid` van de gebruiker bevat dat gebruikt wordt voor de authenticatie naar SURFconext. De waarde uit dit attribuut wordt de de extensie gebruikt om de SURFconext identifier van de gebruiker te bepalen voor authenticatie op de gateway.
ServiceProvider
	SigningCertificate	Naam van een .pfx bestand in de `Setup` directory met daarin het X.509 certificaat en de RSA private key waarmee de authenticatie verzoeken van de extensie naar de SURFconext SA gateway worden ondertekend. Voor installatie op de 1e AD FS server kan dit leeggelaten worden, het installatie stript zal dan zelf een certificaat en private key genereren, en deze exporteren naar een .pfx bestand. Een .pfx bestand is een PKCS#12 in DER formaat.
	EntityId	Dit is het SAML EntityID van de extensie welke de extensie uniek identificeert richting SURFconext SA. Deze waarde is vrij te kiezen en heeft de vorm van een URL of een URN. De in de URL gebruikte identifier moet onder eigen beheer zijn. Voorbeeld: `http://catharijnecollege.nl/adfs-mfa-extension`
IdentityProvider
	EntityId	Dit is het SAML EnitityID van de SURFconext SA gateway. Deze staat in de SAML metadata van de omgeving en is verschillend voor de test, pilot en productie omgevingen.
	Certificate	Naam van een .crt bestand in de `Setup` directory met daarin het X.509 signing certificaat van de SURFconext SA gateway in PEM formaat. Dit certificaat staat in de SAML metadata van de omgeving en is verschillend voor de test, pilot en productie omgevingen. Zie de volgende stap (Stap 3).

Stap 3 - Download het SURFconext SA signing certificaat

Download het SAML signing certificaat van de SURFconext Sterke Authenticatie gateway, zet dit in de Setup directory van de extensie op de AD FS server, en zorg dat Certificate in de SurfnetMfaPluginConfiguration.json (zie ook de vorig stap) naar deze file refereert. Dit certificaat staat in de SAML metadata van de omgeving en is verschillend voor de test, pilot en productie omgevingen.

Pilot omgeving: https://wiki.surfnet.nl/download/attachments/50111280/sa_pilot_saml_signing_certificate_pem.crt
Productie omgeving: https://wiki.surfnet.nl/download/attachments/50111280/sa_production_saml_signing_certificate_pem.crt

Stap 4 - Run het Install-SurfnetMfaPlugin.ps1 installatie script op de 1e AD FS Server

Het installatie script herstart de AD FS service.

Open, als gebruiker met Administrator rechten, een powershell op de AD FS server.
Ga naar de Setup directory (van de uitgepakte SetupPackage.zip)
Run Install-SurfnetMfaPlugin.ps1

Bij eerste installatie schrijft het installatiescript een aantal files weg:

Een backup van de ADFS configuratie (C:\Windows\ADFS\Microsoft.IdentityServer.Servicehost.exe.config)
Een export van het gegenereerde SAML signing certificaat van de plugin
De SigningCertificate parameter in de SurfnetMfaPluginConfiguration.json wordt gevuld met deze file.

Bewaar deze, en bewaar ook de uitvoer van het script, op een veilige plaats.

Er zit een beperking in het huidige installatiescript. Na een eerste installatie zal de AD FS configuratie bij het nogmaals uitvoeren van het script niet worden aangepast. Wijzigingen in SurfnetMfaPluginConfiguration.json worden dus niet overgenomen. Er moet eerste een volledige uninstall worden gedaan om het installatiescript weer te kunnen gebruiken met een aangepaste configuratie. De (aangepaste) SurfnetMfaPluginConfiguration.json en het gegenereerde certificaat kunnen wel worden hergebruikt.

Stap 5 - Run het Install-SurfnetMfaPlugin.ps1 installatie script op de andere AD FS Servers

Het installatie script herstart de AD FS service.

Kopieer de uitgepakte SetupPackage.zip directory, met daarin de Setup directory en de bij installatie aangepaste en toegevoegde bestanden van de eerste AD FS server naar deze AD FS server.
Ga naar de Setup directory (van de uitgepakte SetupPackage.zip)
Run Install-SurfnetMfaPlugin.ps1
Het script zal vragen om een password, dit password staat in de uitvoer van het installatiescript script van de eerste server.

Stap 6 - Laat een koppeling maken voor de extensie in SURFconext SA

Stuur een mail aan support@surfconext.nl met daarin de volgende informatie:

Om welke instelling gaat het (wat is de waarde van het schacHomeOrganization attribuut?)
Aan welke SURFconext SA omgeving moet de extensie gekoppeld worden: Pilot of Productie?
Wat is de Issuer (het EntityID) van de extensie? Dit staat in de uitvoer van het installatiescript
Wat is het SAML signing certificaat van de extensie? Dit staat in de uitvoer van het installatiescript

Stap 7 - Configureer MFA in AD FS

Na installatie van de extensie zal deze als MFA methode als "ADFS.SCSA" beschikbaar zijn in AD FS, maar deze wordt nog niet gebruikt voor authenticatie. Daarvoor moet deze methode eerste aangezet worden, en moet aangegeven worden voor welke gebruikers en voor welke Relying Parties MFA vereist is.

Alle configuratie vindt plaats in AD FS Management (Administrative Tools).

Enable de ADFS.SCSA MFA extansie

Ga naar "Authentication Policies" en kies voor "Edit Global Multi-factor Authentication"
Enable "ADFS.SCSA" door deze aan te vinken.
Optioneel kan in dit scherm voor alle alle Relying Parties op basis van groeplidmaatschap MFA aangezet worden

Enable MFA per Relyng Partie

Ga naar "Authentication Policies" en dan "Per Relying Party Trust", selecteer de Relying Party waarvoor je MFA wil configureren, en kies voor "Edit Custom Multi-factor Authentication".
Geef aan voor welke gebruikers / groepen voor authenticatie naar deze Relying Party MFA vereist is. Daarnaast kan op basis van registered / unregistered of intranet / extranet MFA voor een Relying Party worden vereist.

Opmerkingen

De AD FS MFA extensie heeft haar eigen SAML implementatie en configuratie welk lost staat van AD FS. Hoewel de extensie is een SAML service provider (SP) voor SURFconext SA, staat deze dus niet onder de relying parties in de AD FS config.

Page tree

Installatie ADFS MFA Extensie