AllSolutions biedt een koppeling met Microsoft Exchange, waarbij het mogelijk is om Contactpersonen (relaties), Taken (acties) en Agenda (afspraken) te synchroniseren met MS Outlook. Lees hier welke voorwaarden van toepassing zijn om een koppeling tussen AllSolutions en Microsoft Exchange te realiseren. In dit artikel wordt uitgelegd hoe je de koppeling kunt inrichten.
De koppeling met Microsoft 365 (online-versie) wordt gelegd 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.
We raden aan om de inrichting eerst te testen in je acceptatieomgeving, voordat je dit in je productieomgeving gaat doorvoeren.
LET OP! Het is belangrijk dat gebruikers in EWS/Azure Active Directory op dezelfde manier zijn opgezet als in AllSolutions! In het veld Exchange account bij de Gebruiker (MGEBRU) vul je straks in de laatste stap het user account van de gebruiker in. Voor het werken van de koppeling moet dit veld dit altijd de User Principal Name (UPN) van de gebruiker bevatten. 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.
Als in AllSolutions bij de gebruiker in het veld Exchange account geen geldige UPN is ingevuld, zal Exchange dit melden. Vanuit AllSolutions wordt de synchronisatie van 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.
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.
- URL: Vul de URL in van de Exchange-service.
- Domein: Vul hier de naam van jouw maildomein in.
- Stel het veld Authentication method in op OAuth 2.0.
- Selecteer bij het veld Interface voor EWS via de i-button de EWS-importlocatie (MILSCN) die je zojuist hebt aangemaakt.
- De velden EWS access token en EWS access-token geldig tot kun je negeren. Deze worden straks als de koppeling volledig in bedrijf is, automatisch gevuld.
- 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 van de gebruiker waarop voor Exchange de impersonation rechten zijn weggegeven! (Zie ook de voorwaarden voor de AllSolutions koppeling met Exchange.) Als je dit met een ander account uitvoert, zal de koppeling met Exchange NIET gaan werken!
Zorg er voor dat dit account 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.
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.
Volgende stap
Als de koppeling tussen AllSolutions en Exchange is ingericht, kun je de synchronisatie gaan activeren bij je gebruikers.
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.