Page tree
Skip to end of metadata
Go to start of metadata

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 ook ingegaan op de ondersteuning van multivalued 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 onder Manage op Enterprise applications.



Klik nu op ‘New application’


En selecteer de optie ‘Non-gallery application’. Vul bij ‘Name’ bijvoorbeeld ‘SURFconext’ in (SURFconext (Test) in het voorbeeld hieronder) 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 van SURFconext 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’.

Setup Single Sign-On with SAML

De Single Sign-on configuratie wordt als een stappenplan gepresenteerd. Er moeten 4 stappen doorlopen worden om bij stap 5 uit te komen en de verbinding met SURFconext te testen.

De metadata van SURFconext instellen

Voer de volgende gegevens in die je vindt op de metadata pagina van SURFconext. Vink hiervoor ‘Show advanced URL settings' aan:


Beheren van Claims (ofwel attributen).

In deze stap worden de SAML Attributen gevuld met de in Azure beschikbare Claims. Verwijder om te beginnen de bestaande default 'Additional claims'. Klik vervolgens op Add new claim. Een scherm met Manage claim verschijnt. Hier kun je een voor jou handige naam voor een attribuut invullen. Vul daarnaast voor de namespace de waarden in zoals je vindt op onze pagina over attributen. Geef alle attributen op die vermeld staan op pagina van Vereiste attributen. Die pagina geeft ook aan welke je minimaal gevuld moet hebben om succesvol met SURFconext aan te melden. In het voorbeeld hieronder vullen we het uid met de namespace 'urn:mace:dir:attribute-def:uid' en gebruiken hiervoor de bron 'user.onpremisessamaccountname'. Een ander voorbeeld kan zijn om urn:mace:dir:attribute-def:mail te vullen met user.mail. Deze mapping is aan jou om te bepalen en hangt af van hoe je je IdP hebt ingericht:


Je krijgt een lijst met additional claims die je zo volledig mogelijk vult. SURFconext ondersteunt twee attributen schema's die je beide kunt vullen:

  • urn:oid schema (SAML2.0 compliant) 
  • urn schema (SAML1.1 compliant) 

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 en surfguest.nl bij urn:mace:terena.org:attribute-def:schacHomeOrganization
  • 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 stellen door transformation te kiezen. Kies dan bijvoorbeeld Extract en ‘Join()’ om combinaties te maken met van mail en bijvoorbeeld een afdeling. Zie het voorbeeld hieronder.  



Het eindresultaat zal een lijst zijn zoals bijvoorbeeld hieronder:



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:


Je kunt de metadata ook als XML sturen. Klik daarvoor op de link zoals in het screenshot hierboven aangegeven. Realiseer je dat de endpoints dan niet automatisch worden bijgewerkt. Het heeft daarom onze voorkeur een link naar de metadata te ontvangen van je.

Mail de App Federation Metadata-URL of XML naar het SURFconext-team: support@surfconext.nl

Controle SHA-256

SURFconext werkt niet als je SHA-256 niet hebt ingesteld. Dit is de standaard in Azure AD en deze informatie kan zichtbaar gemaakt worden door op het potloodje te klikken in het screenshot hierboven, van het SAML Signing Certificate. Het onderstaande scherm wordt getoond.


Multi Valued Attributen en Extension Attributes

Raadpleeg de handleiding van InSpark.  Hier wordt uitgebreid ingegaan op het aanmaken van Assignedroles en het aanmaken van groepen en assigned roles. Dit geeft je uitgebreidere mogelijkheden dan in het voorbeeld hieronder.

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

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.


NaamWaardeDetail
urn:mace:dir:attribute-def:mailuser.mailActive Directory waarde 'mail'
urn:mace:dir:attribute-def:displayNameuser.displaynameActive Directory waarde 'displayname'
urn:mace:dir:attribute-def:snuser.surnameActive Directory waarde 'sn'
urn:mace:dir:attribute-def:givenNameuser.givennameActive Directory waarde 'givenname'
urn:mace:terena.org:attribute-def:schacHomeOrganizationStatische waarde (tekst)Voor iedere gebruiker altijd hetzelfde. In dit voorbeeld 'rocfriesepoort.nl'.
urn:mace:dir:attribute-def:uiduser.onpremisessamaccountnameActive Directory waarde 'sAMAccountName'
urn:mace:dir:attribute-def:preferredLanguageStatische waarde (tekst)Voor iedere gebruiker altijd hetzelfde. In dit voorbeeld 'NL'.
urn:mace:dir:attribute-def:eduPersonAffiliationuser.extensionattribute1Active Directory waarde 'extensionattribute1' 
urn:mace:dir:attribute-def:eduPersonPrincipalNameuser.userprinciplenameActive Directory waarde 'userPrincipleName'
urn:mace:dir:attribute-def:eduPersonEntitlementJoin ("urn:x-surfnet:universiteitvanharderwijk.nl:afas:personeelsnummer", ":", user.employeeid)In dit voorbeeld worden twee waarden aan elkaar 'geplakt'. Het eerste deel van de string is 'urn:x-surfnet:universiteitvanharderwijk.nl:afas:personeelsnummer' en het tweede deel van de sting is de waarde uit de Active Directory 'employeeid', gescheiden door een dubbele punt ":".
urn:mace:terena.org:attribute-def:schacHomeOrganizationTypeStatische waarde (tekst)Deze waarde is altijd en voor iedere gebruiker urn:mace:terena.org:attribute-def:schacHomeOrganizationType:educationInstitution'


Dit kan er zo uitzien als je het configureert:



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:


Stuur de metadata naar het aansluitteam en test

Het geheel wordt getoond als een vijfstappenplan en eenmaal gereed ziet het er ongeveer uit zoals hieronder aangegeven. Als je deze configuratie wilt gaan testen stuur je een mail naar support@surfconext.nl en wij helpen je op weg. Zorg dat je de URL van de metadata van het Azure Identity Management systeem gereed hebt. Wij zullen de metadata invoeren in SURFconext en doen  noodzakelijke tests. We hebben een dienst beschikbaar die je de mogelijkheid biedt jouw configuratie te testen. Dit stelt je in staat vast te stellen of het aanmelden met SURFconext goed werkt en of SURFconext de attributen goed ontvangt van jouw IdP. Als dat door ons is verwerkt kun je naar deze site gaan om te zien of Azure doet wat hij moet doen https://engine.surfconext.nl/authentication/sp/debug (productie) of https://engine.test.surfconext.nl/authentication/sp/debug (test).


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.


  • No labels