Szybki start: inicjowanie aplikacji klienckiej (C#)

  • Artykuł

W tym przewodniku Szybki start pokazano, jak zaimplementować wzorzec inicjowania klienta używany przez otokę .NET zestawu MIP SDK w czasie wykonywania.

Uwaga

Kroki opisane w tym przewodniku Szybki start są wymagane dla każdej aplikacji klienckiej korzystającej z zestawów SDK plików, zasad lub ochrony otoki programu MIP .NET. Mimo że w tym przewodniku Szybki start pokazano użycie zestawów SDK plików, ten sam wzorzec ma zastosowanie do klientów korzystających z zestawów SDK zasad i ochrony. Przyszłe przewodniki Szybki start powinny być wykonywane szeregowo, ponieważ każda z nich opiera się na poprzednim, a ten jest pierwszym. Ten kod ma na celu pokazanie, jak rozpocząć pracę z zestawem MIP SDK i nie jest przeznaczony do użytku produkcyjnego.

Wymagania wstępne

Jeśli jeszcze tego nie zrobiono, upewnij się, że:

  • Wykonaj kroki opisane w artykule Konfiguracja i konfiguracja zestawu SDK usługi Microsoft Information Protection (MIP). Ten przewodnik Szybki start "Inicjowanie aplikacji klienckiej" opiera się na odpowiedniej konfiguracji i konfiguracji zestawu SDK.
  • Opcjonalnie:
    • Przejrzyj obiekty profilu i aparatu. Obiekty profilu i aparatu są uniwersalnymi pojęciami wymaganymi przez klientów korzystających z zestawów SDK plików/zasad/ochrony miP.
    • Zapoznaj się z pojęciami dotyczącymi uwierzytelniania, aby dowiedzieć się, jak uwierzytelnianie i zgoda są implementowane przez zestaw SDK i aplikację kliencą.

Tworzenie rozwiązania i projektu programu Visual Studio

Najpierw utworzymy i skonfigurujemy początkowe rozwiązanie i projekt programu Visual Studio, na którym zostaną utworzone inne przewodniki Szybki start.

  1. Otwórz program Visual Studio 2019, wybierz menu Plik , Nowy, Projekt. W oknie dialogowym Nowy projekt:

    • W okienku po lewej stronie w obszarze Zainstalowane, Visual C# wybierz pozycję Pulpit systemu Windows.

    • W środkowym okienku wybierz pozycję Aplikacja konsolowa (.NET Framework)

    • W dolnym okienku zaktualizuj odpowiednio nazwę projektu, lokalizację i nazwę rozwiązania zawierającego.

    • Po zakończeniu kliknij przycisk OK w prawym dolnym rogu.

      Visual Studio solution creation

  2. Dodaj pakiet Nuget dla zestawu MIP File SDK do projektu:

    • W Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł projektu (bezpośrednio pod węzłem góry/rozwiązania), a następnie wybierz pozycję Zarządzaj pakietami NuGet...:
    • Po otwarciu karty Menedżer pakietów NuGet w obszarze karty Grupa edytora:
      • Wybierz przycisk Przeglądaj.
      • Wprowadź ciąg "Microsoft.InformationProtection" w polu wyszukiwania.
      • Wybierz pakiet "Microsoft.InformationProtection.File".
      • Kliknij przycisk "Zainstaluj", a następnie kliknij przycisk "OK", gdy zostanie wyświetlone okno dialogowe potwierdzenia podglądu .

  3. Powtórz powyższe kroki, aby dodać pakiet zestawu MIP File SDK, ale zamiast tego dodaj do aplikacji ciąg "Microsoft.Identity.Client".

Implementowanie delegata uwierzytelniania

Zestaw MIP SDK implementuje uwierzytelnianie przy użyciu rozszerzalności klas, co zapewnia mechanizm udostępniania pracy uwierzytelniania z aplikacją kliencką. Klient musi uzyskać odpowiedni token dostępu OAuth2 i udostępnić zestaw MIP SDK w czasie wykonywania.

Teraz utwórz implementację delegata uwierzytelniania, rozszerzając interfejs zestawu SDK Microsoft.InformationProtection.IAuthDelegate i przesłaniając/implementując funkcję wirtualną IAuthDelegate.AcquireToken() . Delegat uwierzytelniania jest tworzone i używane później przez FileProfile obiekty i FileEngine .

  1. Kliknij prawym przyciskiem myszy nazwę projektu w programie Visual Studio, wybierz pozycję Dodaj, a następnie pozycję Klasa.

  2. Wprowadź ciąg "AuthDelegateImplementation" w polu Nazwa . Kliknij pozycję Dodaj.

  3. Dodaj instrukcje using dla biblioteki Microsoft Authentication Library (MSAL) i biblioteki MIP:

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

  4. Ustaw AuthDelegateImplementation wartość , aby dziedziczyć Microsoft.InformationProtection.IAuthDelegate i implementować zmienną Microsoft.InformationProtection.ApplicationInfo prywatną i konstruktor, który akceptuje ten sam typ.

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

}

    Obiekt ApplicationInfo zawiera trzy właściwości. Element _appInfo.ApplicationId zostanie użyty w AuthDelegateImplementation klasie , aby podać identyfikator klienta do biblioteki uwierzytelniania. ApplicationName będą ApplicationVersion udostępniane w raportach usługi Azure Information Protection Analytics.

  5. Dodaj metodę public string AcquireToken() . Ta metoda powinna akceptować Microsoft.InformationProtection.Identity i trzy ciągi: adres URL urzędu, identyfikator URI zasobu i oświadczenia, jeśli jest to wymagane. Te zmienne ciągu zostaną przekazane do biblioteki uwierzytelniania przez interfejs API i nie powinny być manipulowane. Wprowadź identyfikator GUID dzierżawy z witryny Azure Portal dla dzierżawy. Edytowanie ciągów innych niż identyfikator GUID dzierżawy może spowodować niepowodzenie uwierzytelniania.

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

Teraz utwórz implementację delegata zgody, rozszerzając interfejs zestawu SDK Microsoft.InformationProtection.IConsentDelegate i przesłaniając/implementując GetUserConsent()element . Pełnomocnik zgody jest tworzone i używane później przez obiekty Profil pliku i Aparat plików. Pełnomocnik zgody jest dostarczany z adresem usługi, za pomocą których użytkownik musi wyrazić zgodę na użycie w parametrze url . Delegat powinien ogólnie zapewnić przepływ, który umożliwia użytkownikowi akceptowanie lub odrzucanie zgody na dostęp do usługi. W tym przewodniku Consent.AcceptSzybki start kod twardy.

  1. Korzystając z tej samej funkcji "Dodaj klasę" programu Visual Studio, której użyliśmy wcześniej, dodaj kolejną klasę do projektu. Tym razem wprowadź ciąg "ConsentDelegateImplementation" w polu Nazwa klasy.

  2. Teraz zaktualizuj plik ConsentDelegateImpl.cs , aby zaimplementować nową klasę delegata zgody. Dodaj instrukcję using dla Microsoft.InformationProtection klasy i ustaw klasę do dziedziczenia IConsentDelegate.

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

  3. Opcjonalnie spróbuj skompilować rozwiązanie, aby upewnić się, że kompiluje się bez błędów.

Inicjowanie zarządzanej otoki zestawu MIP SDK

  1. W Eksplorator rozwiązań otwórz plik cs w projekcie zawierający implementację Main() metody . Domyślnie ma taką samą nazwę jak projekt zawierający go, który został określony podczas tworzenia projektu.

  2. Usuń wygenerowaną implementację elementu main().

  3. Zarządzana otoka zawiera klasę statyczną używaną Microsoft.InformationProtection.MIP do inicjowania, tworzenia MipContext, ładowania profilów i wydawania zasobów. Aby zainicjować otokę dla operacji zestawu FILE SDK, wywołaj MIP.Initialize()metodę , przekazując polecenie MipComponent.File , aby załadować biblioteki niezbędne do operacji na plikach.

  4. W Main() pliku Program.cs dodaj następujące polecenie, zastępując <ciąg application-id> identyfikatorem utworzonej wcześniej rejestracji aplikacji firmy Microsoft.

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

Konstruowanie profilu pliku i aparatu

Jak wspomniano, obiekty profilów i aparatu są wymagane dla klientów zestawu SDK przy użyciu interfejsów API MIP. Ukończ część kodowania tego przewodnika Szybki start, dodając kod, aby załadować natywne biblioteki DLL, a następnie utworzyć wystąpienie obiektów profilu i aparatu.

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. Zastąp wartości symboli zastępczych w wklejonym kodzie źródłowym, używając następujących wartości:

    Symbol zastępczy Wartość Przykład
    <identyfikator aplikacji> Identyfikator aplikacji Entra firmy Microsoft przypisany do aplikacji zarejestrowanej w sekcji "Konfiguracja i konfiguracja zestawu MIP SDK" (2 wystąpienia). 0edbblll-8773-44de-b87c-b8c6276d41eb
    <przyjazna nazwa> Przyjazna nazwa aplikacji zdefiniowana przez użytkownika. AppInitialization
    <Identyfikator GUID dzierżawy> Identyfikator dzierżawy dla dzierżawy firmy Microsoft Entra TenantID

  2. Teraz wykonaj ostateczną kompilację aplikacji i rozwiąż wszelkie błędy. Kod powinien zostać pomyślnie skompilować.

Następne kroki

Teraz, gdy kod inicjowania został ukończony, możesz przystąpić do następnego przewodnika Szybki start, w którym zaczniesz korzystać z zestawów SDK plików MIP.

Wyświetlanie listy etykiet poufności