Guida introduttiva: Inizializzazione dell'applicazione client (C#)

  • Articolo

Questa guida introduttiva illustra come implementare il modello di inizializzazione client, usato dal wrapper .NET di MIP SDK in fase di esecuzione.

Nota

I passaggi descritti in questa guida introduttiva sono necessari per qualsiasi applicazione client che usa gli SDK file, criteri o protezione del wrapper .NET DI MIP. Anche se questa guida introduttiva illustra l'uso degli SDK di file, questo stesso modello è applicabile ai client che usano gli SDK per criteri e protezione. Le guide introduttive future devono essere eseguite in modo seriale, in quanto ognuna si basa su quella precedente, con questa operazione che rappresenta la prima. Questo codice è progettato per illustrare come iniziare a usare MIP SDK e non è destinato all'uso in produzione.

Prerequisiti

Se non è già stato fatto, assicurarsi di:

  • Completare i passaggi della configurazione e della configurazione di Microsoft Information Protection SDK (MIP). Questa guida introduttiva all'inizializzazione dell'applicazione client si basa sull'installazione e la configurazione appropriate dell'SDK.
  • Facoltativamente:
    • Esaminare gli oggetti profilo e motore. I profili e gli oggetti motore sono concetti universali, richiesti dai client che usano gli SDK di protezione/file/criteri MIP.
    • Vedere Concetti relativi all'autenticazione per informazioni sull'implementazione dell'autenticazione e del consenso da parte dell'SDK e dell'applicazione client.

Creare una soluzione e un progetto di Visual Studio

Prima di tutto viene creata e configurata la soluzione e il progetto iniziale di Visual Studio, in base ai quali verranno compilati gli altri argomenti di avvio rapido.

  1. Aprire Visual Studio 2019, selezionare il menu File , Nuovo, Progetto. Nella finestra di dialogo Nuovo progetto :

    • Nel riquadro sinistro, in Installato, Visual C#, selezionare Desktop di Windows.

    • Nel riquadro centrale selezionare App console (.NET Framework)

    • Nel riquadro inferiore aggiornare di conseguenza il nome del progetto, il percorso e il nome della soluzione che lo contiene.

    • Al termine, fare clic sul pulsante OK in basso a destra.

      Visual Studio solution creation

  2. Aggiungere il pacchetto Nuget per MIP File SDK al progetto:

    • Nella Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto (direttamente sotto il nodo superiore/soluzione) e selezionare Gestisci pacchetti NuGet...:
    • Quando si apre la scheda Gestione pacchetti NuGet nell'area Schede Gruppo editor:
      • Selezionare Sfoglia.
      • Immettere "Microsoft.InformationProtection" nella casella di ricerca.
      • Selezionare il pacchetto "Microsoft.InformationProtection.File".
      • Fare clic su "Installa", quindi su "OK" quando viene visualizzata la finestra di dialogo di conferma delle modifiche dell'anteprima.

  3. Ripetere i passaggi precedenti per aggiungere il pacchetto MIP File SDK, ma aggiungere "Microsoft.Identity.Client" all'applicazione.

Implementare un delegato di autenticazione

MIP SDK implementa l'autenticazione usando l'estendibilità della classe, che fornisce un meccanismo per condividere l'autenticazione con l'applicazione client. Il client deve acquisire un token di accesso OAuth2 appropriato e fornire all'SDK MIP in fase di esecuzione.

Creare ora un'implementazione per un delegato di autenticazione estendendo l'interfaccia dell'SDK Microsoft.InformationProtection.IAuthDelegate ed eseguendo l'override/implementazione della IAuthDelegate.AcquireToken() funzione virtuale. Il delegato di autenticazione viene creata un'istanza FileProfile e usata in un secondo momento dagli oggetti e FileEngine .

  1. Fare clic con il pulsante destro del mouse sul nome del progetto in Visual Studio, scegliere Aggiungi e quindi Classe.

  2. Immettere "AuthDelegateImplementation" nel campo Nome . Fare clic su Aggiungi.

  3. Aggiungere istruzioni using per Microsoft Authentication Library (MSAL) e la libreria MIP:

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

  4. Impostare AuthDelegateImplementation per ereditare Microsoft.InformationProtection.IAuthDelegate e implementare una variabile privata di Microsoft.InformationProtection.ApplicationInfo e un costruttore che accetta lo stesso tipo.

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

}

    L'oggetto ApplicationInfo contiene tre proprietà. Verrà _appInfo.ApplicationId usato nella AuthDelegateImplementation classe per fornire l'ID client alla libreria di autenticazione. ApplicationName e ApplicationVersion verranno visualizzati nei report di Azure Information Protection Analytics.

  5. Aggiungere il metodo public string AcquireToken(). Questo metodo deve accettare Microsoft.InformationProtection.Identity e tre stringhe: URL dell'autorità, URI della risorsa e attestazioni, se necessario. Queste variabili stringa verranno passate alla libreria di autenticazione dall'API e non devono essere modificate. Immettere il GUID del tenant da portale di Azure per il tenant. La modifica di stringhe diverse dal GUID del tenant potrebbe causare un errore di autenticazione.

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

Creare ora un'implementazione per un delegato di consenso estendendo l'interfaccia dell'SDK e eseguendo l'override/implementazione GetUserConsent()di Microsoft.InformationProtection.IConsentDelegate . Il delegato di consenso viene creata un'istanza e usata in un secondo momento dagli oggetti Profilo file e Motore file. Il delegato di consenso viene fornito con l'indirizzo del servizio a cui l'utente deve fornire il consenso per l'uso nel url parametro . Il delegato deve in genere fornire un flusso che consenta all'utente di accettare o rifiutare il consenso per accedere al servizio. Per questo hardcoded Consent.Acceptdi avvio rapido.

  1. Usando la stessa funzionalità "Aggiungi classe" di Visual Studio usata in precedenza, aggiungere un'altra classe al progetto. Questa volta immettere "ConsentDelegateImplementation" nel campo Nome classe.

  2. Aggiornare ora ConsentDelegateImpl.cs per implementare la nuova classe delegato di consenso. Aggiungere l'istruzione using per Microsoft.InformationProtection e impostare la classe per ereditare IConsentDelegate.

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

  3. Facoltativamente, tentare di compilare la soluzione per assicurarsi che venga compilata senza errori.

Inizializzare il wrapper gestito di MIP SDK

  1. Da Esplora soluzioni aprire il file con estensione cs nel progetto che contiene l'implementazione del Main() metodo . Per impostazione predefinita, il nome del progetto che lo contiene è stato specificato durante la creazione del progetto.

  2. Rimuovere l'implementazione generata di main().

  3. Il wrapper gestito include una classe statica, Microsoft.InformationProtection.MIP usata per l'inizializzazione, la creazione di un MipContext, il caricamento di profili e il rilascio di risorse. Per inizializzare il wrapper per le operazioni di File SDK, chiamare MIP.Initialize(), passando MipComponent.File per caricare le librerie necessarie per le operazioni sui file.

  4. In Main() Program.cs aggiungere quanto segue, sostituendo <application-id> con l'ID della registrazione dell'applicazione Microsoft Entra creata in precedenza.

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

Costruire un profilo e un motore di file

Come accennato, gli oggetti profilo e motore sono necessari per i client SDK che usano le API MIP. Completare la parte di scrittura del codice di questa guida introduttiva aggiungendo il codice per caricare le DLL native, quindi creare un'istanza degli oggetti profilo e motore.

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. Sostituire i valori segnaposto nel codice sorgente incollato usando i valori seguenti:

    Segnaposto Valore Esempio
    <application-id> ID applicazione Microsoft Entra assegnato all'applicazione registrata in "Configurazione e configurazione di MIP SDK" (2 istanze). 0edbblll-8773-44de-b87c-b8c6276d41eb
    <friendly-name> Nome descrittivo definito dall'utente per l'applicazione. AppInitialization
    <TENANT-GUID> ID tenant per il tenant di Microsoft Entra TenantID

  2. A questo punto, eseguire una compilazione finale dell'applicazione e risolvere eventuali errori. Il codice dovrebbe essere compilato correttamente.

Passaggi successivi

Ora che il codice di inizializzazione è completo, si è pronti per la guida introduttiva successiva, in cui si inizierà a sperimentare gli SDK di file MIP.

Elencare le etichette di riservatezza