Inleiding
In deze handleiding lees je hoe je jouw organisatie kunt aansluiten op SURFconext als Identity Provider met behulp van Microsoft Azure AD. Deze pagina is gebaseerd op het document zoals opgesteld door Platani en ROC Friese Poort. Zie daarvoor deze link. Omdat er sindsdien wijzigingen zijn doorgevoerd bij SURFconext is deze bijgewerkte pagina opgesteld.
In de handleiding van InSpark wordt specifiek in gegaan op de ondersteuning van multivalue attributen zoals de eduPersonEntitlement. Op deze pagina worden de volgende onderwerpen uitgelicht:
Azure AD Premium en SAML
Voor het inschakelen van SAML in Azure AD is Azure AD Premium P1 of hoger nodig. Raadpleeg de website van Microsoft voor meer details over het gebruik van SAML met Azure AD.
Configuratie Azure AD koppeling met SURFconext
Met onderstaande screenshots wordt het maken van een koppeling tussen Azure AD (Premium P1) en SURFconext beschreven. In de loop van de tijd kunnen schermen in Azure AD wijzigen. Mail naar support@surfconext.nl als je vragen hebt. Log om te beginnen in op https://portal.azure.com en ga naar ‘Azure Active Directory’. Klik vervolgens op ‘Enterprise Applications’.
Klik nu op ‘New application’
Selecteer de optie ‘Non-gallery application’.
Vul bij ‘Name’ ‘SURFconext’ in en klik op ‘Add’.
De ‘Enterprise Application’ voor SURFconext is nu aangemaakt en kan geconfigureerd worden. Ga eerst naar de optie ‘Properties’. Upload indien gewenst een logo in png formaat. Wanneer er niet per individuele gebruiker toegang tot de SURFconext Service Provider hoeft te worden geconfigureerd passen we de ‘user assingment required’ aan naar ‘No’, Klik op ‘Save’ om de wijzigingen op te slaan.
Klik nu in het menu links op ‘Single sign-on’. Hieronder wordt aangegeven hoe je de belangrijkste instellingen voor de SAML koppeling configureert. Selecteer uit het pull-down menu bij Single Sign-on de methode ‘SAML-based Sign-on’. Voer de volgende gegevens in die je vindt op de metadata pagina van SURFconext. Vink hiervoor ‘Show advanced URL settings' aan:
- Identifier (Dit is het entityID van SURFconext): https://engine.surfconext.nl/authentication/sp/metadata
- Reply URL (AssertionConsumerService:Location URL in de metadata): https://engine.surfconext.nl/authentication/sp/consume-assertion
- Sign on URL (AssertionConsumerService:Location URL in de metadata): https://engine.surfconext.nl/authentication/sp/consume-assertion
Verwijder vervolgens de bestaande default claims, de SAML Token Attributes.
Nu kunnen we onder ‘SAML Token Attributes’ de juiste claims, attributen in SAML, voor SURFconext toevoegen. Zorg er allereerst voor dat ‘View and edit all other user attributes’ aan staat.
Klik op ‘Add Attribute’ om de eerste ‘Claim’ toe te voegen.
Voer nu de juiste gegevens voor de ‘Claim’ in. De geldige claims of attributen voor SURFconext worden hier beschreven. Het screenshot hieronder geeft een voorbeeld voor het email adres.
- Name: urn:mace:dir:attribute-def:mail
- Value: user.mail
Het uiteindelijke resultaat ziet er als volgt uit. De LDAP-attributen die gebruikt worden dienen de juiste waarden te bevatten. Dit wordt geregeld door de synchronisatie van Active Directory via Azure AD Connect. Deze kunnen op een aantal manieren ingevuld worden:
- Statisch - zoals bijvoorbeeld de waarde NL bij urn:mace:dir:attribute-def:preferredLanguage;
- LDAP attribuut. Hierbij wordt het attribuut voorafgegaan door ‘user.’. Deze attributen kunnen uit een dropdown lijst worden geselecteerd;
- Het is ook mogelijk om waarden samen te voegen via ‘Join()’ off om combinaties te maken met de email suffix via ‘ExtractMailPrefix()’.
Geef alle attributen op die vermeld staan op Vereiste attributen.
Voer ten slotte een email adres in bij ‘Notification Email’. Dit adres wordt gebruikt om een notificatie te sturen wanneer het ‘token signing certificaat’ (na 3 jaar) dreigt te verlopen.
De Metadata URL van de Azure AD IdP
SURF heeft de metadata van de IdP nodig om deze te kunnen configureren in SURFconext. Je kunt de metadata-URL of de metadata als XML naar SURF mailen zodat configuratie kan worden toegevoegd aan SURFconext. De makkelijkste en meest robuuste manier is met gebruik van de metadata-URL. Deze wordt door Azure AD gemaakt. Dit werkt goed omdat dan de endpoints automatisch kunnen worden geconfigureerd en bijgewerkt. Hieronder is aangegeven waar die te vinden is. Deze link is te kopiëren door op het kopieericoon rechts van de aangegeven link te klikken:
Mail de App Federation Metadata-URL naar het SURFconext-team: support@surfconext.nl
Als het nodig is de metadata te downloaden of als XML te sturen kun je dat doen zoals hieronder aangegeven. Bedenk dat de endpoints dan niet automatisch worden bijgewerkt:
Mail de XML naar het SURFconext-team: support@surfconext.nl
Controle SHA-256
Controleer dat bij het Signing Algorithm, SHA-256 is geselecteerd. Dit is de standaard in Azure AD. Deze informatie kan zichtbaar gemaakt worden door het vinkje ‘Show advanced certificate signing settings’ in te schakelen.
Multi Valued Attributen en Extension Attributes
Om de functionaliteit van een Azure AD Identity Provider met SURFconext volledig te benutten moet in de configuratie van de Azure IdP gebruik gemaakt worden van de 'Extension Attributes', ExtensionAttribute1 tot ExtensionAttribute15. Zo kan bijvoorbeeld de waarde van het attribuut 'urn:mace:dir:attribute-def:eduPersonEntitlement' samengesteld worden uit twee extension attributes. Dit wordt gedaan door het attribuut samen te voegen via het pull down in het add attribute scherm 'Join()'. Zo kan bijvoorbeeld een urn:mace:dir:attribute-def:eduPersonEntitlement voor SURFdrive gevuld worden met de waarden 'urn:x-surfnet:surf.nl:surfdrive:quota:' en de gebruiker specifieke waarde '100'. Controleer de output van je IdP op de debug pagina van SURFconext. Hier laat de kolom 'Validation' zien of het attribuut correct gevuld is. SURFconext ondersteunt dus attributen waarin meer dan één waarde mag voorkomen. Hieronder zie je hoe daar bij ROC Friese Poort mee is omgegaan
- eduPersonEntitlement: Samengevoegde waarde uit een vaste string en het AD veld employeeID
- eduPersonAffiliation: dit veld hebben is opgeslagen bij alle gebruikers in AD in ExtensionAttribute1
- eduPersonPrincipalName: UserPrincipalName uit AD (Dit moet dan wel gelijk zijn aan het e-mailadres)
In onderstaande tabel wordt als voorbeeld de constructie van alle claims voor ROC Friese Poort uitgelegd. Details omtrent de waarden van deze claims kunnen op de website van SURFconext worden gevonden.
Dit ziet er voor eduPersonEntitlement dan als volgt uit:
Het veld ‘urn:mace:dir:attribute-def:eduPersonEntitlement’ wordt dus geconstrueerd uit een string (String1) en de employeeID (String2) uit de Active Directory. Omdat in deze constructie het veld employeeID niet leeg mag zijn, is ervoor gekozen om voor iedereen die geen employeeID heeft, dit veld op de waarde ‘0’ te zetten. Wanneer dit niet zou worden gedaan, treedt na het inloggen in bijvoorbeeld Office 365 onderstaande foutmelding op:
Pass-Through Authentication
Op het moment van het opstellen van het document van Platani is het wat betreft claims (transformaties) zo dat je nog steeds niet kunt doen wat in ADFS kan, maar Azure ontwikkelt zich snel en voor ROC Friese Poort voldeed het.
Bij ROC Friese poort wordt ook gebruik gemaakt van de 'SSO/Pass Through Authentication' (PTA) functie om in te loggen op Azure AD vanaf een werkplek (domain Joined) om toegang te krijgen tot de diensten. Dit is een 'Complete SSO', gestart vanaf de Windows client login. Dit hangt af van Azure Pass Through Authentication en Seamless Sign On. Zie https://docs.microsoft.com/en-us/azure/active-directory/connect/active-directory-aadconnect-pass-through-authentication.
Nu dat beschikbaar is, zullen klanten die voorheen een ADFS-omgeving moesten bouwen dat niet meer doen. In feite heb je op deze manier ADFS als dienst. Zeer interessant voor onderwijsinstellingen, omdat ze de benodigde licentie (Azure AD Premium) helemaal gratis krijgen.
Bij het het gebruik van pass-through authenticatie (PTA) is het nog steeds zo dat je wachtwoorden via Microsoft-infrastructuur moet doorgeven: https://docs.microsoft.com/en-us/azure/active-directory/connect/active-directory-aadconnect-pass-through-authentication-how-it-works.
PTA is interessant voor organisaties die Microsoft vertrouwen voor het beheer van hun accounts (inclusief wachtwoorden), maar die accounts graag via een On Premise AD beheren in plaats van het beheersportaal van Azure AD. Wachtwoorden zijn nog steeds zichtbaar voor Microsoft, hoewel ze niet opgeslagen hoeven te worden.
Sessieduur of TokenLifetimePolicy
Een verkeerd ingestelde AccessTokenLifetime zal onduidelijke foutmeldingen geven. Een fout 404 of Authentication Instant is too old or in the future zijn hier voorbeelden van. Ook zal de SURFconext OIDC Gateway een foutmelding geven als een gebruiker op jouw IdP na een jaar niet een nieuwe sessie heeft opgestart en opnieuw is aangemeld. Diensten kunnen controleren wanneer een gebruiker voor het laatst is aangemeld op de IdP door te kijken naar het ' saml:AuthnStatement ' die ze ontvangen. Als de dienst deze tijd niet accepteert gaat het aanmelden fout met vaak onduidelijke meldingen tot gevolg. Zie hiervoor de saml:AuthnStatement AuthnInstant of SessionNotOnOrAfter in de SAML post en controleer de eisen van de dienst. Maak een een SAML trace om te zien hoe oud het AuthnStatement is als je tegen fouten aanloopt.
De default waarde van 1 uur uur in Azure zal doorgaans werken met SURFconext. Om het gebruikersgemak van SURFconext tot zijn recht te laten komen kun je een werkdag aanhouden; 8 uur of 12 uur. De daaropvolgende werkdag zal de gebruiker weer een prompt krijgen aan te melden. Zie voor meer informatie de support pagina van Microsoft over token lifetimes in Azure Active Directory.