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 hebben Microsoft en Google intussen aangekondigd op termijn met ‘basic authentication’ te 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 op deze nieuwe methode.



Stappenplan Microsoft Azure

In het kort bestaat dit uit het aanmaken van AllSolutions als ‘app’ op het Microsoft platform en het overnemen van de gegenereerde informatie in AllSolutions. Hiervoor voer je de volgende stappen uit:

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

Geef de ‘app’ een naam, bijvoorbeeld AllSolutions mailimport.

AllSolutions 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

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.

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

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 het importeren straks niet werken. 

Sla de gegevens op.

4. AllSolutions ‘app’ authoriseren

Open het overzicht van de mailbox (of kies nog een keer voor bewerken) in AllSolutions.

Kopieer de URL in het veld Request an authorization code naar je internet-browser om voor AllSolutions (als ‘app’ binnen Microsoft Azure) een authorization code aan te vragen. Dit opent een nieuwe browser waarin Microsoft om toestemming vraagt. 

Gebruik de mailbox die je wilt laten uitlezen (zie veld Account mailserver in de mailbox instellingen in AllSolutions) om in te loggen en als deze gebruiker het toegangsverzoek te beoordelen. (In de Microsoft-omgeving kan overigens ingericht zijn dat alleen een account met administrator rechten dit toegangsverzoek mag goedkeuren.)

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

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.

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 en refresh token aanwezig is, dan weet je dat de koppeling goed is ingericht en dat AllSolutions toegang heeft tot de 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.)

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.

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)


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.

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.

3. AllSolutions ‘app’ authoriseren

Open het overzicht van de mailbox (of kies nog een keer voor bewerken) in AllSolutions.

Kopieer de URL in het veld Request an authorization code naar je internet-browser om in Google AllSolutions toestemming te verlenen.

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

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)


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 bij 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