In AllSolutions kun je documenten (poststukken, inkoopfacturen, etc.) importeren vanuit een of meerdere mailboxen. Op basis van Basic Authentication wordt een gebruikersnaam en wachtwoord gebruikt om op de mailbox in te loggen. 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. En ook Google zal op termijn hiermee gaan stoppen.
Daarom is het mogelijk om een Microsoft Office 365 mailbox (vanaf versie 22.0.01) of Google mailbox (vanaf versie 22.0.07) uit te lezen 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 de mailbox.
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.
Tip! Als je één mailbox hebt omgezet, controleer dan gelijk even of het importeren uit deze mailbox goed gaat. Een goede check om te zien of je alle stappen goed hebt doorlopen. En zo heb je gelijk een ‘best practice’ voor het omzetten van de volgende mailboxen.
- Stappenplan Microsoft Azure
- Stappenplan Google
- Onderhoud op client secrets en refresh tokens
- Alternatief: Inkoopfacturen importeren vanuit eConnect
Ondersteuning bij inrichting
Heb je bij de inrichting van de mailboxen ondersteuning nodig? Of lukt het je niet om een vervallen client secret of refresh token 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.
Stappenplan Microsoft Azure
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 mailaccount dat je wilt uitlezen, 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 mailboxen als test wilt kunnen uitlezen). De in je omgeving geregistreerde mailboxen – in de functies Importlocaties E-mail Integratie (MILEML) en Importlocaties Documenten (MILSCN) – kunnen de gegevens van de ‘app’ delen. Zo houd je het beheer van de apps in Azure overzichtelijk.
Geef de ‘app’ een naam, bijvoorbeeld AllSolutions mailimport (acceptatie) en AllSolutions mailimport (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
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 de mailbox 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 de mailbox niet meer uitgelezen kan worden 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 Onderhoud op client secrets en refresh tokens.
3. Interface informatie registreren in AllSolutions
Met de gegevens uit stap 1 en 2 kun je de instellingen in AllSolutions omzetten naar OAuth 2.0. Dit doe je voor elke geregistreerde mailbox in de functies:
- Importlocaties E-mail Integratie (MILEML)
- Importlocaties Documenten (MILSCN)
Zijn er al mailboxen ingericht? Selecteer dan de mailbox die je wilt omzetten en kies voor bewerken.
Wil je een nieuwe mailbox gaan inrichten? Gebruik dan de plus-knop of actie Nieuw om een nieuwe mailbox te gaan toevoegen.
Tip! Zet de helpteksten in het scherm aan voor meer informatie.
- Protocol: OAuth authentication wordt alleen ondersteund in combinatie met Secure IMAP via poort 993.
- Authentication method: Zet deze om naar Oauth 2.0 voor Microsoft.
- Account mailserver: Hier staat het adres van de mailbox die je wilt uitlezen. Werk je met een shared mailbox? Vul in dit veld dan eerst het hoofdaccount in. (In geval van het willen uitlezen van meerdere mailboxen onder dit hoofdaccount maak je in deze stap 3. een apart record aan voor elke mailbox die je wilt uitlezen.)
Vul in de volgende velden de gegevens in die je in Microsoft Azure hebt verkregen:
- Application (client) ID
- Client secret (=de secret VALUE – dus niet de ‘SecretID’!)
- OAuth 2.0 authorization endpoint
- OAuth 2.0 token endpoint
Client secret: Let erop dat je hier de VALUE van de secret invult en niet de ‘SecretID’. De secret value is doorgaans langer, toont geen streepjes en bevat veelal een tilde ~.
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 het importeren straks niet werken.
Sla de gegevens op via Opslaan + Overzicht. Je komt dan terug in het overzichtscherm waarmee je gelijk verder kan met punt 4.
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/MILEML) in AllSolutions in te voeren. Het opnieuw autoriseren van de app is hierbij niet nodig.
4. AllSolutions ‘app’ authoriseren
In deze stap vraag je voor AllSolutions (als ‘app’ binnen Microsoft Azure) een autorization code aan. Dit doe je vanuit het overzichtscherm van de mailbox waarin je bij de vorige stap bent geëindigd.
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.
Log hier in met de mailbox die je wilt laten uitlezen (zie veld Account mailserver in het overzicht in AllSolutions) om het toegangsverzoek te beoordelen. Zorg er dus 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 het e-mail account van de mailbox die je wilt gaan uitlezen, om het toegangsverzoek te beoordelen. Als je dit met een ander e-mailadres uitvoert, zal het uitlezen van de mailbox 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.
Shared mailboxen
Werk je met shared mailboxen? Dan gelden de volgende aandachtspunten:
- Vraag per mailbox de autorisatie op door in te loggen met het hoofdaccount. Dit doe je apart voor elke mailbox die je in AllSolutions hebt geregistreerd, ook al gaat het om hetzelfde (hoofd)account! Voor elke mailbox moet namelijk een eigen refresh-token gegenereerd worden.
- Daarna verander je het e-mailadres van het hoofdaccount in het veld Account mailserver in het adres van de uiteindelijke mailbox die wordt uitgelezen. Als je dit vergeet, zal de import niets doen.
Voorbeeld:
Bij deze shared mailbox vraag je de autorisatie dus eerst op voor het (hoofd)account ‘allsolutions@allsolutions.nl’.
Nadat de autorisatie is geregeld en het veld Refresh token is gevuld, neem je in het veld Account mailserver de naam op van de uiteindelijke mailbox die uitgelezen moet worden:
5. Controleren gegevens
Open opnieuw het overzicht van de mailbox 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 tot de mailbox. Als hier een refresh token aanwezig is, dan is de koppeling in principe goed ingericht en heeft AllSolutions toegang heeft tot de mailbox. Als extra controle kun je bij het mailaccount 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 verloopt of tot de de rechten van de app komen te vervallen of in Azure worden ingetrokken.
Goed om te weten: Er zijn op dat moment nog geen e-mails geïmporteerd. Dit doe je met de volgende functies zoals je gewend bent:
- Importeren Inkoopfacturen (VIMINK)
- Importeren Gescande Poststukken (VIMPSI)
- Importeren E-mails (VEMAIL)
Tip! Als je één mailbox hebt omgezet, controleer dan gelijk even of het importeren uit deze mailbox goed gaat. Een goede check om te zien of alle stappen goed zijn doorlopen. En zo heb je gelijk een ‘best practice’ om de volgende mailboxen om te zetten.
Stappenplan Google
1. Maak een OAuth Client ID aan in de cloud console
Ga naar https://console.cloud.google.com/apis/ en maak daar een OAuth client ID aan. Kies hierbij voor OAuth 2.0 Client ID.
Als dit de eerste OAuth client ID binnen een Google Project is, moet er ook een consent screen gedefinieerd worden.
Het application type is Web application.
En geef de client ID de naam AllSolutions zodat je deze goed kunt herleiden.
Gebruik als Authorised redirect URL ‘https://[domein].[tld]/jsonhandler.ashx‘, waarbij je op de plaats van [domein].[tld] de URL van de AllSolutions-omgeving invult. Google gebruikt deze URL straks om de respons op het authenticatie verzoek naartoe te sturen.
Als de OAuth client aangemaakt is, noteer je de Client ID en Client Secret. Deze heb je straks nodig voor de inrichting in AllSolutions.
OAuth consent screen aanmaken
Als Google vraagt een OAuth consent screen aan te maken, doe dit dan. Dit bepaalt hoe het verleen-toestemming-scherm van Google gestyled wordt.
Kies hierbij wel voor internal users. Anders zou de hele wereld de AllSolutions ‘app’ kunnen gebruiken en moet deze goedgekeurd worden door Google.
Vul AllSolutions als app name in. Deze naam zie je straks op het consent scherm terug.
Geef bij Authorised domains het klantdomein op.
De scopes mogen leeg blijven. Deze worden straks via het Authorisation request gevraagd.
2. Interface informatie registreren in AllSolutions
Met de gegevens uit stap 1 en 2 kun je de instellingen in AllSolutions omzetten naar OAuth 2.0. Dit doe je in de functies:
- Importlocaties E-mail Integratie (MILEML)
- Importlocaties Documenten (MILSCN)
Selecteer de mailbox die je wilt omzetten en kies voor bewerken.
Tip! Zet de helpteksten in het scherm aan voor meer informatie.
- Protocol: OAuth authentication wordt alleen ondersteund in combinatie met Secure IMAP via poort 993.
- Authentication method: Zet deze om naar Oauth 2.0 voor Google.
Vul in de volgende velden de gegevens in die je in Google hebt verkregen:
- Application (client) ID
- Client secret
Daarnaast heb je ook de volgende informatie nodig:
- OAuth 2.0 authorization endpoint
- OAuth 2.0 token endpoint
Deze beide endpoints vind je in Google. Op deze pagina vind je meer informatie.
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 bij Google. Google 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 Google hebt gedaan! Anders zal het importeren straks niet werken.
Sla de gegevens op via Opslaan + Overzicht. Je komt dan terug in het overzichtscherm waarmee je gelijk verder kan met punt 3.
3. AllSolutions ‘app’ authoriseren
In deze stap vraag je voor AllSolutions de autorisatie aan bij Google. Dit doe je vanuit het overzichtscherm van de mailbox waarin je bij de vorige stap bent geëindigd.
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.
Controleer in het toegangsverzoek:
- De zelf opgegeven naam van de app
- De gevraagde rechten
Hieronder een voorbeeld van het toegangsverzoek waarbij op de plaats van ‘mail import door AllSolutions‘ de naam komt te staan, die je in Google aan de app hebt meegegeven.
Klik op Toestaan om de toestemming te verlenen.
De volgende rechten of scopes worden gebruikt:
- De access_type=offline is nodig om nieuwe access tokens aan te kunnen vragen zonder tussenkomst van de gebruiker
- https://mail.google.com/ is nodig voor toegang om de mailbox uit te lezen.
Na het accepteren van het toegangsverzoek, wordt je door Google doorgestuurd naar de opgegeven Redirect URL (in je browser toont dit als een lege pagina). Je kunt dit tabblad sluiten.
4. Controleren gegevens
Open opnieuw het overzicht van de mailbox 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. Als hier een refresh token aanwezig is, dan weet je dat de koppeling goed is ingericht en dat AllSolutions toegang heeft tot de Google mailbox.
(Hier 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.)
Google heeft (waarschijnlijk) ook een e-mail gestuurd ter bevestiging van de nieuw uitgedeelde rechten. En in https://myaccount.google.com/ kun je ook zien dat de AllSolutions als ‘app’ toegang heeft gekregen.
Bij Google verlopen de refresh tokens als deze 6 maanden niet gebruikt zijn. In een normale situatie zorgt dit niet voor problemen. Maar in omgevingen die minder actief worden gebruikt (zoals de acceptatieomgeving) kan dit wel voorkomen. En wanneer je het wachtwoord van een Google account wijzigt, worden sowieso alle refresh tokens ongeldig gemaakt.
De mailbox kan in dit geval niet langer worden uitgelezen. Dit kun je zien op het verwerkingsverslag. Je kunt dit zelf oplossen door AllSolutions als ‘app’ opnieuw toegang te verlenen (zie stap 3 van Google).
Goed om te weten: Er zijn op dit moment nog geen e-mails geïmporteerd. Dit doe je met de volgende functies zoals je gewend bent:
- Importeren Inkoopfacturen (VIMINK)
- Importeren Gescande Poststukken (VIMPSI)
- Importeren E-mails (VEMAIL)
Tip! Als je één mailbox hebt omgezet, controleer dan gelijk even of het importeren uit deze mailbox goed gaat. Een goede check om te zien of alle stappen goed zijn doorlopen. En zo heb je gelijk een ‘best practice’ om de volgende mailboxen om te zetten.
Onderhoud op client secrets en refresh tokens
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 importlocatie (MILSCN/MILEML) in AllSolutions in te voeren. Het opnieuw autoriseren van de app is hierbij niet nodig.
Bij Microsoft verloopt het refresh token als deze 90 dagen niet gebruikt is. In een normale situatie zorgt dit niet voor problemen, maar in omgevingen die minder actief worden gebruikt (zoals de acceptatieomgeving) kan dit wel voorkomen. De mailbox kan in dit geval niet langer worden uitgelezen. Dit kun je zien op het verwerkingsverslag. Je kunt dit zelf oplossen door AllSolutions als ‘app’ opnieuw toegang te verlenen (zie stap 4 van Microsoft).
Bij Google verlopen de refresh tokens als deze 6 maanden niet gebruikt zijn. En wanneer je het wachtwoord van een Google account wijzigt, worden sowieso alle refresh tokens ongeldig gemaakt.
De mailbox kan in dit geval niet langer worden uitgelezen. Dit kun je zien op het verwerkingsverslag. Je kunt dit zelf oplossen door AllSolutions als ‘app’ opnieuw toegang te verlenen (zie stap 3 van Google).
Lees hier meer informatie over het verlopen en intrekken van toegang.
Alternatief: Inkoopfacturen importeren vanuit eConnect
Het is ook mogelijk om inkoopfacturen op een gecontroleerde en veilige manier in AllSolutions te importeren via een koppeling met eConnect. Op basis van herkenning van een aantal factuurgegevens doet het systeem een voorstel voor de registratie van de inkoopfactuur. Op deze manier kun je de factuur snel en gemakkelijk inboeken en verwerken in AllSolutions.
Meer informatie over eConnect