Handleiding Azure AD als SAML Identity Provider in SURFconext

Inleiding

In deze handleiding lees je hoe je jouw organisatie kunt aansluiten op SURFconext als Identity Provider met behulp van Microsoft Azure AD. Azure is voortdurend in ontwikkeling. Als je opmerkingen of aanvullingen hebt ontvangen we die graag op support@surfconext.nl. De volgende onderwerpen worden uitgelicht:

De beperkingen van Azure

Als nog je voor de keuze staat om Azure of iets anders als SAML Identity Provider in te zetten is het verstandig de beperkingen van Azure aangaande Multi Valued attributen in acht te nemen. Dit is in SURFconext een veel gebruikte techniek. Azure is hier minder flexibel in dan andere identity management systemen. Dit geldt ook ten opzichte van bestaande producten van Microsoft. Zie deze pagina voor achtergrondinformatie hoe multivalued attributen te realiseren door gebruik te maken van Azure AD Connect. Hier vind je richtlijnen hoe hier zo goed mogelijk mee om te gaan alsook de beperkingen. Wij doen onderzoek naar multi-valued attributes bij gebruik van Azure AD om de functionaliteit van SURFconext ten volle te benutten. Nu is het zo dat slechts 1 attribuut in Azure multi-valued kan zijn. Houd hier rekening mee bij het opzetten van een IdP als je gebruik maakt of wilt gaan maken van Azure. SURFconext heeft meerdere attributen hebben die multivalued kunnen zijn: Entitlements, Affiliation, Mail, etc. Het kan dus zijn dat je functionaliteit gaat inleveren bij het gebruik van SURFconext als je overstapt naar Azure AD en hier in je huidige IdM en SURconext gebruik van maakt.

Azure AD Tenants

In de Azure Active Directory database zijn gegevens opgedeeld in logische containers per organisatie. Dit heten tenants in Azure. Jouw organisatie heeft toegang tot de jullie eigen tenant en niet tot de tenants van andere organisaties, hoewel alle gegevens in dezelfde database staan. Elk tenant, elk object, elke rol, enzovoorts, heeft een unieke identificatie code, een GUID. Onder water wordt hier alles aan gerelateerd, zodat in principe alle gegevens, zoals de naam kunnen wijzigen, maar de juiste informatie bij de juiste organisatie wordt opgeslagen.

Configuratie Azure AD koppeling met SURFconext

Met 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. Voel je vrij om contact met ons op te nemen op support@surfconext.nl als je vragen hebt. Een 'Active Directory' stelt je in staat om het beleid (rechten en instellingen) in het netwerk van jouw organisatie te beheren en daarmee dus ook de toegang tot SURFconext. Dit gaan we gebruiken om de toegang tot diensten via SURFconext mogelijk te maken. Log in op https://portal.azure.com en ga naar ‘Azure Active Directory’. 

Klik vervolgens onder Manage op Enterprise applications.

SURFconext is in deze omgeving een 'applicatie'. Deze gaan we aanmaken. Klik op ‘New application’ of ga naar de applicatie die je wilt wijzigen als je al een applicatie voor SURFconext hebt aangemaakt. 

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 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’. Dit definieert hoe de SAML-koppeling met SURFconext werkt. 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. Daarna kan in de verbinding met SURFconext worden getest.

De metadata van SURFconext instellen

Voer de gegevens in die je vindt op de metadata pagina van SURFconext. Je hebt de metadata nodig die je vindt onder SURFconext als SP Proxy. Vink in Azure de ‘Show advanced URL settings' aan:

• Identifier (Dit is het entityID van SURFconext): https://engine.surfconext.nl/authentication/sp/metadata
  • Note: Dit is NIET de locatie van de metadata maar enkel en alleen de entityID van het SP end-point van SURFconext
• Reply URL (AssertionConsumerService:Location URL in de metadata): https://engine.surfconext.nl/authentication/sp/consume-assertion
• Sign on URL (engine debugpagina om de authenticatie te testen): https://engine.surfconext.nl/authentication/sp/debug

Beheren van Claims (ofwel attributen)

In deze stap worden de SAML Attributen voor de koppeling met SURFconext 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. Vul in het veld 'Name' de waarden in zoals je vindt op onze pagina over attributen. Kopieer en plak deze waarde van onze wiki, SURFconext is case senstitive! De ingevulde waarden moeten exact hetzelfde zijn. Geef in ieder geval 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 in het veld name zoals je vindt op onze pagina over attributen met  '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.

Hoe verwarrend ook, het veld 'Namespace' laten we leeg. 

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 een '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. Deze link is te vinden in het veld SAML Signing Certificate in jouw Singe sign-on configuratie van Azure. 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 van jouw IdP te ontvangen.

Controleer je configuratie zelf: Errors, Warnings en groene vinkjes

Zodra wij de metadata hebben ontvangen gaan we jouw IdP opvoeren op onze test of productieomgeving. Je kunt dan de attributen die je hebt gedefinieerd controleren. We hebben daar een debug-pagina voor op test en op productie:

• https://engine.surfconext.nl/authentication/sp/debug (Productie)
• https://engine.test.surfconext.nl/authentication/sp/debug (Test)

Als je de bevestiging hebt ontvangen dat jouw IdP is opgevoerd kun je naar bovenstaande pagina's navigeren en jouw IdP selecteren in de WAYF (Het 'Were Are You From' scherm). Deze website kan je helpen fouten weg te werken. Als er een noodzakelijk attribuut ontbreekt, wordt dit aangegeven: 'Some attributes failed validation'. Warnings hoeven niet perse een probleem te zijn. Kijk op onze attributen pagina om meer te weten over de fouten die je ziet. 

Azure zal bepaalde waarden altijd doorgeven waarop SURFconext een waarschuwing geeft: ' http://schemas.microsoft.com/identity/claims/identityprovider is not known in the schema'. Werk ze zo veel mogelijk weg. SURFconext 'dropped' wat over blijft en deze kun je negeren. 

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

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 kan er zo bijvoorbeeld 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:

User Assigned Roles: Een Multi valued attribuut aanmaken

Zoals aangegeven kun je één attribuut naar SURFconext vanuit Azure AD multivalued maken. Dit doe je door gebruik te maken van User Assigned Roles.  Ga daarvoor naar Azure AD, en klik op “App registrations” onder het kopje “Manage”. Mocht de App Registration (met dezelfde naam als de Enterprise Application) niet voorkomen in de lijst, klik dan op “All applications”. Vervolgens klik je op “App roles” onder het kopje “Manage” om "roles" to te voegen. Als voorbeeld gaan we de roles voor eduPersonAffiliation aanmaken. Zie hieronder een voorbeeld wat je voor eduPeronAffiliation kan toevoegen (iemand kan in dienst zijn als werknemer, een studie zijn en nog een lid ergens van zijn) :

Description is voor eigen gebruik en mag een voor jou handige omschrijving hebben. 

Als je nu terug gaat naar de enterprise application, kun je deze rolens koppelen aan een gebruiker en aan een claim toevoegen. Klik op “User and groups” onder het kopje “Manage”. Hier voeg je alle rollen die je net hebt aangemaakt toe, die je wilt voor deze gebruiker. Klik op Add user/group, en kies een gebruiker uit de Azure AD en een van de rollen die van toepassing zijn.

User Assigned roles aan SAML attribuut koppelen

Nu we de rollen hebben gekoppeld aan de gebruiker, kunnen we de bouw van het attribuut voltooien. Ga naar de Enterprise Application, en klik op “Single sign-on”. Klik vervolgens op “Edit”.  Hier vul je de claims in zoals beschreven staat op de wiki van SURF, in dit voorbeeld eduPersonAffiliation. Voor eduPersonAffiliation vul je dan in: 

Als het goed is zie je op de debug pagina van SURFconext de rollen als multivalued attributen worden meegegeven met eduPersonEntitlement. Wil je meerdere attributen die multivalued zijn, lees dan dit artikel over Azure AD Connect.

Rond het Stappenplan af

Het geheel wordt getoond als een vijfstappenplan en eenmaal gereed ziet het er ongeveer uit zoals hieronder aangegeven. 

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 alles 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, TokenLifetimePolicy of wel de Sign-in Frequency

Een verkeerd ingestelde sessieduur 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 sessieduur een halve werkdag, 4 uur, of een werkdag aanhouden; 8 uur tot 12 uur. De daaropvolgende dag zal de gebruiker weer een prompt krijgen aan te melden. Zie voor meer informatie de support pagina van Microsoft hoe de aanmeldfrequentie in te stellen. Om veiligheidsoverwegingen raden wij het configureren van een permanente browser sessie af.