Handleiding Entra 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 Entra ID. Entra 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 Entra

Entra ID biedt beperktere ondersteuning voor multivalued attributen dan andere identity management systemen, inclusief sommige Microsoft-producten. Dit kan de functionaliteit van SURFconext beïnvloeden omdat je in SURFconext veelvuldig gebruik maakt van multivalued attributen zoals entitlements, affiliation, mail, etc. Entra ID ondersteunt standaard slechts één multivalued attribuut voor synchronisatie naar externe diensten. Zonder aanvullende maatregelen kan dit leiden tot verminderde functionaliteit bij de overstap naar Entra ID.

Oplossingen en overwegingen

• Azure AD Connect
  • Voor maximale functionaliteit met SURFconext gebruik je Azure AD Connect. Hiermee kunt je alle multivalued attributen synchroniseren zonder beperkingen.  Dit vereist een on-premise component in jouw infrastructuur.
• Assigned Roles
  • Je kunt "User Assigned Roles" gebruiken om één multivalued attribuut aan te bieden aan SURFconext. Hoewel dit beperkt is tot één attribuut, kan dit voldoende zijn voor bepaalde use-cases.
• Heroverweging van attributen
  • Evalueer welke multivalued attributen essentieel zijn voor SURFconext-integratie.
• Alternatieve IdP-oplossingen
  • Als multivalued attributen cruciaal zijn overweeg dan alternatieve IdP-oplossingen die beter ondersteuning bieden voor multivalued attributen.

Zie deze pagina voor achtergrondinformatie hoe multivalued attributen te realiseren door gebruik te maken van Azure AD Connect en Assigned Roles. Voor een goede integratie met SURFconext raden we aan om een inventarisatie te maken van de benodigde multivalued attributen, de impact van Entra ID-beperkingen op huidige en toekomstige use-cases te beoordelen, de haalbaarheid van Azure AD Connect of Assigned Roles te onderzoeken en overleg met ons voor advies op maat. 

Entra ID Tenants

In de Entra Active Directory database zijn gegevens opgedeeld in logische containers per organisatie. Dit zijn tenants. 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 koppeling met SURFconext

Met screenshots wordt het maken van een koppeling tussen Entra ID (Premium P1) en SURFconext beschreven. In de loop van de tijd kunnen schermen 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 ‘Entra 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 ‘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 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 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 Entra ID 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 Entra. 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. 

Entra 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 voor Entra 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 Entra ID Identity Provider met SURFconext volledig te benutten moet in de configuratie 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.

• 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)

Details omtrent de waarden van deze claims kunnen op de website van SURFconext worden gevonden.

Dit ziet er zo uit:

urn:mace:dir:attribute-def:eduPersonEntitlement wordt samengesteld uit een vaste string (String1) en de employeeID (String2) uit Active Directory. 

Een Multi valued attribuut maken met User Assigned Roles. 

Het maken van een multi-valued attribuut kan worden gedaan door rollen toe te wijzen aan gebruikers of groepen. Voor SURFconext zijn dit app-rollen die je toewijst aan groepen of individuele gebruikers. Wanneer een gebruiker lid is van een groep met toegewezen app-rollen, erft de gebruiker automatisch de rollen van die groep. Deze aanpak kan worden gebruikt om een multi-valued attribuut te creëren en door te geven aan SURFconext. In dit attribuut worden zowel de directe rollen van de gebruiker als de rollen die via groepslidmaatschappen worden toegekend, gecombineerd. Op deze manier kun je alle rechten of eigenschappen van een gebruiker doorgeven in één multi-valued attribuut. 

Samengevat doe je het volgende:

• Maak een app role aan bij de 'app registration' van SURFconext. Bijvoorbeeld "Toegang SURFdrive" met als waarde "urn:x-surfnet:surf.nl:surfdrive:quota:100"
• Ken gebruikers of groepen toe aan de app-roles voor SURFconext onder Enterprise Applications. 
• Ken de User.assignedroles toe aan een attribuut. Bijvoorbeeld eduPersonEntitlement.
• Test het attribuut op onze debugpagina (test, productie). 

Dit is in meer detail uitgewerkt op pagina Achtergrondinformatie over Multivalued Attributen in Entra ID. 

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 Entra 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 Entra ID 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 Entra Pass Through Authentication en Seamless Sign On. Zie https://docs.microsoft.com/en-us/Entra/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 (Entra ID 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 Entra. 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 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.