Inicio rápido: Inicialización de la aplicación cliente (C#)

  • Artículo

Esta guía de inicio rápido le mostrará cómo implementar el patrón de inicialización del cliente, que usa el contenedor .NET del SDK de MIP en tiempo de ejecución.

Nota:

Los pasos descritos en este inicio rápido son necesarios para cualquier aplicación cliente que use los SDK de protección, directivas o archivos del contenedor .NET de MIP. Aunque en este inicio rápido se muestra el uso de los SDK de archivos, este mismo patrón se aplica a los clientes que usan los SDK de directivas y protección. Los inicios rápidos futuros deben realizarse en serie, ya que cada uno se basa en el anterior, siendo este el primero. Este código está pensado para demostrar cómo empezar a trabajar con el SDK de MIP y no está destinado a su uso en producción.

Requisitos previos

Si aún no lo ha hecho:

Creación de una solución y un proyecto de Visual Studio

En primer lugar, se crearán y configurarán la solución y el proyecto iniciales de Visual Studio, en los que se basan los demás inicios rápidos.

  1. Abra Visual Studio 2019, seleccione el menú Archivo y después Nuevo y Proyecto. En el cuadro de diálogo Nuevo proyecto:

    • En el panel de la izquierda, en Instalados, Visual C#, seleccione Escritorio de Windows.

    • En el panel del centro, seleccione Aplicación de consola (.NET Framework).

    • En el panel inferior, actualice el Nombre y la Ubicación del proyecto, y el Nombre de la solución en la que se incluye, según corresponda.

    • Cuando termine, haga clic en el botón Aceptar en la esquina inferior derecha.

      Visual Studio solution creation

  2. Agregue el paquete Nuget para el SDK de archivos de MIP al proyecto:

    • En el Explorador de soluciones, haga clic con el botón derecho en el nodo del proyecto (directamente debajo del nodo principal o de la solución) y seleccione Administrar paquetes NuGet…:
    • Cuando se abra la pestaña Administrador de paquetes NuGet en el área de pestañas del grupo de editores:
      • Seleccione Examinar.
      • Escriba "Microsoft.InformationProtection" en el cuadro de búsqueda.
      • Seleccione el paquete "Microsoft.InformationProtection.File".
      • Haga clic en "Instalar" y después en "Aceptar" cuando se muestre el cuadro de diálogo de confirmación Vista previa de los cambios.

  3. Repita los pasos anteriores para agregar el paquete del SDK de archivo de MIP, pero en su lugar agregue "Microsoft.Identity.Client" a la aplicación.

Implementación de un delegado de autenticación

El SDK de MIP implementa la autenticación mediante la extensibilidad de clases, que proporciona un mecanismo para compartir el trabajo de autenticación con la aplicación cliente. El cliente debe adquirir un token de acceso de OAuth2 adecuado y proporcionarlo al SDK de MIP en tiempo de ejecución.

Ahora creará una implementación para un delegado de autenticación, mediante la interfaz Microsoft.InformationProtection.IAuthDelegate del SDK y el reemplazo e implementación de la función virtual IAuthDelegate.AcquireToken(). Se crea una instancia del delegado de autenticación y los objetos FileProfile y FileEngine la usan más adelante.

  1. Haga clic con el botón derecho en el nombre del proyecto en Visual Studio, seleccione Agregar y, a continuación, Clase.

  2. Escriba "AuthDelegateImplementation" en el campo Nombre. Haga clic en Agregar.

  3. Agregue instrucciones Using para la biblioteca de autenticación de Microsoft (MSAL) y la biblioteca de MIP:

    using Microsoft.InformationProtection;
using Microsoft.Identity.Client;

  4. Establezca que AuthDelegateImplementation herede Microsoft.InformationProtection.IAuthDelegate e implemente una variable privada de Microsoft.InformationProtection.ApplicationInfo y un constructor que acepte el mismo tipo.

    public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}

    El objeto ApplicationInfo contiene tres propiedades. _appInfo.ApplicationId se usará en la clase AuthDelegateImplementation para proporcionar el identificador de cliente a la biblioteca de autenticación. ApplicationName y ApplicationVersion aparecerán en los informes de Azure Information Protection Analytics.

  5. Agregue el método public string AcquireToken(). Este método debe aceptar Microsoft.InformationProtection.Identity y tres cadenas: dirección URL de autoridad, URI de recursos y notificaciones, si es necesario. La API pasará estas variables de cadena a la biblioteca de autenticación y no se deben manipular. Introduzca el GUID de inquilino de Azure Portal para su inquilino. Editar las cadenas que no son el GUID de inquilino puede provocar un error de autenticación.

    public string AcquireToken(Identity identity, string authority, string resource, string claims)
{
   var authorityUri = new Uri(authority);
   authority = String.Format("https://{0}/{1}", authorityUri.Host, "<Tenant-GUID>");

   _app = PublicClientApplicationBuilder.Create(_appInfo.ApplicationId).WithAuthority(authority).WithDefaultRedirectUri().Build();
   var accounts = (_app.GetAccountsAsync()).GetAwaiter().GetResult();

   // Append .default to the resource passed in to AcquireToken().
   string[] scopes = new string[] { resource[resource.Length - 1].Equals('/') ? $"{resource}.default" : $"{resource}/.default" };
   var result = _app.AcquireTokenInteractive(scopes).WithAccount(accounts.FirstOrDefault()).WithPrompt(Prompt.SelectAccount)
              .ExecuteAsync().ConfigureAwait(false).GetAwaiter().GetResult();

   return result.AccessToken;
}

Ahora creará una implementación para un delegado de consentimiento, mediante la interfaz Microsoft.InformationProtection.IConsentDelegate de la clase y el reemplazo e implementación de GetUserConsent(). Se crea una instancia del delegado de consentimiento, que después usan los objetos de perfil de archivo y de motor de archivo. El delegado de consentimiento se proporciona con la dirección del servicio al que el usuario debe dar su consentimiento en el parámetro url. Por lo general, el delegado debe proporcionar algún flujo que permita al usuario aceptar o rechazar el consentimiento para acceder al servicio. Para este inicio rápido, codifique de forma rígida Consent.Accept.

  1. Con la misma característica "Agregar clase" de Visual Studio que ha usado antes, agregue otra clase al proyecto. Esta vez, escriba "ConsentDelegateImplementation" en el campo Nombre de clase.

  2. Ahora, actualice ConsentDelegateImpl.cs para implementar la nueva clase de delegado de consentimiento. Agregue la instrucción Using para Microsoft.InformationProtection y establezca la clase para heredar IConsentDelegate.

    class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}

  3. Opcionalmente, intente crear la solución para asegurarse de que se compila sin errores.

Inicialización del contenedor administrado del SDK de MIP

  1. Con el Explorador de soluciones, abra el archivo .cs del proyecto que contiene la implementación del método Main(). De manera predeterminada, tiene el mismo nombre que el proyecto que lo contiene, que especificó al crear el proyecto.

  2. Quite la implementación generada de main().

  3. El contenedor administrado incluye una clase estática, Microsoft.InformationProtection.MIP, que se usa para inicializar, crear MipContext, cargar perfiles y liberar recursos. Para inicializar el contenedor para las operaciones del SDK de archivo, llame a MIP.Initialize(), pasando MipComponent.File para cargar las bibliotecas necesarias para las operaciones de archivo.

  4. En Main(), en Programa.cs, añada lo siguiente, sustituyendo <application-id> por el identificador del registro de aplicaciones de Microsoft Entra creado anteriormente.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.Exceptions;
using Microsoft.InformationProtection.File;
using Microsoft.InformationProtection.Protection;

namespace mip_sdk_dotnet_quickstart
{
    class Program
    {
        private const string clientId = "<application-id>";
        private const string appName = "<friendly-name>";

        static void Main(string[] args)
        {
            //Initialize Wrapper for File SDK operations
            MIP.Initialize(MipComponent.File);
            
        }
    }
}

Creación de un motor y un perfil de archivo

Como ya se mencionó, los objetos de perfil y motor son necesarios para los clientes del SDK que usan las API de MIP. Complete la parte de codificación de esta guía de inicio rápido agregando código para cargar los archivos DLL nativos y, a continuación, cree una instancia de los objetos de perfil y motor.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.File;

namespace mip_sdk_dotnet_quickstart
{
  class Program
  {
       private const string clientId = "<application-id>";
       private const string appName = "<friendly-name>";

       static void Main(string[] args)
       {
            // Initialize Wrapper for File SDK operations.
            MIP.Initialize(MipComponent.File);

            // Create ApplicationInfo, setting the clientID from Microsoft Entra App Registration as the ApplicationId.
            ApplicationInfo appInfo = new ApplicationInfo()
            {
                 ApplicationId = clientId,
                 ApplicationName = appName,
                 ApplicationVersion = "1.0.0"
            };

            // Instantiate the AuthDelegateImpl object, passing in AppInfo.
            AuthDelegateImplementation authDelegate = new AuthDelegateImplementation(appInfo);

            // Create MipConfiguration Object
            MipConfiguration mipConfiguration = new MipConfiguration(appInfo, "mip_data", LogLevel.Trace, false);

            // Create MipContext using Configuration
            MipContext mipContext = MIP.CreateMipContext(mipConfiguration);

            // Initialize and instantiate the File Profile.
            // Create the FileProfileSettings object.
            // Initialize file profile settings to create/use local state.
            var profileSettings = new FileProfileSettings(mipContext,
                                     CacheStorageType.OnDiskEncrypted,
                                     new ConsentDelegateImplementation());

            // Load the Profile async and wait for the result.
            var fileProfile = Task.Run(async () => await MIP.LoadFileProfileAsync(profileSettings)).Result;

            // Create a FileEngineSettings object, then use that to add an engine to the profile.
            // This pattern sets the engine ID to user1@tenant.com, then sets the identity used to create the engine.
            var engineSettings = new FileEngineSettings("user1@tenant.com", authDelegate, "", "en-US");
            engineSettings.Identity = new Identity("user1@tenant.com");

            var fileEngine = Task.Run(async () => await fileProfile.AddEngineAsync(engineSettings)).Result;

            // Application Shutdown
            // handler = null; // This will be used in later quick starts.
            fileEngine = null;
            fileProfile = null;
            mipContext.ShutDown();
            mipContext = null;
       }
  }
}

  1. Reemplace los valores de marcador de posición en el código fuente en el que se pegaron por los valores siguientes:

    Marcador Valor Ejemplo
    <application-id> El identificador de aplicaciones de Microsoft Entra asignado a la aplicación registrada en “Instalación y configuración del SDK de MIP” (2 instancias). 0edbblll-8773-44de-b87c-b8c6276d41eb
    <friendly-name> Nombre descriptivo de la aplicación definido por el usuario. AppInitialization
    <Tenant-GUID> Identificador de inquilino del inquilino de Microsoft Entra TenantID

  2. Ahora realice una compilación final de la aplicación y resuelva los errores. El código debe crearse correctamente.

Pasos siguientes

Ahora que el código de inicialización está completo, ya está listo para el inicio rápido siguiente, en el que empezará a experimentar los SDK de archivos de MIP.

Enumeración de las etiquetas de confidencialidad