Краткое руководство. Инициализация клиентских приложений (C#)

Статья
10/18/2023

В этом кратком руководстве показано, как реализовать шаблон инициализации клиентов, используемый пакетом SDK MIP для оболочки .NET во время выполнения.

Примечание.

Действия, описанные в этом кратком руководстве, применимы к любому клиентскому приложению, использующему пакеты MIP File, Policy и Protection для оболочки .NET. Хотя в этом кратком руководстве показано использование пакетов SDK File, этот же шаблон применим к клиентам, использующим пакеты SDK Policy и Protection. Выполняйте оставшиеся краткие руководства последовательно, так как каждое из них основано на предыдущем, и это первое. Этот код представлен для демонстрации начала работы с пакетом SDK MIP и не предназначен для использования в рабочей среде.

Необходимые компоненты

Обязательно сделайте следующее, если еще этого не сделали:

Выполните действия, описанные в статье Установка и настройка пакета SDK Microsoft Information Protection (MIP). Для работы с кратким руководством "Инициализация клиентских приложений" требуется правильная установка и настройка пакета SDK.
Дополнительно:
- Просмотрите раздел Объекты профиля и подсистемы. Объекты профиля и подсистемы — это универсальные понятия для клиентов, которые используют пакеты SDK MIP File, Policy и Protection.
- Изучите основные понятия проверки подлинности, чтобы узнать, как пакет SDK и клиентское приложение реализуют проверку подлинности и согласие.

Создание решения и проекта Visual Studio

Сначала мы создадим и настроим первоначальное решение и проект Visual Studio, которые будут использоваться при работе с другими краткими руководствами.

В Visual Studio 2019 откройте меню Файл и выберите Создать и Проект. В диалоговом окне Новый проект:
- В области слева в разделе Установленные продукты выберите Visual C# и Рабочий стол Windows.
- В области в центре выберите Консольное приложение (.NET Framework)
- В области внизу обновите значения полей Имя и Расположение для проекта, а также Имя решения.
- Завершив, щелкните ОК внизу справа.
Добавьте пакет Nuget для пакета SDK MIP File в проект:
- В Обозревателе решений щелкните правой кнопкой мыши узел проекта (непосредственно под верхним узлом или узлом решения) и выберите Управление пакетами NuGet:
- Когда откроется вкладка NuGet диспетчер пакетов в области вкладок группы редакторов:
  - Выберите Обзор.
  - Введите Microsoft.InformationProtection в поле поиска.
  - Выберите пакет Microsoft.InformationProtection.File.
  - Когда отобразится диалоговое окно подтверждения Предварительный просмотр изменений, щелкните "Установить" и "ОК".
Повторите эти действия, чтобы добавить пакет SDK MIP File, но вместо этого добавьте Microsoft.Identity.Client в приложение.

Реализация делегата проверки подлинности

Пакет SDK MIP реализует проверку подлинности с использованием расширяемости класса, которая предоставляет механизм совместного использования проверки подлинности с клиентским приложением. Клиент должен получить подходящий маркер доступа OAuth2 и предоставить его пакету SDK MIP во время выполнения.

Теперь создайте реализацию для делегата проверки подлинности, расширив интерфейс Microsoft.InformationProtection.IAuthDelegate пакета SDK и переопределив или реализовав виртуальную функцию IAuthDelegate.AcquireToken(). Экземпляр делегата проверки подлинности позже создается и используется объектами FileProfile и FileEngine.

Щелкните правой кнопкой мыши имя проекта в Visual Studio и выберите Добавить и Класс.
Введите AuthDelegateImplementation в поле Имя. Нажмите кнопку Добавить.
Добавьте операторы using для Библиотеки проверки подлинности Майкрософт (MSAL) и библиотеки MIP:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Настройте AuthDelegateImplementation для наследования Microsoft.InformationProtection.IAuthDelegate и реализуйте закрытую переменную Microsoft.InformationProtection.ApplicationInfo и конструктор, который принимает один и тот же тип.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
Объект ApplicationInfo содержит три свойства. _appInfo.ApplicationId будет использоваться в классе AuthDelegateImplementation для предоставления идентификатора клиента в библиотеке проверки подлинности. ApplicationName и ApplicationVersion будут отображаться в отчетах аналитики Azure Information Protection.

Добавьте метод public string AcquireToken(). Этот метод должен принимать Microsoft.InformationProtection.Identity и три строки: URL-адрес центра, универсальный код ресурса и требования, если это необходимо. Эти строковые переменные будут переданы в библиотеку проверки подлинности с помощью API, и ими нельзя управлять. Введите GUID арендатора с портала Azure для вашего арендатора. Изменение других строк, кроме GUID арендатора, может привести к сбою проверки подлинности.

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

Теперь создайте реализацию для делегата согласия, расширив интерфейс Microsoft.InformationProtection.IConsentDelegate пакета SDK и переопределив или реализовав GetUserConsent(). Экземпляр делегата согласия создается и используется позже объектами профиля и подсистемы File. Делегат согласия предоставляется с адресом службы, на использование которой пользователь должен дать согласие, в параметре url. Делегат должен обычно предоставлять определенный поток, позволяющий пользователю принять или отклонить разрешение на доступ к службе. Для этого краткого руководства включите Consent.Accept в код.

Добавьте в проект еще один класс с помощью той же функции "Добавить класс" в Visual Studio, которая использовалась ранее. В этот раз введите ConsentDelegateImplementation в поле Имя класса.
Теперь обновите ConsentDelegateImpl.cs, чтобы реализовать новый класс делегата согласия. Добавьте заявление об использовании для Microsoft.InformationProtection и настройте класс для наследования IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
(Необязательно.) Вы можете попытаться создать решение, чтобы убедиться в том, что оно компилируется без ошибок.

Инициализация пакета SDK MIP для управляемой оболочки

В Обозревателе решений откройте файл .cs в проекте, содержащем реализацию метода Main(). По умолчанию он имеет то же имя, что и содержащий его проект, который вы указали при создании проекта.
Удалите созданную реализацию main().
У управляемой оболочки есть статический класс Microsoft.InformationProtection.MIP, используемый для инициализации, создания MipContext, загрузки профилей и освобождения ресурсов. Чтобы инициализировать оболочку для операций пакета SDK File, вызовите MIP.Initialize(), передав в MipComponent.File, чтобы загрузить библиотеки, необходимые для работы с файлами.
В Main() Program.cs добавьте следующий код, заменив< идентификатор> приложения идентификатором созданной ранее регистрации приложений Microsoft Entra.

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

Создание профиля и подсистемы File

Как уже упоминалось, для клиентов пакета SDK, использующих API MIP, необходимы объекты профиля и подсистемы. Выполните часть этого краткого руководства, содержащую код, добавив его для загрузки собственных библиотек DLL для создания экземпляров объектов профиля и подсистемы.

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

Замените значения-заполнители в исходном коде, который вы вставили, следующими значениями:

Заполнитель	Значение	Пример
<application-id>	Идентификатор приложения Microsoft Entra, назначенный приложению, зарегистрированным в разделе "Настройка и конфигурация пакета SDK MIP" (2 экземпляра).	0edbblll-8773-44de-b87c-b8c6276d41eb
<friendly-name>	Определенное пользователем понятное имя вашего приложения.	AppInitialization
<Tenant-GUID>	Идентификатор клиента для клиента Microsoft Entra	TenantID

Теперь вы можете выполнить окончательную сборку приложения и устранить все ошибки. Сборка кода должна выполниться успешно.

Дальнейшие действия

Теперь, когда код инициализации написан, вы можете переходить к следующему краткому руководству по началу работы с пакетом SDK MIP File.

Перечисление меток конфиденциальности

Поделиться через

Краткое руководство. Инициализация клиентских приложений (C#)

Необходимые компоненты

Создание решения и проекта Visual Studio

Реализация делегата проверки подлинности

Инициализация пакета SDK MIP для управляемой оболочки

Создание профиля и подсистемы File

Дальнейшие действия

Обратная связь

Дополнительные ресурсы

Поделиться через

Краткое руководство. Инициализация клиентских приложений (C#)

Необходимые компоненты

Создание решения и проекта Visual Studio

Реализация делегата проверки подлинности

Реализация делегата согласия

Инициализация пакета SDK MIP для управляемой оболочки

Создание профиля и подсистемы File

Дальнейшие действия

Обратная связь

Дополнительные ресурсы