Schnellstart: Initialisieren von Clientanwendungen (C#)

In diesem Schnellstart erfahren Sie, wie Sie das Muster für die Clientinitialisierung implementieren, das vom .NET-Wrapper für das MIP SDK zur Laufzeit verwendet wird.

Voraussetzungen

Falls noch nicht geschehen, sorgen Sie für Folgendes:

• Führen Sie die Schritte unter Microsoft Information Protection (MIP) SDK: Setup und Konfiguration aus. Dieser Schnellstart „Initialisieren von Clientanwendungen“ basiert auf der ordnungsgemäßen Einrichtung und Konfiguration des SDK.
• Optional:
  • Informieren Sie sich über Profil- und Engine-Objekte. Bei Profil- und Engine-Objekten handelt es sich um universelle Konzepte, die von Clients benötigt werden, die das File SDK, das Policy SDK oder das Protection SDK von MIP verwenden.
  • Lesen Sie die Authentifizierungskonzepte, um zu erfahren, wie die Authentifizierung und die Einwilligung vom SDK und der Clientanwendung implementiert werden.

Erstellen einer Visual Studio-Projektmappe und eines -Projekts

Zunächst erstellen und konfigurieren Sie die erste Projektmappe und das erste Projekt in Visual Studio. Diese bilden die Grundlage für die anderen Schnellstarts.

1. Öffnen Sie Visual Studio 2019, und wählen Sie das Menü Datei, anschließend Neu und dann Projekt aus. Geben Sie im Dialogfeld Neues Projekt Folgendes ein:

   • Wählen Sie im linken Bereich unter Installiert, Visual C# die Option Windows Desktop aus.

   • Wählen Sie im mittleren Bereich Konsolen-App (.NET Framework) aus

   • Aktualisieren Sie im unteren Bereich Name, Speicherort und den darin enthaltenen Projektmappennamen des Projekts.

   • Wenn Sie fertig sind, klicken Sie rechts unten auf die Schaltfläche OK.

     

2. Fügen Sie Ihrem Projekt das NuGet-Paket für das MIP File SDK hinzu:

   • Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten (direkt unter dem obersten Knoten bzw. dem Projektmappenknoten), und wählen Sie NuGet-Pakete verwalten… aus:
   • Gehen Sie wie folgt vor, wenn im Bereich „Editor-Gruppe“ die Registerkarte NuGet-Paket-Manager geöffnet wird:
     • Wählen Sie Durchsuchen aus.
     • Geben Sie „Microsoft.InformationProtection“ in das Suchfeld ein.
     • Wählen Sie das Paket „Microsoft.InformationProtection.File“ aus.
     • Klicken Sie auf „Installieren“ und anschließend auf „OK“, wenn das Bestätigungsdialogfeld Vorschau der Änderungen anzeigen angezeigt wird.

3. Wiederholen Sie die oben aufgeführten Schritte, um das Paket für das MIP File SDK hinzuzufügen, aber fügen Sie der Anwendung „Microsoft.Identity.Clients“ hinzu.

Implementieren eines Authentifizierungsdelegaten

Das MIP SDK implementiert die Authentifizierung mithilfe der Klassenerweiterbarkeit, die einen Mechanismus zur Freigabe der Authentifizierung für die Clientanwendung bietet. Der Client muss ein geeignetes OAuth2-Zugriffstoken abrufen und dem MIP SDK zur Laufzeit bereitstellen.

Erstellen Sie nun eine Implementierung für einen Authentifizierungsdelegaten, indem Sie die Microsoft.InformationProtection.IAuthDelegate-Schnittstelle des SDK erweitern und die virtuelle IAuthDelegate.AcquireToken()-Funktion überschreiben bzw. implementieren. Der Authentifizierungsdelegat wird später von den Objekten FileProfile und FileEngine instanziiert und verwendet.

1. Klicken Sie in Visual Studio mit der rechten Maustaste auf den Projektnamen, und wählen Sie anschließend Hinzufügen und dann Klasse aus.

2. Geben Sie im Feld Name „AuthDelegateImplementation“ ein. Klicken Sie auf Hinzufügen.

3. Fügen Sie using-Anweisungen für die Microsoft Authentication Library (MSAL) und die MIP-Bibliothek hinzu:

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

4. Legen Sie AuthDelegateImplementation darauf fest, von Microsoft.InformationProtection.IAuthDelegate zu erben und eine private Variable von Microsoft.InformationProtection.ApplicationInfo sowie einen Konstruktor zu implementieren, der den gleichen Dateityp akzeptiert.

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

   Das ApplicationInfo-Objekt enthält drei Eigenschaften. _appInfo.ApplicationId wird in der AuthDelegateImplementation-Klasse verwendet, um der Authentifizierungsbibliothek die Client-ID bereitzustellen. ApplicationName und ApplicationVersion werden in Azure Information Protection-Analyseberichten aufgeführt.

5. Fügen Sie die public string AcquireToken()-Methode hinzu. Diese Methode akzeptiert Microsoft.InformationProtection.Identity und drei Zeichenfolgen: Autoritäts-URL, Ressourcen-URI und Ansprüche (sofern erforderlich). Diese Zeichenfolgenvariablen werden über die API an die Authentifizierungsbibliothek übergeben und sollten nicht geändert werden. Geben Sie eine Mandanten-GUID aus dem Azure-Portal für Ihren Mandanten ein. Das Bearbeiten von anderen Zeichenfolgen als der Mandanten-GUID kann zu einem Authentifizierungsfehler führen.

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

Implementieren eines Einwilligungsdelegaten

Erstellen Sie nun eine Implementierung für einen Einwilligungsdelegaten, indem Sie die Microsoft.InformationProtection.IConsentDelegate-Schnittstelle des SDK erweitern und GetUserConsent() überschreiben bzw. implementieren. Der Einwilligungsdelegat wird später von den File-Profil- und File-Engine-Objekten instanziiert und verwendet. Der Einwilligungsdelegat enthält im url-Parameter die Adresse des Diensts, dessen Aufruf die Benutzer*innen zustimmen müssen. Der Delegat sollte einen Flow enthalten, durch den Benutzer*innen dem Zugriff auf den Dienst zustimmen oder diesen ablehnen können. Hartcodieren Sie Consent.Accept für diesen Schnellstart.

1. Fügen Sie mit der gleichen Visual Studio-Funktion „Klasse hinzufügen“, die Sie vorher verwendet haben, Ihrem Projekt eine weitere Klasse hinzu. Geben Sie dieses Mal „ConsentDelegateImplementation“ in das Feld Klassenname ein.

2. Aktualisieren Sie jetzt ConsentDelegateImpl.cs, damit Ihre neue Einwilligungsdelegatklasse implementiert wird. Fügen Sie die using-Anweisung für Microsoft.InformationProtection hinzu, und legen Sie die Klasse so fest, dass sie von IConsentDelegate erbt.

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

3. Sie können optional versuchen, die Projektmappe zu erstellen, um sicherzustellen, dass diese fehlerfrei kompiliert wird.

Initialisieren des verwalteten Wrappers des MIP SDK

1. Öffnen Sie im Projektmappen-Explorer die CS-Datei im Projekt, die die Implementierung der Main()-Methode enthält. Standardmäßig weist sie denselben Namen wie das Projekt auf, in dem sie enthalten ist. Diesen Namen haben Sie bei der Projekterstellung angegeben.

2. Entfernen Sie die generierte Implementierung von main().

3. Der verwaltete Wrapper enthält eine statische Klasse (Microsoft.InformationProtection.MIP), die für die Initialisierung, das Erstellen eines MipContext, das Laden von Profilen und das Freigeben von Ressourcen verwendet wird. Zum Initialisieren des Wrappers für File SDK-Vorgänge rufen Sie MIP.Initialize() auf und übergeben MipComponent.File, um die erforderlichen Bibliotheken für Dateivorgänge zu laden.

4. Fügen Sie in Main() in der Datei Program.cs folgenden Codeausschnitt hinzu. Ersetzen Sie <application-id> dabei durch die ID der Azure AD-Anwendungsregistierung, die Sie zuvor erstellt haben.

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

Erstellen eines File-Profils und einer File-Engine

Wie bereits erwähnt sind für SDK-Clients, die MIP-APIs verwenden, Profil- und Engine-Objekte erforderlich. Vervollständigen Sie den Codeabschnitt dieses Schnellstarts, indem Sie Code hinzufügen, um die nativen DLLs zu laden und anschließend die Profil- und Engine-Objekte zu instanziieren.

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

3. Ersetzen Sie die Platzhalterwerte in dem von Ihnen eingefügten Quellcode durch die folgenden Werte:

   Platzhalter	Wert	Beispiel
   <application-id>	Die ID der Azure AD-Anwendung wird der unter „MIP SDK: Setup und Konfiguration“ registrierten Anwendung zugewiesen (2 Instanzen).	0edbblll-8773-44de-b87c-b8c6276d41eb
   <friendly-name>	Ein benutzerdefinierter Anzeigename für Ihre Anwendung.	AppInitialization
   <Tenant-GUID>	Die Mandanten-ID Ihres Microsoft Entra-Mandanten ab.	TenantID

4. Stellen Sie nun die Anwendung endgültig fertig, und beheben Sie etwaige Fehler. Der Code sollte erfolgreich erstellt werden.

Nächste Schritte

Da Ihr Initialisierungscode nun vollständig ist, können Sie mit dem nächsten Schnellstart fortfahren. Darin erfahren Sie mehr über die MIP File SDKs.