Autenticar una aplicación EWS mediante OAuth

  • Artículo

Obtenga información sobre cómo usar la autenticación OAuth con las aplicaciones de la API administrada de EWS.

Puede usar el servicio de autenticación de OAuth proporcionado por Microsoft Entra para permitir que las aplicaciones de api administrada de EWS accedan a Exchange Online en Office 365. Para usar OAuth con la aplicación tendrá que:

  1. Registre la aplicación con Microsoft Entra.
  2. Agregar código para obtener un token de autenticación para obtener un token de autenticación de un servidor de tokens.
  3. Agregar un token de autenticación a las solicitudes de EWS que envíe.

Nota:

La autenticación OAuth para EWS solo está disponible en Exchange como parte de Microsoft 365. Las aplicaciones de EWS que usan OAuth deben registrarse con Microsoft Entra.

Para usar el código de este artículo, tendrá que tener acceso a lo siguiente:

Hay dos tipos de permisos OAuth que se pueden usar para obtener acceso a las API de EWS en Exchange Online. Antes de continuar con el tutorial, tendrá que seleccionar el tipo de permiso específico que desea usar.

  • Los permisos delegados los usan las aplicaciones en las que un usuario debe haber iniciado sesión. En estas aplicaciones, el usuario o un administrador dan su consentimiento a los permisos que solicita la aplicación, y la aplicación puede actuar como un usuario que ha iniciado sesión cuando se hacen llamadas de API.
  • Los permisos de aplicación son los que usan las aplicaciones que se ejecutan sin que un usuario haya iniciado sesión, como las aplicaciones que se ejecutan como servicios en segundo plano o demonios y que pueden acceder a varios buzones.

Registrar su aplicación

Para usar OAuth, una aplicación debe tener un identificador de aplicación emitido por Microsoft Entra. En este tutorial, se supone que la aplicación es una aplicación de consola, por lo que debe registrar la aplicación como cliente público con Microsoft Entra. Puede registrar una aplicación en el Centro de administración Microsoft Entra o mediante Microsoft Graph.

  1. Abra un explorador y vaya al Centro de administración Microsoft Entra e inicie sesión con una cuenta profesional o educativa.

  2. Seleccione Identidad en el panel de navegación izquierdo y, a continuación, seleccione Registros de aplicaciones en Aplicaciones.

  3. Seleccione Nuevo registro. En la página Registrar una aplicación, establezca los valores siguientes.

    • Establezca Nombre como un nombre descriptivo para la aplicación.
    • Configure Tipos de cuenta compatibles de manera adecuada para su escenario.
    • Para URI de redirección, cambie la lista desplegable a Cliente público (dispositivo móvil y escritorio) y establezca el valor en https://login.microsoftonline.com/common/oauth2/nativeclient.

  4. Elija Registrar. En la página siguiente, copie los valores del Id. de la aplicación (cliente) y del Id. del directorio (cuenta empresarial) y guárdelos; los necesitará más adelante.

Nota:

Los desarrolladores pueden iniciar sesión con una cuenta profesional o educativa para registrar una aplicación en un directorio de Id. de entra o iniciar sesión con una cuenta personal (MSA) que sea un invitado en un directorio de Id. de entra. Si los desarrolladores no tienen un directorio Entra ID, pueden obtener uno gratis del Programa para desarrolladores M365.

Configurar para la autenticación delegada

Si la aplicación usa una autenticación delegada, no es necesario realizar ninguna configuración adicional. La Plataforma de identidad de Microsoft permite que las aplicaciones soliciten permisos de forma dinámica, por lo que no es necesario que configure previamente los permisos en el registro de la aplicación. Sin embargo, en algunos casos (como en el del flujo con derechos delegados) se necesitan permisos para la configuración previa. Siga los siguientes pasos para configurar previamente los permisos de EWS.

  1. Seleccione Manifiesto en el panel de navegación izquierdo, debajo de Administrar.

  2. Localice la propiedad requiredResourceAccess en el manifiesto y agregue lo siguiente dentro de los corchetes ([]):

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

  3. Seleccione Guardar.

  4. Seleccione Permisos de las API en Administrar. Confirme que el permiso EWS.AccessAsUser.All aparezca en la lista.

Configurar la autenticación solo para la aplicación

Para usar los permisos de la aplicación, siga estos pasos adicionales.

  1. Seleccione Manifiesto en el panel de navegación izquierdo, debajo de Administrar.

  2. Localice la propiedad requiredResourceAccess en el manifiesto y agregue lo siguiente dentro de los corchetes ([]):

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

  3. Seleccione Guardar.

  4. Seleccione Permisos de las API en Administrar. Confirme que aparezca el permiso full_access_as_app.

  5. Seleccione Conceder consentimiento de administrador para organización y acepte el cuadro de diálogo de consentimiento.

  6. Seleccione Certificados y secretos en el panel de navegación de la parte izquierda, en Administrar.

  7. Seleccione Nuevo secreto de cliente, escriba una descripción breve y seleccione Agregar.

  8. Copie el Valor del secreto de cliente recién agregado y guárdelo, ya que lo necesitará más adelante.

Agregar código para obtener un token de autenticación

Los siguientes fragmentos de código muestran cómo usar la Biblioteca de autenticación de Microsoft para obtener los tokens de autenticación de los permisos delegados y los permisos de aplicación. En estos fragmentos se presupone que la información necesaria para realizar la solicitud de autenticación está almacenada en el archivo App.config de la aplicación. Entre estos ejemplos no se incluyen la comprobación de errores. Consulte los Ejemplos de código para el código completo.

Obtener un token con la autenticación delegada

// 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();

Obtener un token con autenticación solo para la aplicación

// 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();

Agregar un token de autenticación a las solicitudes de EWS

Tras recibir el objeto AuthenticationResult, puede usar la propiedad AccessToken para obtener el token emitido por el servicio de token.

// 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);

Para usar los permisos de la aplicación, también tendrá que suplantar de manera explícita al buzón al que le gustaría acceder.

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

Ejemplos de código

Autenticación delegada

El siguiente es un código de muestra completo que ejemplifica cómo realizar una solicitud EWS autenticada por OAuth usando los permisos delegados de la aplicación.

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();
            }
        }
    }
}

Autenticación solo para la aplicación

El siguiente es un código de muestra completo que ejemplifica cómo realizar una solicitud EWS autenticada por OAuth usando la autenticación solo para la aplicación.

Nota:

Cuando se usa la suplantación, debe usar siempre el encabezado de la solicitud X-AnchorMailbox, el cual debería estar establecido para la dirección SMTP del buzón suplantado.

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();
            }
        }
    }
}

En ambos casos, el ejemplo de código requiere un archivo App.config con las entradas siguientes:

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

Vea también