Modernin todennuksen (OAuth2) käyttö sähköpostin todennusmenetelmänä O365:n kanssa

Tässä dokumentissa kuvattu moderni todennus on tuettu ESM-versiossa 2021.1 ja sitä uudemmissa versioissa.

Jotta ESM:ssä voidaan käyttää modernia todennusta (OAuth2) perustodennuksen sijaan SMTP- ja IMAP-protokollille, on tehtävä kolme vaihetta:

1. ESM on rekisteröitävä hyväksyttynä sovelluksena Azure Active Directoryyn Microsoft Azure -portaalin kautta.
2. Rekisteröidylle sovellukselle on myönnettävä käyttöoikeus Efectelle käytettävään O365-sähköpostitiliin.
3. ESM:n alusta-asetukset on päivitettävä vastaamaan Microsoft Azuren asetuksia.

Vaiheet 1–2 suositellaan tehtäväksi samalla O365-tilillä, josta sähköpostit luetaan ESM:ään. Jos tämä ei ole mahdollista, sovellukselle on määritettävä Owner (omistaja) Azure AD:ssa.

ESM:n rekisteröiminen sovellukseksi Microsoft Azuressa

Edellytykset

• Microsoft Azure -tili, jolla on aktiivinen tilaus (ESM:n kanssa käytettävä O365-sähköpostitili).
• Käytettävissä oleva Azure-vuokraaja (tenant), jonka alle sovellus rekisteröidään.

Sovelluksen rekisteröiminen

Sovelluksen rekisteröiminen luo luottamussuhteen ESM:n ja Microsoftin identiteettialustan välille. Rekisteröidyn sovelluksen luottamussuhde on yksisuuntainen: sovellus (ESM) luottaa Microsoftin identiteettialustaan, mutta ei toisin päin. Luottamus perustuu rekisteröintiprosessissa luotuun tunnisteeseen.

Luo sovellusrekisteröinti seuraavien vaiheiden mukaisesti:

• Kirjaudu Microsoft Entra -portaaliin (https://entra.microsoft.com) tai Azure-portaaliin (https://portal.azure.com/).
• Jos sinulla on käyttöoikeus useisiin vuokraajiin, käytä Directory + subscription -suodatinta ylävalikossa valitaksesi vuokraajan, johon haluat rekisteröidä sovelluksen.
• Hae ja valitse Microsoft Entra ID (aiemmin Azure Active Directory).
• Kohdassa Manage, valitse App registrations > New registration.
• Anna Name sovellukselle. Sovelluksesi käyttäjät saattavat nähdä tämän nimen, ja voit muuttaa sitä myöhemmin.
• Määritä, kuka voi käyttää sovellusta (kutsutaan joskus kirjautumiskohderyhmäksi). Valitse ESM:lle Accounts in this organizational directory only -vaihtoehto.
• Älä syötä mitään kohtaan Redirect URI (optional).
• Valitse Register viimeistelläksesi alustavan sovellusrekisteröinnin.

Kun rekisteröinti on valmis, Azure-portaali näyttää sovellusrekisteröinnin Overview-näkymän, joka sisältää sovelluksen Application (client) ID -tunnuksen. Tätä arvoa kutsutaan myös nimellä client ID, ja se yksilöi sovelluksesi Microsoftin identiteettialustalla.

Käyttöoikeuksien lisääminen O365-postilaatikon käyttöä varten

Jotta sähköposteja voidaan lähettää ja vastaanottaa O365-postilaatikosta OAuthin avulla, on määritettävä API-käyttöoikeuksien laajuudet (scopes) aiemmin Azure Active Directoryyn rekisteröidylle ESM-sovellukselle.

Delegoitu käyttöoikeus Microsoft Graphiin

Määritä delegoitu käyttöoikeus Microsoft Graphiin, jotta ESM voi suorittaa toimintoja sovelluksen omistajien puolesta, esimerkiksi lukea tai lähettää heidän sähköpostejaan.

• Kirjaudu Microsoft Entra -portaaliin (https://entra.microsoft.com) tai Azure-portaaliin (https://portal.azure.com/).
• Jos sinulla on käyttöoikeus useisiin vuokraajiin, käytä Directory + subscription -suodatinta ylävalikossa valitaksesi vuokraajan, joka sisältää aiemmin rekisteröimäsi ESM-sovelluksen.
• Valitse Azure Active Directory > App registrations, ja valitse sitten asiakassovelluksesi (jos sitä ei näy luettelossa, tarkista, että sivulla näytetään All applications).
• Valitse API permissions > Add a permission > Microsoft Graph.
• Valitse Delegated permissions. Microsoft Graph tarjoaa monia käyttöoikeuksia, ja yleisimmin käytetyt näkyvät luettelon alussa.
• Kohdassa Select permissions, valitse seuraavat käyttöoikeudet:
  • IMAP.AccessAsUser.All – Luku- ja kirjoitusoikeus postilaatikoihin IMAP:n kautta.
  • SMTP.Send – Sähköpostien lähetys postilaatikoista SMTP AUTH:n avulla.
  • openid – Käyttäjien kirjautuminen sisään.
  • User.Read– Kirjautuminen sisään ja käyttäjäprofiilin lukeminen.
  • offline_access – Pääsyn ylläpitäminen dataan, johon olet myöntänyt sille oikeuden.
• Valitse Add permissions viimeistelläksesi prosessin.

Ylläpitäjänä sinun tulisi myös myöntää suostumus (consent) kaikkien ESM-ylläpitäjäkäyttäjien puolesta, jotta heiltä ei kysytä sitä erikseen, kun he kirjautuvat postilaatikkoon. Admin consent -toimintoa käsitellään seuraavassa alaluvussa. Jos määrität Admin consentin etukäteen, postilaatikkoihin kirjautuvilta käyttäjiltä ei kysytä erikseen Admin consentia.

ESM-ylläpitäjien tulisi kirjautua viikoittain sähköpostitileille, jotka luetaan ESM:ään, tarkistaakseen, sisältääkö roskapostikansio todellisia asiakassähköposteja, ja siirtää ne kansioon, josta sähköpostit haetaan ESM:ään (yleensä saapuneet-kansio).
Lisäksi ylläpitäjien tulisi tarkistaa tapaukset, joissa sähköposteja ei saada haettua onnistuneesti ESM:ään. Jos saapuneet-kansiossa on suuria sähköposteja, joita ei voida hakea ESM:ään, ne tulisi siirtää toiseen kansioon virheiden välttämiseksi.

Admin consent -painike

Grant admin consent for {your tenant} -painike antaa ylläpitäjälle mahdollisuuden myöntää admin consentin sovellukselle määritetyille käyttöoikeuksille. Kun valitset painikkeen, näytetään valintaikkuna, jossa pyydetään vahvistamaan suostumustoiminto.

Kun suostumus on myönnetty, käyttöoikeudet, jotka vaativat admin consentin, näkyvät myönnettyinä:

Grant admin consent-painike on poissa käytöstä, jos et ole ylläpitäjä tai jos sovellukselle ei ole määritetty käyttöoikeuksia. Jos sinulla on käyttöoikeuksia, jotka on myönnetty mutta joita ei ole vielä määritetty, admin consent -painike kehottaa käsittelemään nämä käyttöoikeudet. Voit lisätä ne määritettyihin käyttöoikeuksiin tai poistaa ne.

Todennusasetukset

Jotta ROPC-valtuutusvuo toimisi oikein sovellukselle ja ESM voisi todentaa ja saada käyttöoikeustunnuksia (access token), on otettava käyttöön Default Client type -asetus (kuten kuvakaappauksessa) kohdassa Authenticate → Advanced Settings.

Oletuksena asetuksena on No (confidential client). Kun sen päivittää arvoon Yes muuttaa oletusasiakastyypin julkiseksi asiakkaaksi (public client). Tämä on erittäin tärkeä vaihe – jos sitä ei tehdä, näet alla olevan virheen:

-  AADSTS7000218: The request body must contain the following parameter: client_assertion or client_secret when authenticating to Azure AD. 

Sovelluksen rekisteröinti- ja asetusprosessi on nyt valmis. Tämän jälkeen tarvitsee vain lisätä seuraavat alusta-asetukset ESM:ään yllä olevan määrityksen käyttämiseksi.

ESM:n alusta-asetukset

Jotta ESM voidaan määrittää käyttämään juuri Azure-portaaliin luotua OAuth2-päätepistettä sähköposteille, siirry ESM:n ylläpitonäkymään ja siirry kohtaan Maintenance > System settings > Edit Platform Settings. Käytä suodatinkenttää löytääksesi seuraavat sähköpostiasetukset yksi kerrallaan ja aseta seuraavat ominaisuudet:

mail.store.oauth.enabled = true
mail.transport.oauth.enabled = true
mail.oauth.authorize.endpoint = https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize
mail.oauth.client.id = {clientId}
mail.oauth.scopes = https://outlook.office365.com/IMAP.AccessAsUser.All,https://outlook.office365.com/SMTP.Send

clientId ja authorize-päätepiste löytyvät Azure Active Directoryn etusivulta ESM:lle rekisteröidyn sovelluksen kohdalta. Katso alta, miten ne haetaan.

Huomaa, että mailtaskit käyttävät niiden ominaisuuksissa määritettyjä asetuksia. Jos yhteys- ja todennusasetukset on määritetty mailtaskin ominaisuuksissa (eikä keskitetysti kaikkien mailtaskien alusta-asetuksissa), aseta yllä luetellut asetukset suoraan kunkin mailtaskin ominaisuuksiin.

Viitteet

https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth 
https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app 
https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows 
https://blogs.aaddevsup.xyz/2020/09/whats-the-security-implication-of-changing-the-default-client-type-from-confidential-to-public-in-azure-ad/