Instellingen WICBox met OAuth2 functionaliteit
Beste WIC-klant,
Microsoft heeft beslist om Basic Authentication definitief uit te schakelen en alle applicaties en gebruikers te verplichten de beveiligde OAuth2.0-methode te gebruiken om authenticatie te doen op de email-servers. Dit zowel voor het inlezen als versturen van mails.
In eerste instantie wordt het inlezen van mails via Basic Authentication afgesloten. Er blijft een periode van 3 maanden beschikbaar om ook het versturen van mails te laten migreren naar de nieuwe OAuth2.0-integratie.
Voor het versturen van de mails zal de toekomstige WIC-versie (v4.9.9) uitkomen waarin we het probleem oplossen binnenin WIC. Deze versie zal in de loop van Oktober officieel gereleased worden.
Voor het inlezen van mails is de overgangsperiode korter en wordt er verwacht dat we onmiddellijk de overgang gaan moeten organiseren. We hebben hierover reeds heel wat tegenstrijdige berichten gekregen maar momenteel gaan we uit van het scenario dat de werking per direct stopt vanaf 01/10/2022. Dit heeft een grote impact op de werking van WICBOX. Als gebruiker van WICBOX en ook als gebruiker van Microsoft’s Office365 dient de WICBOX over te schakelen op OAuth2.0 authenticatie.
Om deze overgang te begeleiden, werd dit document opgesteld om de stappen van omschakeling zo vlot mogelijk te laten verlopen. Vooral Stap 5 is een belangrijke stap voor u als klant om zelf mee aan de slag te gaan.
Stap 1: Minimale WIC-versie 4.9.6
Omdat we geen gloednieuwe versie zo maar op u willen loslaten is er geopteerd om backwards-compatible te blijven met enkele voorgaande versies van WIC. We vragen daarom om WIC minstens te gaan upgraden naar versie 4.9.6 (4.9.6.20 is de laatste specifieke versie in deze reeks).
Ter info: de versie die momenteel kan uitgerold worden is onze nieuwe 4.9.8.
Stap 2: Configuratie: WicGlobal.config
Onze WIC-applicaties maken ondertussen gebruik van een globale configuratie-bestand waarin we voor deze omschakeling nog een configuratie-sleutel hebben moeten toevoegen. Deze is niet beschikbaar in WICMan omdat we niet wensen dat hier zo maar mee geëxperimenteerd kan/mag worden. Het is aan KPD om deze configuratie uit te voeren. Het betreft een configuratie om aan te geven hoeveel mails er per run zal verwerkt mogen worden. Dit om te vermijden dat bij grote mailboxen de verwerking langer zou lopen dan toegelaten wordt via de nieuwe authenticatie. De maximale waarde is 1000. De inschatting die gemaakt wordt, is het aantal mails dat per 5 minuten binnenkomt op de globale mailbox van WICBOX. Standaard gaan we dit op 100 zetten. Indien er door de klant wordt ingeschat dat dit onvoldoende zou zijn, kan er contact opgenomen worden met onze helpdesk, meer in het bijzonder het WIC-team.
Stap 3: Nieuwe WIC-parameters
Afhankelijk van de versie die geïnstalleerd staat/wordt, dienen er een aantal parameters geconfigureerd te worden in WICMan. Als deze parameters nog niet bestaan zal KPD er voor zorgen dat ze worden voorzien.
- WICBOX_MAILCLIENT_SCOPE
- WICBOX_MAILCLIENT_CLIENTID
- WICBOX_MAILCLIENT_CLIENTSECRET
- WICBOX_MAILCLIENT_TENANTID
- WICBOX_MAILCLIENT_USERNAME
- WICBOX_MAILCLIENT_PASSWORD
- Omzetting ACCOUNTMODE -> WICBOXACCOUNTMODE
- WICBOXMethod
(Scriptnrs: 40201575.sql / 40201577.sql / 40201578.sql)
Stap 4: WICBOX = Scheduled Task
De WICBOX is een applicatie die getriggered wordt vanuit een scheduled task. Deze task dient gestopt te worden, alvorens de nieuwe WICBOX kan geïnstalleerd worden. Deze stap zal, indien KPD voldoende rechten heeft, ook door ons uitgevoerd worden tijdens het update-proces.
Vervolgens zal KPD de nieuwe versie van de WICBOX installeren.
Stap 5: Configuratie van de Azure-omgeving
De Azure-service voor Office365 dient aangepast te worden. Er dient een applicatie “WicBox” aangemaakt te worden waarbij de ClientId en TenantId dienen ingevuld te worden.
- Ga naar je “Azure homepage”
- Klik op “Azure Active Directory”
- Klik op “+ Add” => “App registration” (zie Screenshot1)
- Kies een naam (WICBox), de rest mag blijven zoals het staat (zie Screenshot2)
- Klik op ‘Register’
- In overzichtsscherm van deze nieuwe applicatie kan je de Client Id (is zelfde als Application Id) en Tenant Id (is zelfde als Directory Id) vinden.
- Een client secret is niet nodig tenzij men via “Application permissions” wil werken i.p.v. “Delegated permissions”, zie helemaal onderaan voor verschil.
Screenshot 1
Screenshot 2
- In Azure moet voor deze applicatie de setting “Authentication/Allow public client flows” aangezet worden, klik hiervoor links in Application overzichtsscherm op “Authentication” (zie Screenshot3)
Screenshot 3
- In Azure moet deze applicatie bij “API permissions” de “Microsoft Graph” permission “Mail.ReadWrite” van type “Delegated” (of “Application”, zie helemaal onderaan voor verschil) krijgen, goed te keuren door administrator via “Grant admin consent”. Klik hiervoor links op “API Permissions” en klik op “+ Add permission” (zie Screenshot4, opgelet: in deze screenshot staan veel meer permissions dan nodig voor WICBox)
Screenshot 4
Stap 6: Nieuwe parameters – invullen
Parameter |
Waarde |
Alternatief: Application Permissions |
WICBOX_MAILCLIENT_SCOPE |
Mail.ReadWrite |
Mail.ReadWrite |
WICBOX_MAILCLIENT_CLIENTID |
CientID van Azure |
leeg |
WICBOX_MAILCLIENT_CLIENTSECRET |
leeg |
ClientSecret van Azure |
WICBOX_MAILCLIENT_TENANTID |
TenantID van Azure |
|
WICBOX_MAILCLIENT_USERNAME |
Zelfde als WICBOXUsername |
Zelfde als WICBOXUsername |
WICBOX_MAILCLIENT_PASSWORD |
Zelfde als WICBOXPassword |
leeg |
WICBOXMethod |
OAuth2 |
OAuth2 |
Alternatief – Application Permissions ipv Delegated Permissions
Men kan er ook voor kiezen om via “Application Permissions” te werken i.p.v. “Delegated Permissions”.
Dan dient er een “Client Secret” toegevoegd worden aan de application in Azure. Deze waarde moet dan in de parameter WICBOX_MAILCLIENT_CLIENTSECRET komen (parameter WICBOX_MAILCLIENT_PASSWORD mag dan leeg blijven wegens niet gebruikt). In Azure moet deze applicatie dan bij “API permissions” de “Microsoft Graph” permission “Mail.ReadWrite” van type “Application” krijgen, goed te keuren door administrator via “Grant admin consent”.
Het grote verschil tussen beide is:
Delegated Permissions: de applicatie vraagt een authenticatie aan via zijn ClientId en username/password van een mailbox en heeft enkel autorisatie om de mails van zijn eigen mailbox te lezen, de applicatie kan normaal niet aan andere mailboxen (kan misschien wel ingesteld worden door admin maar is buiten onze scope). Als WICBOXMETHOD op “MULTIPLE” dan zal de authenticatie/autorisatie steeds opnieuw gedaan worden via de username/password van het project zelf (dus niet wat in WICBOX_MAILCLIENT_USERNAME en WICBOX_MAILCLIENT_PASSWORD staat).
Application Permissions: de applicatie vraagt een authenticatie aan via zijn ClientId en zijn ClientSecret, en vraagt dan toegang tot 1 of meerder mailboxen, dat is bij “SINGLE” dan de mailbox van de user in parameter WICBOX_MAILCLIENT_USERNAME. Maar de applicatie kan dan volgens mij standaard aan ALLE mailboxen in die TenantId tenzij expliciet verboden door een policy, dit is in te stellen door de admin (maar is buiten onze scope). Als WICBOXMETHOD op “MULTIPLE” staat dan zal de authenticatie/autorisatie slechts eenmaal gedaan worden voor de applicatie zelf, maar wordt dus ook steeds een andere mailbox (die van het project zelf, dus niet wat in WICBOX_MAILCLIENT_USERNAME staat) opgevraagd om mails uit te lezen.
Ter info: als WICBOXMETHOD op “MIX” staat dan zal de applicatie eerst de code van “SINGLE” doorlopen en dan die van “MULTIPLE” maar met een iets aangepast lijst van projecten (andere WHERE conditie) dan als enkel “SINGLE” of “MULTIPLE” wordt gekozen.
Voor WICBox zelf maakt het functioneel geen verschil of voor “Application Permissions” of “Delegated Permissions” wordt gekozen, is puur een kwestie van configuratie van Azure en WICBox zelf. Volgens mij is “Delegated Permissions” misschien het eenvoudigste als men “SINGLE” werkt, en “Application Permissions” als men “MULTIPLE” werkt.
