Authentifier une application EWS à l’aide d’OAuth

  • Article

Apprendre à utiliser l’authentification OAuth avec vos applications EWS Managed API.

Vous pouvez utiliser le service d’authentification OAuth fourni par Microsoft Entra pour permettre à vos applications API managées EWS d’accéder à Exchange Online dans Office 365. Pour utiliser OAuth avec votre application, vous devrez :

  1. Inscrivez votre application auprès de Microsoft Entra.
  2. Ajouter un code pour obtenir un jeton d’authentification afin d’obtenir un jeton d’authentification à partir d’un serveur de jetons.
  3. Ajouter un jeton d’authentification aux demandes EWS que vous envoyez.

Remarque

L’authentification OAuth pour EWS est disponible uniquement dans Exchange dans le cadre d’Office 365. Les applications EWS qui utilisent OAuth doivent être inscrites auprès de Microsoft Entra.

Pour utiliser le code dans cet article, vous devrez avoir accès aux éléments suivants :

Deux types d’autorisations OAuth peuvent être utilisés pour accéder aux API EWS dans Exchange Online. Avant de commencer le tutoriel, vous devrez choisir le type de permission spécifique à utiliser.

  • Des autorisations déléguées sont utilisées par les applications qui ont un utilisateur connecté. Pour ces applications, l’utilisateur ou un administrateur consent aux autorisations demandées par l’application, et l’application peut agir en tant qu’utilisateur connecté lors des appels API.
  • Des autorisations d’application sont utilisées par les applications qui s’exécutent sans utilisateur connecté ; par exemple, les applications qui s’exécutent en tant que démons ou services d’arrière-plan et qui peuvent accéder à plusieurs boîtes aux lettres.

Inscription de votre application

Pour utiliser OAuth, une application doit avoir un ID d’application émis par Microsoft Entra. Dans ce tutoriel, il est supposé que l’application est une application console. Vous devez donc inscrire votre application en tant que client public avec Microsoft Entra. Vous pouvez inscrire une application dans le centre d'administration Microsoft Entra ou à l’aide de Microsoft Graph.

  1. Ouvrez un navigateur et accédez au centre d'administration Microsoft Entra et connectez-vous à l’aide d’un compte professionnel ou scolaire.

  2. Sélectionnez Identité dans le volet de navigation de gauche, puis sélectionnez inscriptions d'applications sous Applications.

  3. Sélectionnez Nouvelle inscription. Sur la page Inscrire une application, définissez les valeurs comme suit.

    • Définissez Nompour un nom convivial de votre application.
    • Définissez types de comptes pris en charge pour le choix adapté à votre scénario.
    • Pour Rediriger URI, remplacez la liste déroulante par client public (mobile & bureau) et définissez la valeur sur https://login.microsoftonline.com/common/oauth2/nativeclient.

  4. Choisissez Inscrire. Sur la page Application console Graph, copiez les valeurs de l’ID de l’application (client) et de l’ID du répertoire (client) ; vous en aurez besoin plus loin dans cet exercice.

Remarque

Les développeurs peuvent se connecter avec un compte professionnel ou scolaire pour inscrire une application dans un répertoire d’ID Entra, ou se connecter avec un compte personnel (MSA) qui est un invité dans un répertoire Entra ID. Si les développeurs n’ont pas de répertoire d’ID Entra, ils peuvent en obtenir un gratuitement auprès du programme développeur M365.

Configurer pour l’authentification déléguée

Si votre application utilise l’authentification déléguée, aucune configuration ultérieure n’est requise. La Platforme d’identites Microsoft pour développeurs permet aux applications de demander des autorisations de façon dynamique, de sorte que vous n’avez pas à configurer préalablement les autorisations sur l’inscription de l’application. Toutefois, dans certains scénarios (par exemples, au nom du flux), la configuration préalable des autorisations est requise. Suivez les étapes ci-dessous pour préconfigurer les autorisations EWS.

  1. Sélectionnez Autorisations de l’API dans le volet de navigation gauche sous Gérer.

  2. Recherchez la propriété requiredResourceAccess dans le manifeste, puis ajoutez les éléments suivants à l’intérieur des crochets ([]) :

    {
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5",
            "type": "Scope"
        }
    ]
}

  3. Sélectionnez Enregistrer.

  4. Sélectionnez Autorisations de l’API dans le volet de navigation gauche sous Gérer. Vérifiez que l’autorisation EWS.AccessAsUser.All est répertoriée.

Configurer pour l’authentification de l’application uniquement

Pour utiliser les autorisations des applications, suivez ces étapes supplémentaires.

  1. Sélectionnez Autorisations de l’API dans le volet de navigation gauche sous Gérer.

  2. Recherchez la propriété requiredResourceAccess dans le manifeste, puis ajoutez les éléments suivants à l’intérieur des crochets ([]) :

    {
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",
            "type": "Role"
        }
    ]
}

  3. Sélectionnez Enregistrer.

  4. Sélectionnez Autorisations de l’API dans le volet de navigation gauche sous Gérer. Vérifiez que l’autorisation full_access_as_app est répertoriée.

  5. Sélectionnez Accorder l’autorisation d’administrateur pour l'entreprise puis acceptez la boîte de dialogue de consentement.

  6. Sélectionnez Certificats et clés secrètes dans le volet de navigation gauche sous Gérer.

  7. Sélectionnez Secret nouveau client, entrez une courte description, puis sélectionnez Ajouter.

  8. Copiez la Valeur du nouveau secret client ajouté et enregistrez-le. vous en aurez besoin plus tard.

Ajouter un code pour obtenir un jeton d’authentification

Les extraits de code suivants montrent comment utiliser la bibliothèque d’authentification Microsoft pour obtenir des jetons d’authentification pour les autorisations déléguées et les autorisations d’application. Ces extraits de code partent du principe que les informations requises pour effectuer la demande d’authentification sont stockées dans le fichier App. config de l’application. Ces exemples ne comprennent pas la vérification des erreurs, voir les exemples de code pour le code complet.

Obtenir un jeton avec l’authentification déléguée

// Using Microsoft.Identity.Client 4.22.0

// Configure the MSAL client to get tokens
var pcaOptions = new PublicClientApplicationOptions
{
    ClientId = ConfigurationManager.AppSettings["appId"],
    TenantId = ConfigurationManager.AppSettings["tenantId"]
};

var pca = PublicClientApplicationBuilder
    .CreateWithApplicationOptions(pcaOptions).Build();

// The permission scope required for EWS access
var ewsScopes = new string[] { "https://outlook.office365.com/EWS.AccessAsUser.All" };

// Make the interactive token request
var authResult = await pca.AcquireTokenInteractive(ewsScopes).ExecuteAsync();

Obtenir un jeton avec l’authentification de l’application uniquement

// Using Microsoft.Identity.Client 4.22.0
var cca = ConfidentialClientApplicationBuilder
    .Create(ConfigurationManager.AppSettings["appId"])
    .WithClientSecret(ConfigurationManager.AppSettings["clientSecret"])
    .WithTenantId(ConfigurationManager.AppSettings["tenantId"])
    .Build();

// The permission scope required for EWS access
var ewsScopes = new string[] { "https://outlook.office365.com/.default" };

//Make the token request
var authResult = await cca.AcquireTokenForClient(ewsScopes).ExecuteAsync();

Ajouter un jeton d’authentification aux demandes EWS

Une fois que vous avez reçu l’objet RésultatAuthentification vous pouvez utiliser la propriété duJetond’Accès pour obtenir le jeton émis par le service d’émission de jeton.

// Configure the ExchangeService with the access token
var ewsClient = new ExchangeService();
ewsClient.Url = new Uri("https://outlook.office365.com/EWS/Exchange.asmx");
ewsClient.Credentials = new OAuthCredentials(authResult.AccessToken);

Pour utiliser les autorisations d’application, vous devez également emprunter explicitement une boîte aux lettres à laquelle vous voulez accéder.

//Impersonate the mailbox you'd like to access.
ewsClient.ImpersonatedUserId = new ImpersonatedUserId(ConnectingIdType.SmtpAddress, "test@demotenant.onmicrosoft.com");

Exemples de code

Authentification déléguée

Ce qui suit est l’échantillon de code complet qui démontre qu’une demande EWS authentifiée OAuth utilise les autorisations d’application.

using Microsoft.Exchange.WebServices.Data;
using Microsoft.Identity.Client;
using System;
using System.Configuration;

namespace EwsOAuth
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Using Microsoft.Identity.Client 4.22.0

            // Configure the MSAL client to get tokens
            var pcaOptions = new PublicClientApplicationOptions
            {
                ClientId = ConfigurationManager.AppSettings["appId"],
                TenantId = ConfigurationManager.AppSettings["tenantId"]
            };

            var pca = PublicClientApplicationBuilder
                .CreateWithApplicationOptions(pcaOptions).Build();

            // The permission scope required for EWS access
            var ewsScopes = new string[] { "https://outlook.office365.com/EWS.AccessAsUser.All" };

            try
            {
                // Make the interactive token request
                var authResult = await pca.AcquireTokenInteractive(ewsScopes).ExecuteAsync();

                // Configure the ExchangeService with the access token
                var ewsClient = new ExchangeService();
                ewsClient.Url = new Uri("https://outlook.office365.com/EWS/Exchange.asmx");
                ewsClient.Credentials = new OAuthCredentials(authResult.AccessToken);

                // Make an EWS call
                var folders = ewsClient.FindFolders(WellKnownFolderName.MsgFolderRoot, new FolderView(10));
                foreach(var folder in folders)
                {
                    Console.WriteLine($"Folder: {folder.DisplayName}");
                }
            }
            catch (MsalException ex)
            {
                Console.WriteLine($"Error acquiring access token: {ex}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex}");
            }

            if (System.Diagnostics.Debugger.IsAttached)
            {
                Console.WriteLine("Hit any key to exit...");
                Console.ReadKey();
            }
        }
    }
}

Authentification de l'application uniquement

Ce qui suit est l’échantillon de code complet qui démontre qu’une demande EWS authentifiée OAuth utilise les autorisations d’application.

Remarque

Lorsque vous utilisez l’emprunt d’identité, vous devez toujours utiliser l’en-tête de demande X-AnchorMailbox, qui doit être défini sur le SMTP de la boîte aux lettres empruntée.

using Microsoft.Exchange.WebServices.Data;
using Microsoft.Identity.Client;
using System;
using System.Configuration;

namespace EwsOAuth
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Using Microsoft.Identity.Client 4.22.0
            var cca = ConfidentialClientApplicationBuilder
                .Create(ConfigurationManager.AppSettings["appId"])
                .WithClientSecret(ConfigurationManager.AppSettings["clientSecret"])
                .WithTenantId(ConfigurationManager.AppSettings["tenantId"])
                .Build();

            var ewsScopes = new string[] { "https://outlook.office365.com/.default" };

            try
            {
                var authResult = await cca.AcquireTokenForClient(ewsScopes)
                    .ExecuteAsync();

                // Configure the ExchangeService with the access token
                var ewsClient = new ExchangeService();
                ewsClient.Url = new Uri("https://outlook.office365.com/EWS/Exchange.asmx");
                ewsClient.Credentials = new OAuthCredentials(authResult.AccessToken);
                ewsClient.ImpersonatedUserId =
                    new ImpersonatedUserId(ConnectingIdType.SmtpAddress, "meganb@contoso.onmicrosoft.com");

                //Include x-anchormailbox header
                ewsClient.HttpHeaders.Add("X-AnchorMailbox", "meganb@contoso.onmicrosoft.com");

                // Make an EWS call
                var folders = ewsClient.FindFolders(WellKnownFolderName.MsgFolderRoot, new FolderView(10));
                foreach(var folder in folders)
                {
                    Console.WriteLine($"Folder: {folder.DisplayName}");
                }
            }
            catch (MsalException ex)
            {
                Console.WriteLine($"Error acquiring access token: {ex}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex}");
            }

            if (System.Diagnostics.Debugger.IsAttached)
            {
                Console.WriteLine("Hit any key to exit...");
                Console.ReadKey();
            }
        }
    }
}

Le code échantillon dans les deux cas nécessite un fichier App.config avec les entrées suivantes :

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
  <appSettings>
    <!-- The application ID from your app registration -->
    <add key="appId" value="YOUR_APP_ID_HERE" />
    <!-- The tenant ID copied from your app registration -->
    <add key="tenantId" value="YOUR_TENANT_ID_HERE"/>
    <!-- The application's client secret from your app registration. Needed for application permission access -->
    <add key="clientSecret" value="YOUR_CLIENT_SECRET_HERE"/>
  </appSettings>
</configuration>

Voir aussi