Utilisation de Microsoft 365/ OAUTH2 / Graph...


nativIP serveur peut nécessiter l'envoi et la réception de courriers électroniques pour différents services :

  • Recevoir les demandes d'envois de télécopie (l'utilisateur envoie un courriel au serveur nativIP),
  • Envoyer les notifications de réception de télécopie (le destinataire d'une télécopie reçoit un courrier électronique comprenant le fac-similé sous forme d'un fichier PDF en pièce jointe),
  • Envoyer les notifications de réception d'un message dans sa boite vocale,
  • Envoyer des notifications de création automatique d'une boite vocale à l'administrateur,
  • Envoyer des comptes-rendus d'activité ...


Si vous utilisez Microsoft 365 pour vos services de messagerie électronique, il est nécessaire d'inscrire au moins une application sur le portail d'administration Azure (cette application peut être utilisée par d'autres logiciels ou vous pouvez créer autant d'applications que de besoins selon vos stratégies de sécurité) permettant l'accès à ces fonctionnalités :

  • Authentifier l'accès à l'aide d'Oauth2
  • (réception ) Utiliser et autoriser l'accès IMAP 
  • (emission) Utiliser et autoriser l'accès à l'API Graph
  • Maintenir les secret d'accès (renouvellement)


Vous pouvez aussi consulter la documentation Microsoft :  Authentifier une connexion IMAP, POP ou SMTP à l’aide d’OAuth

Connection à l'interface d'administration Azure


Connectez vous sur https://portal.azure.com  avec vos identifiants d'administration.

Via la barre d'outils latérale (déroulez le menu burger), choisissez le lien vers Microsoft Entra ID (auparavant Azure Active Directory)  ou cliquez sur l'icône correspondante.

Définir/Paramètrer une application

Accédez à la page d'inscription d'application 
(Vue d'ensemble / Ajouter / Inscription d'application)

 




Inscrivez l'application nativip_srv (ou tout autre nom de votre choix).

(Il n'est pas nécessaire de saisir une URL de redirection.)


Le nom de l'application peut être modifié ultérieurement.

L'ID d'application (client) ainsi que l'ID de l'annuaire (locataire) (aussi appelé Tenant-ID) sont requis pour la suite.


Poursuivez en cliquant sur Ajouter un certificat ou un secret.

Définir un secret


Activez l'onglet Secrets client s'il n'est pas sélectionné, puis cliquez sur Nouveau secret client.


Ultérieurement, la gestion des secrets est accessible depuis la vue d'ensemble Microsoft Entra ID  : Inscriptions d'applications (menu vertical à gauche), sélectionner l'application puis Certificats et secrets

Définissez la durée de validité du secret. Un nouveau secret devra ainsi être défini avant expiration de celui-ci et configuré sur nativIP serveur pour éviter toute interruption de service.

Autorisations de l'API


Dans API autorisées, cliquez sur ajouter un autorisation.


Pour autoriser la réception de courrier électronique (Service Mail to Fax), il est nécessaire d'autoriser l'accès IMAP : 

- Recherchez l'API Office 365 Exchange Online. Sélectionnez Autorisations d'applications.
- Sélectionner les autorisations imap : validez IMAP.AccessAsApp


Pour autoriser l'envoi de courriel électronique, via Microsoft Graph, il est nécessaire d'autoriser : 

- Recherchez l'API Microsoft Graph, Sélectionnez Autorisations d'applications,
- Sélectionner les autorisations Microsoft Graph : Mail.Send


Il conviendra aussi d'accorder un consentement d'administrateur à l'API.

Dans Applications / Applications d'entreprise , récupérez l'ID d'objet.


ATTENTION : C'est cet ID d'objet qui doit être utilisé dans la configuration et non celui affiché sur Applications / Inscriptions des Applications.
Un mauvais ID d'objet utilisé par la suite (inscription ServicePrincipal ...) entrainera une erreur d'authentification et un accès impossible à la boite de courrier.

Ouvrir l'accès via Exchange

Inscrire le ServicePrincipal dans Exchange

Une fois que l'application est autorisée par un administrateur du tenant (consentement) , l'application doit être inscrite via l'applet NewServicePrincipal.

(Le module PowerShell ExchangeOnlineManagement doit être préalablement installé.)


Install-Module -Name ExchangeOnlineManagement
Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <tenantId>

New-ServicePrincipal -AppId 56ad9064-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ServiceId 82216bb4-xxxx-xxxx-xxxx-xxxxxxxxxxxx


help_outline Ci-avant vous devrez utiliser l'ID d'application (pour AppId) et l'ID d'objet (ServiceID) de votre application.

Autoriser l'accès à la boite mail concernée par l'application

Add-MailboxPermission -Identity "fax@nativip.onmicrosoft.com" -User 
82216bb4-xxxxx-xxxx-xxxx-xxxxxxxxxxxx  -AccessRights FullAccess

(remplacez 822... par l'ObjetID de votre application)

Configuration nativIP serveur

Le serveur nativIP doit être paramétré à travers de son interface web de configuration pour utiliser les services Azure pour l'envoi et / ou la réception des courriers électroniques.
La page de configuration est accessible via le menu Config. Générale / Microsoft 365

Configurer l'envoi des courriels via l'API Graph

Tous les courriels envoyés par le serveur nativIP sont concernés, qu'il s'agisse des notifications de messagerie vocale, de réception de télécopie, toutes notifications, reporting. L'activation de l'envoi via MS365 se fait via l'interrupteur Utiliser MS365... . La prise en compte de la configuration est immédiate, tous les messages en attente et futurs passeront par la configuration active. Lorsque l'envoi via MS365 est activé, les paramètres SMTP ne sont plus utilisés, y compris s'ils sont définis.

Le tenant peut aussi être configuré par son ID.  Le secret doit être actif. Il conviendra de le mettre à jour régulièrement en fonction de sa durée de vie définie sur MS365. L'utilisateur utilisé pour l'envoi des messages est défini par son ObjectID (voir ci-dessous pour connaitre l'ObjectID d'un utilisateur).

Configurer la lecture du compte du serveur de télécopies

Le service mail to fax (courriel vers télécopie) passe par un compte de courrier électronique recevant les demandes d'envoi de télécopies.

Le tenant peut aussi être configuré par son ID.  Le secret doit être actif. Il conviendra de le mettre à jour régulièrement en fonction de sa durée de vie définie sur MS365. Le compte recevant les demandes d'envoi est défini ici. (Les utilisateurs enverront les demandes d'envoi de télécopie à cette adresse de courrier électronique). Il peut être commun (cas général) ou différent du compte utilisé pour l'envoi des messages du serveur nativIP.

Tester

Script PowerShell

Nous vous recommandons de tester l'accès via IMAP à la boite de courrier électronique via un script proposé par Danijel Klaric, ingénieur Microsoft 365 disponible ici :  https://github.com/DanijelkMSFT/ThisandThat/blob/main/Get-IMAPAccessToken.ps1 


Get-IMAPAccessToken.ps1 -tenantID "video.nativip.com" -clientId "56ad9064-xxxx-xxxx-xxxxxxxxxxxx" -clientsecret "zzzzzzz" -targetMailbox "fax@nativip.onmicrosoft.com" -Verbose

forward Ci-avant vous devrez utiliser l'ID d'application (pour AppId) et l'ID d'objet (ServiceID) de votre application.

PS .\Get-IMAPAccessToken.ps1 -tenantID "video.nativip.com" -clientId "56ad9064-xxxx-xxxx-xxxxxxxxxxxx" -clientsecret "zzzzzzzzzzzzzzzzzzzzzzzz" -targetMailbox "fax@nativip.onmicrosoft.com" -Verbose

COMMENTAIRES : Renseignement de la propriété RepositorySourceLocation pour le module MSAL.PS.
COMMENTAIRES : Chargement du module à partir du chemin
[....]
COMMENTAIRES : Chargement du module à partir du chemin
COMMENTAIRES : Access Token --
eyJ0eXAiOiJKV1QiLCJub25jZSI6IkdUVxRExteWZfUi1WclFJQUFBQUFBUEVQemdBQUFBQUFBQUI2QUFBLiIsInJv
[...]
Accessing Sharedmailbox - fax@nativip.onmicrosoft.com - with Accesstoken of User .
COMMENTAIRES : SASL XOAUTH2 login string
dXNlcj1mYXhAbmF0aXZpcC5vbm1pY3Jvc29mdC5jb20BYXV0aD1CZWFyZXIgZXlKMGVYQWlPaUpLVjFRaUxDSnViMjVqWlNJNklrSXlXSEYyTFRrM01YWkl
[...]
Connect to Office 365 IMAP Service.
* OK The Microsoft Exchange IMAP4 service is ready. [UABSADAAUAAyADYANABDAEEAMAAxADQAMAAuAEYAUgBBAFAAMgA2ADQALgB==]
Authenticate using XOAuth2.
COMMENTAIRES : Executing command -- A01 AUTHENTICATE XOAUTH2
dXNlcj1mYXhAbmF0aXZpcC5vbm1pY3Jvc29mdC5jb20BYXV0aD1CZWFyZXIgZXlKMGVYQWlPaUpLVjFRaUxDSnViMjVqWlNJNklrSXlXSEYyTFRrM01YWkl
[...]
A01 OK AUTHENTICATE completed.
Getting mailbox folder list as authentication was successfull.
COMMENTAIRES : Executing command -- A01 LIST "" *
* LIST (\HasNoChildren) "/" Archive
[...]
* LIST (\HasNoChildren) "/" Tasks
A01 OK LIST completed.
Logout and cleanup sessions.
COMMENTAIRES : Executing command -- A01 Logout
* BYE Microsoft Exchange Server IMAP4 server signing off.

Connaitre l'ObjectId d'un utilisateur 


Il est possible d'afficher l'ensemble des données de définition d'un utilisateur Microsoft 365 (PowerShell) : 

Install-Module MSOnline
Connect-MsolService                               ( ici se connecter via le compte d'administration )
Get-MsolUser                                      ( affiche la liste des utilisateurs )
Get-MsolUser -UserPrincipalName "utilisateur@video.nativip.com" | Format-List *

affiche les différents paramètres dont l'Object Id.