Entra ID (Authenticatie en M365)

Dit artikel bevat de volgende secties:

• Algemeen
• App-registratie configureren
  • Nieuwe app-registratie aanmaken
  • Machtigingen verlenen
  • Id-tokens selecteren
  • Redirect URI's instellen
  • Consent instellen
• Benodigde gegevens voor configuratie inlogkoppeling 
  • Authority: TenantID
  • Secret aanmaken
• Geavanceerde configuraties
  • Toegang beperken tot bepaalde Entra ID-groepen
  • M365 gebruikers uitsluiten van toegang tot "public" sharepointsites
• Troubleshooting
  • Verkeerde tenant
  • Crypto errors
  • MsalUiRequiredException
  • Foutmelding over niet genoeg rechten
  • Machtigingen verlenen voor de Suite
  • Uitleg over rechten
  • Foutmelding: the term 'az' is not recognized

Algemeen

Voor integraties met Microsoft 365 moet de authenticatie geconfigureerd worden. Microsoft 365 maakt hiervoor gebruik van Microsoft Entra ID. 

Het is dus ook mogelijk om klanten die geen Microsoft 365 hebben maar wel een Microsoft Entra ID hebben via onderstaande procedure te laten inloggen in Embrace.

In dit document wordt er vanuit gegaan dat de organisatie al Microsoft 365 / Microsoft Entra ID heeft en dat de organisatie al authenticatie hiermee geregeld heeft. Zo niet dan is het goed als de organisatie dit eerst regelt, eventueel met behulp van een Microsoft 365 specialist. Microsoft 365 kent 3 varianten van authenticatie welke hier beschreven staan: https://blogs.office.com/en-us/2014/05/13/choosing-a-sign-in-model-for-office-365/. Deze drie varianten worden allemaal ondersteund door Embrace.

Vervolgens kan Embrace geconfigureerd worden. Embrace kent de volgende 2 opties:

• Optie 1: Embrace configureren zodat gebruikers met hun Microsoft 365 account in Embrace kunnen inloggen.
• Optie 2: Embrace configureren zodat gebruikers met een ander account kunnen inloggen (Embrace Forms, AD, ADFS, etc) en eenmalig hun Microsoft 365 account kunnen koppelen aan hun gebruikersprofiel

Voor beide opties moet in Azure een app-toepassing gemaakt worden. Dit document beschrijft de acties die de klant moet doen om een app-toepassing te maken.

App-registratie configureren

Nieuwe app-registratie aanmaken

• Ga naar https://portal.azure.com of https://aad.portal.azure.com en log in.
• Ga naar "Microsoft Entra ID" en dan naar "App registrations"

• Je krijgt nu een overzicht van registraties en kan een nieuwe registratie toevoegen:

  

• Kies voor "Nieuwe registratie"
• Vul de volgende velden in:
  - Name: voer een omschrijvende naam in voor de app-registratie, bv Embrace intranet of naam intranet.
  - Supported account types: selecteer de optie " Accounts in this organizational directory only (Embrace Facilities B.V. (Office) only - Single tenant)" 
  - Redirect URI: Selecteer de optie --> Web
  Voer een aanmeldingsurl in. Deze aanmeldingsurl moet er als volgt uit zien:  
  https://auth.embracecloud.nl/auth/realms/[organisatienaam]*/broker/employees/endpoint  
• Hiermee wordt ook de OAuth callback url gezet. Zie ook verderop bij callback urls over hoe je deze eventueel later kan wijzigen of uitbreiden.

• Klik op Register.
  De nieuwe app-registratie wordt getoond. Uit het scherm dat nu verschijnt kan de clientId (toepassings-id) achterhaald worden dat aan Embrace doorgegeven moet worden.

  

* Voor de organisatienaam gebruiken wij het domein van jullie organisatie. Deze vind je bijvoorbeeld in de e-mailadressen achter het @. Bijvoorbeeld: het domein van Embrace is embracecloud, zie ook onze e-mailadressen: ...@embracecloud.nl.

Machtigingen verlenen

Voor elke API call die Embrace gebruikt stel je de juiste machtigingen in. Hieronder lees je welke machtigingen nodig zijn. In de toekomst kunnen hier extra machtigingen bij komen. Lees waarom Embrace deze rechten nodig heeft aan het einde van dit document.

In API-machtigingen stel je de machtigingen voor Embrace in. Hier staat al een standaard machtiging. Deze mag je niet verwijderen. Afhankelijk van de gewenste integraties voeg je hier één of meer extra machtigingen toe.

Application permissions

Hieronder staan alleen de application permissions die Embrace nodig heeft binnen de Microsoft Entra ID app registration. Per permission lees je welke functionaliteit hiermee mogelijk is en wat er niet werkt als deze ontbreekt.

Extra permissions maken extra functionaliteit mogelijk. Als een permission aanwezig is, gebruikt Embrace de bijbehorende functionaliteit volledig. Ontbreekt een permission, dan wordt de functionaliteit beperkt uitgevoerd of probeert het systeem terug te vallen op een delegated permission.

Alle permissions volgen het principle of least privilege. Voor elke functionaliteit vraagt Embrace alleen de minimaal noodzakelijke rechten.

Groepen & lidmaatschappen beheren

Uitleg van deze permissies:

Directory.Read.All

Maakt health checks en validatie van permissions mogelijk voor Microsoft 365 integraties. Zonder deze permission kan Embrace niet controleren of de vereiste permissions correct zijn ingesteld op de app registration. Hierdoor kunnen bepaalde Microsoft 365 integraties mogelijk niet correct worden geactiveerd of gediagnosticeerd in het beheerportaal.

Group.Read.All

Vereist om Graph webhook subscriptions te maken voor resources die met groepen te maken hebben. Hiermee blijven groepslidmaatschappen en wijzigingen in groepen in Azure Entra ID gesynchroniseerd met Social. Bron

Opmerking: Group.ReadWrite.All is een superset van Group.Read.All. Als Group.ReadWrite.All al is toegekend, hoeft deze permission niet afzonderlijk te worden toegevoegd.

Zonder een van deze permissions: wijzigingen in groepslidmaatschappen in Entra ID worden niet automatisch gesynchroniseerd met Social.

GroupMember.ReadWrite.All

Maakt het mogelijk om leden direct toe te voegen aan of te verwijderen uit Microsoft 365 Groups, zonder dat de bredere Group.ReadWrite.All permission nodig is. Dit is vooral nuttig wanneer alleen lidmaatschappen beheerd hoeven te worden en het aanmaken van groepen of het beheren van eigenaren niet nodig is.

Zonder deze permission: leden die aan groepen in Social worden toegevoegd, worden niet automatisch toegevoegd aan de gekoppelde Entra-groep.

Group.ReadWrite.All

• Maakt het mogelijk om Microsoft 365 Groups te maken en bij te werken wanneer gebruikers in Azure Entra ID beperkt zijn in het zelf aanmaken van groepen. Dit wordt gebruikt via de Microsoft 365 groups-integratie-instelling Use Service Principal account to create groups.
• Wanneer een gebruiker in Embrace als eigenaar aan een groep wordt toegevoegd, wordt deze gebruiker ook als eigenaar toegevoegd aan de groep in Azure Entra ID.
• Deze permission bevat ook Group.Read.All en GroupMember.ReadWrite.All en dekt daarmee zowel de webhook subscription als het directe beheer van groepslidmaatschappen.

Zonder deze permission: Microsoft 365 Groups kunnen alleen door eindgebruikers zelf in Entra worden aangemaakt (afhankelijk van de tenant-instellingen). Embrace kan in dat geval geen groepen namens gebruikers aanmaken.

Gastgebruikers uitnodigen / bewerken

Uitleg van deze permissies:

User.Invite.All

Wordt gebruikt om gastgebruikers uit te nodigen in Microsoft Entra ID via de applicatiecontext (system context). Bron

Zonder deze permission: Het systeem valt terug op de delegated permission User.Invite.All. In dat geval worden uitnodigingen verzonden namens de ingelogde gebruiker in plaats van namens de applicatie. 
Dit kan onderhevig zijn aan extra beperkingen afhankelijk van de tenant-configuratie.

User.ReadWrite.All

Microsoft Graph staat niet toe om givenName of surname direct in de invitation payload te zetten. Om deze velden na een uitnodiging toch te vullen, voert het systeem een tweede API call uit. Bron

Zonder deze permission: Het systeem valt terug op de delegated permission User.ReadWrite.All. Toegang via delegated permissions kan nog steeds beperkt zijn afhankelijk van de configuratie in het Azure Entra portal. In dat geval worden voornaam en achternaam na de uitnodiging niet automatisch ingesteld.

Delegated permissions

Naast application permissions gebruikt Embrace ook delegated permissions. In de tabel hieronder zie je welke permissions nodig zijn per functionaliteit.

• Klik op Een machtiging toevoegen om machtigingen bij te werken.
• Je kunt instellen of iedere gebruiker tijdens het inloggen eenmalig toestemming geeft voor de Embrace Microsoft 365 integratie, of dat een administrator dit namens alle gebruikers doet. Lees meer over toestemming onder Consent.

Id-tokens selecteren

• Ga naar "Authentication" en vink Id-tokens aan onder "Implicit grant and hybrid flows". Sla de wijziging op.
  

Redirect URIs

• Ga naar >Manage >Authentication >Platform configurations >Redirect URI's.
  Voeg naast de reeds aangemaakte redirect URI nog twee redirect URI's toe:
  • https://socialprovider-embracecloud.embracecloud.nl
  • https://socialprovider-embracecloud.embracecloud.nl/OAuth/Azure 

Consent

De eerste keer dat een gebruiker inlogt moet hij toestemming geven voor de machtigingen die de appregistratie nodig heeft. Dit scherm ziet er bijvoorbeeld als volgt uit:

Naar mate Embrace meer integraties doet met Office 365 zal er ook meer machtigingen nodig zijn en kan deze lijst best lang worden:

Dit kan tot verwarring en vragen leiden bij gebruikers. Om dit te voorkomen kan een administrator van Azure namens alle gebruikers dit consent geven en zal dit scherm niet getoond worden.

• Klik API Permissions en klik op " Grant admin consent for..." 

Benodigde gegevens voor configuratie inlogkoppeling

Authority: tenantID

Voor de koppeling heeft Embrace de Authority nodig. Deze ziet er als volgt uit: https://login.windows.net/[tennantid]. De tennantid is te achterhalen door te klikken op overzicht en dan Directory-Id(tenant-id).

Secret aanmaken

• Ga naar "Certificates & secrets" en kies "new client secret".

• Vul een beschrijving in en kies een geldigheid. Mocht je een beperkte geldigheid kiezen, noteer dan ergens dat er tijdig een nieuwe sleutel wordt aangemaakt en geconfigureerd.

  

• Kies opslaan en de sleutel (waarde) die nu verschijnt moet samen met de ClientID van de app-registratie en de tenantID doorgegeven worden aan Embrace.

Geavanceerde configuraties

Toegang beperken tot bepaalde Entra ID-groepen

Standaard kan elke Entra ID gebruiker (ook guest accounts) via de Entra ID-koppeling inloggen op Embrace. Binnen Embrace is geen beperking mogelijk op specifieke (groepen van) gebruikers. Dit dient binnen de identity provider (in dit geval Entra ID) ingericht te worden. Microsoft heeft meerdere resources beschikbaar hoe je dit binnen Entra ID kunt inregelen:

• How to: Restrict a Microsoft Entra app to a set of users

M365 gebruikers uitsluiten van toegang tot "public" sharepointsites

Standaard heeft een gebruiker met M365-rechten en bijbehorende licentie, rechten op alle open Sharepoint groepen. Dit kan ongewenst zijn. Denk bijvoorbeeld aan raadsleden die wel een M365-licentie hebben (voor het gebruik van Office en OneDrive). Via OneDrive krijgen deze gebruikers dan toegang tot documenten in alle open groepen, want dat is de standaard instelling van Sharepoint. Onderstaande blog legt uit hoe je dit kunt beperken:

• https://www.thijoubert.com/2021-09/SharePoint-Prevent-Contractor-Access-Public-Files/

Troubleshooting

Verkeerde tenant

Als authenticatie geconfigureerd is dan is dat voor één specifieke Office 365 omgeving / tenant. Alleen gebruikers in die tenant kunnen dan inloggen. Veel gebruikers hebben echter meerdere Office 365 accounts en soms zelf meerdere met hetzelfde email adres. Als tijdens het inloggen gevraagd wordt of het een "werk / school" of "persoonlijk" account betreft dan moet de gebruiker altijd "werk / school" antwoorden. Dit scherm ziet er als volgt uit:

Mocht een gebruiker met een Office 365 account inloggen dat niet onderdeel is van de geconfigureerde tenant of gekozen heeft voor persoonlijk account dan verschijnt de volgende foutmelding:

Hierin staan 3 velden omcirkeld die van belang zijn om het probleem te indentificeren:

• Emailadres dit is het account waarmee de gebruiker probeert in te loggen
• Live.com het account waar de gebruiker mee probeert in te loggen is onderdeel van deze tenant (in dit voorbeeld dus een privé account en geen zakelijk account)
• Malengo dit is de tenant die geconfigureerd is en alleen accounts uit deze tenant zijn toegestaan.

Er is een hoop verwarring bij gebruikers over Office 365 accounts. Voor meer leesvoer zie:

http://www.brucebnews.com/2016/06/finding-your-way-through-microsofts-maze-of-work-and-personal-accounts/

http://www.brucebnews.com/2016/09/microsoft-starts-to-untangle-microsoft-accounts-and-office-365-business-accounts/

Crypto errors

Zoals eerder vermeld is worden de OAuth tokens ge-encrypt met de machine key. Ook de Azure configuratie in omgevingsbeheer wordt op deze manier ge-encrypt.

Mocht dus de machinekey wijzigen dan kunnen alle OAuth tokens niet meer ge-decrypt worden. Tevens zal de omgevingsbeheer configuratie van Azure niet meer ge-decrypt kunnen worden.

In de logfile van Embrace zal dan dit soort informatie gelogd worden:

• Error decrypting Azure OAuth token
• System.Security.Cryptography.CryptographicException: Error occurred during a cryptographic operation

De gebruikers zullen dan of opnieuw moeten inloggen of opnieuw handmatig de koppeling leggen (afhankelijk van welke van de twee authenticatie methodes in gebruik is, zie begin dit document). En de configuratie in omgevingsbeheer moet opnieuw ingevoerd worden (afhankelijk van welke van de twee authenticatie methodes in gebruik is, zie begin dit document).

Hetzelfde geldt wanneer de Embrace website verhuist naar een andere webserver.

MsalUiRequiredException

De gebruiker krijg een foutscherm tijdens het inloggen en deze foutmelding verschijnt in de logfiles:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '00000003-0000-0000-c000-000000000000'.

Als deze melding verschijnt dat betekent dit dat de authenticatie eisen die gesteld worden aan Embrace anders zijn dan die gesteld worden aan Office 365. Aangezien Embrace gegevens uit Office 365 toont vereist Microsoft dat Embrace hetzelfde nivo van beveiliging heeft als Office 365 (Outlook widget, MS teams status, Office 365 1-op-1 kopeling, etc).

Dus als voor Office 365 MFA vereist is dan moet dit ook aan staan voor Embrace. Of als Office 365 alleen vanaf bepaalde devices of locaties gebruikt mag worden dan moet dit ook aan staan voor Embrace.

Dus als een gebruiker naar https://embrace.klant.nl gaat dan moet hij dezelfde authenticatie eisen hebben als wanneer hij bijvoorbeeld naar https://klant.sharepoint.com gaat. 

Foutmelding over niet genoeg rechten

Controleer of de machtigingen in de app registratie goed gezet zijn en pas deze indien nodig aan. Na het aanpassen van de rechten moeten gebruikers opnieuw inloggen voordat dit effect heeft.

Machtigingen verlenen voor de Suite

• Calendars.Read
• Calendars.Read.Shared 
• Mail.Read
• Presence.Read.All
• Tasks.ReadWrite
• User.Read

Uitleg over rechten

Embrace heeft diverse rechten nodig voor de Graph API van Microsoft. In documentatie van Microsoft staat vaak uitgelegd welke rechten nodig zijn voor welke Graph API call, zie bijvoorbeeld: https://docs.microsoft.com/en-us/graph/api/directoryrole-list?view=graph-rest-1.0&tabs=http. Soms lijkt het misschien onlogisch als Embrace zowel Files.ReadWrite als Files.ReadWrite.All nodig heeft. De reden dat we hiervoor gekozen hebben is omdat dit zo in de documentatie van Microsoft staat en we voor de zekerheid ons daar aanhouden.

Office 365 maakt onderscheid in delegated en application rechten. Bij delegated worden Graph API calls aangeroepen met de rechten (OAuth token) van de huidige gebruiker. Bij application wordt de app registratie van Embrace gebruikt om de API call aan te roepen. Delegated heeft de voorkeur omdat hiermee voorkomen wordt dan een gebruiker per ongeluk meer te zien krijgt dan waar hij rechten op heeft. Dit lukt echter niet altijd. Bijvoorbeeld soms moet Embrace zaken uitvoeren zonder dat er een gebruiker bekend is, bijvoorbeeld bij scheduled jobs voor een sync of iets dergelijks.

In onderstaande tabel staat een korte uitleg van de rechten die nodig zijn voor de integratie met Embrace.

Foutmelding: the term 'az' is not recognized

az : the term 'az' is not recognized as the name of a cmdlet, function, script file, or operatable program. CHeck the spelling of the name, or if a path was included, verify that path is correct and try again. 

Het script maakt gebruik van de AZ-module binnen Powershell. Die module dient geinstalleerd te zijn op de computer waar het powershell-script uitgevoerd wordt. Installeer Azure Az via: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-windows?view=azure-cli-latest