Inleiding
In deze handleiding worden de stappen beschreven die nodig zijn om een koppeling tussen Swing en een door de klant beheerde Microsoft Entra ID te realiseren. Swing biedt de mogelijkheid om zowel de authenticatie als de autorisatie via Microsoft Entra ID in te stellen, waarbij de groepsinformatie van de gebruiker wordt gebruikt om de toegang te bepalen. Indien de klant geen gebruik wil maken van Microsoft Entra ID provisioning, kan ervoor gekozen worden om alleen de authenticatie via Microsoft Entra ID te laten verlopen en de autorisatie binnen Swing zelf te configureren.
Voor Swing versies waar de autorisatie binnen Swing plaats vind moeten de gebruikers ook een account hebben in Swing.
Dit houdt in dat er een gebruikersaccount met dezelfde gebruikersnaam (overeenkomend met het e-mailadres in Microsoft Entra ID in Swing moet bestaan. Hieronder volgen de stappen die de klant moet ondernemen om deze koppeling tot stand te brengen.
Configureer de Microsoft Entra ID tenant
In de eerste stap wordt binnen de Microsoft Entra ID tenant een nieuwe app-registratie aangemaakt:
Geef de applicatie een logische naam: (bijvoorbeeld de url).
Registreer de applicatie.
Er wordt vervolgens een scherm getoond met een aantal id’s. De volgende id’s zijn straks nodig om Swing te configureren: het client-id en het tenant-id.
De volgende stap is het configureren van de omleidings-URL’s. Nadat de gebruiker is ingelogd in Microsoft Entra ID, moet deze worden teruggeleid naar de webapplicatie. Microsoft Entra ID stuurt daarbij informatie mee over de ingelogde gebruiker. Om veiligheidsredenen zal Microsoft Entra ID de gebruiker alleen doorsturen naar een URL die vooraf binnen de app-registratie is geconfigureerd. Klik hiervoor op de overzichtspagina op de link “Een omleidings-URL toevoegen”.
Klik vervolgens op “Een platform toevoegen” en kies “Web”.
Vul de URL in die u van ABF heeft ontvangen en vink “Id-tokens” aan:
De URL is de basis URL van de Swing applicatie + /AADLogin/signin-oidc
Voorbeeld: https://accept-demo.swing.eu/AADLogin/signin-oidc
Klik daarna op “Configure”.
De laatste stap is om toestemming te verlenen aan de organisatie om het gebruikersprofiel te lezen. Ga hiervoor naar "API permissions" en verleen namens uw organisatie toestemming voor de vereiste API-machtigingen. Zie de onderstaande screenshot voor een visuele toelichting.
Nu is de app-registratie compleet en kan Swing geconfigureerd worden. De volgende gegevens zijn nodig:
- De login URL die gebruikers binnen uw organisatie gebruiken om in te loggen in Microsoft Entra ID, bijvoorbeeld: https://login.microsoftonline.com/
- Uw domein, bijvoorbeeld: delft.abf.nl
- Het tenant-id
- Het client-id
In Swing Studio kunnen de Microsoft Entra ID instellingen door de beheerder worden geconfigureerd op de pagina admin/studio/Settings/AuthorizationSettings.
Voorbeeld URL: https://acceptdemo.swing.eu/admin/studio/Settings/AuthorizationSettings
Mocht u hulp nodig hebben dan kan de accountmanager bij ABF of de Swing Helpdesk hier bij helpen. U kunt de bovengenoemde gegevens ook direct naar de Swing Helpdesk (helpdesk@swing.eu) sturen met het verzoek om de configuratie voor u in orde te maken.
Aanvulling: De instelling “Microsoft Entra ID Client Secret” is niet nodig als er geen groepsinformatie worden verstuurd vanuit Microsoft Entra ID, die setting kan bij deze configuratie dus worden genegeerd.
Nadat de instellingen in Swing zijn doorgevoerd, kan er worden ingelogd met Microsoft Entra ID-authenticatie. Binnen Swing zijn er vervolgens twee opties om de autorisatie te regelen.
- De gebruikers die toegang moeten hebben aanmaken in Swing Studio met dezelfde gebruikersnaam als binnen Microsoft Entra ID (= emailadres).
- Alle gebruikers die bekend zijn binnen de Microsoft Entra ID tenant dezelfde rechten geven door een default gebruikersgroep uit Swing hieraan te koppelen.
Een combinatie is ook mogelijk. Zo kan er bijvoorbeeld voor beheerders een account in Swing worden aangemaakt (optie 1), waarmee specifieke beheerrechten kunnen worden toegekend. Overige gebruikers komen dan in de gebruikersgroep “Gebruikers” terecht, met beperkte rechten.
Provisioning op basis van groepsinformatie
Swing kan aanvullend op de authenticatie via Microsft Entra ID ook automatisch rechten toekennen (autorisatie) op basis van de groepsinformatie van de gebruiker. Door gebruik te maken van provisioning is het niet meer nodig om gebruikers aan te maken in Swing. Om dit werkend te krijgen moeten een aantal instellingen van de appregistratie in Microsoft Entra ID worden aangepast. Hieronder zijn de stappen beschreven die moeten worden uitgevoerd door de IT-beheerder van uw organisatie.
Aanpassing van de Microsoft Entra ID tenant
Stap 1
Ga binnen portal.azure.com naar de appregistratie en kies “Token configuration”.
Stap 2
Selecteer “Add groups claim” en de optie “Groups assigned to the application …. “ (zodat alleen de relevante groepsinformatie wordt meegestuurd in de token, wat de veiligheid en performance bevordert.) en kies vervolgens “Add”.
Stap 3
Ga naar “Enterprise applications”, zoek de zojuist bewerkte app registratie op en selecteer deze.
Stap 4
Selecteer de groepen binnen de Active Directory die u wilt gebruiken om autorisaties in te stellen binnen Swing en zorg ervoor dat de juiste personen in deze groepen zijn geselecteerd.
De beheerder van Swing heeft het Object ID van de gebruikte groepen nodig om de autorisatie in te stellen. Klik op de groep om het Object ID te kopiëren (zie onderstaande schermafbeelding). Geef deze informatie door aan de applicatiebeheerder van de Swing omgeving.
Voorbeeld
Beheerders :097f458a-fc8f-480d-a61f-b6aa3b5635bd
Interne gebruikers :c2b2f5ce-0568-4d38-8d3a-0512db474204
Configuratie autorisatie binnen Swing
Vervolgens kan de configuratie van Microsoft Entra ID autorisatie in Swing worden ingesteld:
Deze stappen worden door de Swing beheerder uitgevoerd.
Stap 5
Ga naar Swing Studio en open de tabel “Usergroups”.
Stel de ID’s van de Microsoft Entra ID groepen (kolom: AZUREAD GROUP NAME) in bij de gebruikersgroep. Het volgnummer bepaalt welke groep wordt gebruikt indien een gebruiker aanwezig is in beide groepen. Een lager volgnummer krijgt prioriteit. Plaats beheerdersgroepen bijvoorbeeld boven reguliere gebruikersgroepen.
Stap 6
Publiceer de wijzigingen in Swing Studio en test of alles goed werkt.
Klaar!
Swing gebruikt nu autorisaties van Microsoft Entra ID van uw organisatie. Het is niet meer nodig om gebruikers toe te voegen in de Swing Studio.