AllSolutions biedt een koppeling met Microsoft Exchange, waarbij het mogelijk is om Contactpersonen (relaties), Taken (acties) en Agenda (afspraken) te synchroniseren met MS Outlook. De koppeling vindt tot nu toe plaats via Basic Authentication op basis van een gebruikersnaam en wachtwoord. Deze methode is eenvoudig in het gebruik, maar wordt tegenwoordig als minder veilig beschouwd. Daarbij heeft Microsoft intussen aangekondigd per 1 oktober 2022 Basic Authentication te deactiveren.
Daarom is het (vanaf versie 22.0.10) mogelijk om de koppeling met Microsoft 365 (online-versie) in te richten op basis van ‘OAuth 2.0’. Deze methode gebruikt de OAuth 2.0 Authorization Code Flow om op een veilige manier, via access en refresh tokens, toegang te krijgen tot het mailaccount.
In dit artikel wordt uitgelegd hoe je kunt overstappen naar de nieuwe methode. We raden aan om de omzetting eerst te testen in je acceptatieomgeving, voordat je dit in je productieomgeving gaat doorvoeren.
LET OP! Omdat de OAuth2.0 authenticatie flow veiliger is dan Basic Authentication, is het belangrijk dat gebruikers in EWS/Azure Active Directory op dezelfde manier zijn opgezet als in AllSolutions!
Het gaat hier om het veld Exchange account in de functie Gebruikers (MGEBRU). Deze bevat het user account van de gebruiker bij EWS. Vaak zijn de UPN en het e-mailadres gelijk aan elkaar, maar dit hoeft niet. Voor meer informatie hierover, neem contact op met je beheerder. Voor het werken van de koppeling via OAuth2.0 moet dit veld dit altijd de User Principal Name (UPN) van de gebruiker bevatten.
Als in AllSolutios bij de gebruiker in het veld Exchange account geen geldige UPN is ingevuld, zal EWS dit melden. Vanuit AllSolutions wordt de synchronisatie van EWS-items voor deze gebruiker dan gestopt. Let op! Je ontvangt hiervan géén melding. Wel kun je dit controleren door bijvoorbeeld in de functie Afspraken (MAFSPR) te zoeken naar afspraken zonder Synchronisatie id (kp01.sync-id).
Stappenplan
In het kort bestaat dit uit het aanmaken van AllSolutions als ‘app’ op het Microsoft platform, het overnemen van de gegenereerde informatie in AllSolutions en het autoriseren van de app. De gegevens van het account dat wordt gebruikt, vindt je in de Parameters AllSolutions (MZZPAR) in het onderdeel Exchange Webservice.
OAuth authentication wordt alleen ondersteund in combinatie met Secure IMAP via poort 993. Controleer daarom of voor het betreffende mailaccount toegang via IMAP is toegestaan. Is dit (nog) niet het geval, zorg er dan voor dat je dit eerst mogelijk maakt voordat je het onderstaande stappenplan gaat volgen.
1. AllSolutions registreren als ‘app’ in Microsoft Azure Active Directory
De eerste stap is het registreren van AllSolutions als ‘application’ (oftewel ‘app’) binnen Microsoft Azure (single tenant). Hoe dit werkt, wordt uitgelegd op deze pagina van Microsoft: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
Maak per AllSolutions-omgeving een aparte ‘app’ aan, dus één voor de productieomgeving en eventueel één voor de acceptatieomgeving (als je daar ook de koppeling met Exchange wilt kunnen testen).
Geef de ‘app’ een naam, bijvoorbeeld AllSolutions Exchange synchronisatie (acceptatie) en AllSolutions Exchange synchronisatie (productie).
Gebruik als Redirect URL ‘https://[domein].[tld]/jsonhandler.ashx‘, waarbij je op de plaats van [domein].[tld] de URL van de AllSolutions-omgeving invult. Microsoft gebruikt deze URL straks om de respons op het authenticatie verzoek naartoe te sturen.
De app hoeft overigens geen autorisaties te hebben. Deze worden later in het process bij het ‘authorization request’ aangevraagd (zie stap 4).
Na het registreren van de ‘app’ heb je de volgende gegevens nodig voor de verdere inrichting straks in AllSolutions:
- Application (client) ID
- OAuth 2.0 authorization endpoint
- OAuth 2.0 token endpoint
- Redirect URL
Let hierbij op dat je voor zowel de authorization endpoint, als het token endpoint de v2-versie gebruikt!
Aandachtspunt voor Multi-factor authentication (MFA)
Is op het mailaccount Multi-factor authentication (MFA) ingericht? Dan kan het nodig zijn om voor de app een Azure Conditional Access Policy aan te maken of bij te werken, waarbij een uitzondering voor de app of app-gebruiker wordt gemaakt.
2. Genereer een ‘Client Secret’ in Azure
Genereer binnen Microsoft Azure via Certificates & secrets een Client Secret. (AllSolutions ondersteunt alleen het gebruik van een client secret als authenticatie.) Hierbij geef je tegelijkertijd op hoe lang deze ‘client secret’ geldig is. Kies een korte levensduur voor een veilige verbinding of een langere levensduur voor meer gemak. Houd er wel rekening mee dat er geen toegang tot de mailaccounts kan worden verkregen zodra de client secret code is verlopen!
Kopieer de value (!) van de client secret en noteer deze even op een veilige plek voordat je het scherm sluit. Zodra je de pagina verlaat, wordt de client secret namelijk voor altijd verborgen. De enige oplossing is dan het genereren van een nieuwe client secret-code.
Het is voor AllSolutions niet mogelijk de levensduur van een client secret te weten te komen. Houdt dus zelf goed in de gaten wanneer deze verloopt! Zie ook Aanvullende informatie en onderhoud.
3. Interface informatie registreren in AllSolutions
Met de gegevens uit stap 1 en 2 kun je de instellingen in AllSolutions inrichten op basis OAuth 2.0. Hiervoor ga je naar de functie Importlocaties Documenten (MILSCN). Voeg een nieuw record toe van het importtype ‘EWS‘ (Exchange Web Services):
Vul in de volgende velden de gegevens in die je in Microsoft Azure hebt verkregen:
- Application (client) ID
- Client secret
- OAuth 2.0 authorization endpoint
- OAuth 2.0 token endpoint
Redirect URL: Vul hier https://[domein].[tld]/jsonhandler.ashx in, waarbij je op de plaats van [domein].[tld] de URL van de AllSolutions-omgeving invult. Deze waarde heb je eerder bij stap 1 ook ingevuld bij het aanmaken van de app in Microsoft Azure. Microsoft gebruikt deze URL om de respons op het authenticatie verzoek naartoe te sturen.
Let op dat je hier in AllSolutions exact dezelfde waarde invult als je in Azure hebt gedaan! Anders zal de koppeling straks niet werken.
Sla de gegevens op via Opslaan + Overzicht.
Goed om te weten: Ook als een client secret nog niet is verlopen, kun je deze vervangen door een nieuwe code. Dit doe je door simpelweg een nieuwe client secret te genereren in Azure (zie stap 2) en deze waarde bij de bijbehorende importlocatie (MILSCN) in AllSolutions in te voeren. Het opnieuw autoriseren van de app is hierbij niet nodig.
Start vanuit je gebruikersnaam rechtsboven in het scherm een extra sessie. Start hier de functie Parameters AllSolutions (MZZPAR) en ga naar het onderdeel Exchange Webservice. Noteer allereerst de gebruiker en het wachtwoord die tot nu toe werden gebruikt om in te loggen via Basic Authentication. Deze heb je straks in stap 4 nodig om de AllSolutions ‘app’ te autoriseren.
- Zet het veld Authentication method om naar OAuth 2.0.
- Selecteer bij het veld Interface voor EWS via de i-button de EWS-importlocatie (MILSCN) die je zojuist hebt aangemaakt.
- Sla de gegevens op.
4. AllSolutions ‘app’ autoriseren
In deze stap vraag je voor AllSolutions (als ‘app’ binnen Microsoft Azure) een authorization code aan. Ga hiervoor terug naar je tabblad met de functie Importlocaties Documenten (MILSCN) en klik het overzicht open van de EWS-locatie die je in stap 3 hebt aangemaakt.
Klik met je rechtermuisknop op de URL in het veld Request an authorization code en kies voor Link openen in incognitovenster. Dit opent een nieuwe browser waarin Microsoft om toestemming vraagt.
Belangrijk! Log hier in met de gebruiker en het wachtwoord die je in stap 3 vanuit de Parameters AllSolutions (MZZPAR) hebt genoteerd! Zorg er voor dat dit account ook voldoende rechten heeft om het toegangsverzoek te mogen goedkeuren. De instelling voor het verlenen van toegang wordt aangestuurd via Enterprise applications > Consent and permissions in Azure.
Belangrijk! Log alléén in met de gebruiker en het wachtwoord dat in de parameters AllSolutions is geregistreerd, om het toegangsverzoek te beoordelen. Als je dit met een ander account uitvoert, zal de koppeling met Exchange NIET gaan werken!
Controleer in het toegangsverzoek:
- De zelf opgegeven naam van de app
- De gevraagde rechten
Hieronder een voorbeeld van het toegangsverzoek waarbij op de geel gearceerde plaats de naam komt te staan, die je in Microsoft Azure aan de app hebt meegegeven.
Zie je hier geen mogelijkheid tot ‘accepteren’ staan, dan heeft de app in eerste instantie geen rechten om het verzoek te autoriseren. Klik in dit geval op de button om toestemming aan de systeembeheerder te vragen. Nadat de systeembeheerder toegang heeft verleend, volg je dezelfde stappen nog een keer om de app te autoriseren. Als het goed is, moet je dan wel de mogelijkheid om te accepteren (zoals in het voorbeeld hierboven) zien staan.
De volgende rechten of scopes worden gebruikt:
- De offline access scope is nodig om nieuwe acces-tokens aan te vragen zonder tussenkomst van de gebruiker. Zie ook Microsoft identity platform scopes, permissions, & consent.
- https://outlook.office.com/IMAP.AccessAsUser.All is nodig voor toegang om de mailbox uit te lezen. Zie ook Authenticate an IMAP, POP or SMTP connection using OAuth
Na het accepteren van het toegangsverzoek, wordt je door Microsoft doorgestuurd naar de opgegeven Redirect URL (in je browser toont dit als een lege pagina). Je kunt dit tabblad sluiten.
5. Controleren gegevens
Open opnieuw het overzicht van de EWS-locatie in AllSolutions. Controleer of het veld refresh token nu zichtbaar is. Dit veld wordt automatisch gevuld wanneer alle stappen voor de inrichting goed zijn verlopen. Binnen Microsoft Azure is dan aan AllSolutions (als ‘app’) toegang verleend.. Als hier een refresh token aanwezig is, dan is de koppeling in principe goed ingericht en heeft AllSolutions toegang heeft tot Exchange. Als extra controle kun je bij het mailaccount van de gebruiker nog even nakijken of de applicatie correct is gekoppeld. Zie Azure portal > User > Applications.
(In AllSolutions worden overigens alleen de eerste 50 tekens van het refresh token getoond. Omdat dit token toegang geeft tot de mailbox, wordt hier niet het volledige token weergegeven.)
De koppeling blijft nu werken tot de datum waarop de Client secret code verloopt of tot de de rechten van de app komen te vervallen of in Azure worden ingetrokken.
Aanvullende informatie en onderhoud
In principe is de koppeling onderhoudsvrij. Mochten er toch problemen voordoen, controleer dan altijd de logging. Als hier meldingen over gefaalde authenticatie in staan, is waarschijnlijk het client secret in Microsoft Azure verlopen. Het is voor AllSolutions niet mogelijk de levensduur van een client secret te weten te komen. Houdt dus zelf in de gaten wanneer deze verloopt!
Goed om te weten: Ook als een client secret nog niet is verlopen, kun je deze vervangen door een nieuwe code. Dit doe je door simpelweg een nieuwe client secret te genereren in Azure en deze waarde bij de bijbehorende EWS-importlocatie (MILSCN) in AllSolutions in te voeren. Het opnieuw autoriseren van de app is hierbij niet nodig.
Ondersteuning bij inrichting
Heb je bij de inrichting van de koppeling ondersteuning nodig? Of lukt het je niet om een vervallen client secret te vervangen? Natuurlijk helpen we je dan graag op weg, in eerste instantie via consultancy, of – wanneer meer technische ondersteuning gewenst is – via onze technische dienstverlening. Op deze ondersteuning zijn onze reguliere tarieven van toepassing.