Mailbox uitlezen met OAuth 2.0

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

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).

AllSolutions productieomgeving als ‘app’ aanmaken

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!

Application (client) ID in Microsoft Azure
Endpoints in Microsoft Azure

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!

Client secret genereren in Microsoft Azure

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 omzetten naar OAuth 2.0. Dit doe je voor elke geregistreerde mailbox 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.

Voorbeeld inrichting Outlook mailbox in AllSolutions
  • 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.

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.

AllSolutions ‘app’ authoriseren

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:

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 eerst de autorisatie op door in te loggen met het hoofdaccount (dat vóór de backslash is opgegeven). 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 moet je het e-mailadres in het veld Account mailserver wijzigen naar het adres van de uiteindelijke mailbox die wordt uitgelezen. Anders wordt er niets geïmporteerd.

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.

Voorbeeld inrichting Google mailbox in AllSolutions
  • 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.

Voorbeeld Google OAuth 2.0 authorization endpoint
Voorbeeld Google 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 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.



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 importlocatie (MILSCN/MILEML) in AllSolutions in te voeren. Het opnieuw autoriseren van de app is hierbij niet nodig.

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).

Lees hier meer informatie over het verlopen en intrekken van toegang.



Alternatief: Inkoopfacturen importeren vanuit eVerbinding

Het is ook mogelijk om inkoopfacturen op een gecontroleerde en veilige manier in AllSolutions te importeren via een koppeling met eVerbinding. 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 eVerbinding