Разработка приложения

Статья
07/03/2019

Важно!

Версии пакета SDK службы microsoft Rights Management, выпущенные до марта 2020 г., устарели; Для использования выпуска за март 2020 г. необходимо обновить приложения, использующие более ранние версии. Подробные сведения см. в уведомлении об устаревании.

Для пакета SDK службы Microsoft Rights Management не планируется никаких дополнительных улучшений. Мы настоятельно рекомендуем внедрить пакет SDK Microsoft Information Protection для служб классификации, маркировки и защиты.

В этом примере вы создадите простое консольное приложение, взаимодействующее со службой Azure Information Protection (AIP). Оно будет принимать в качестве входных данных путь к документу, а затем защищать его с помощью специальной политики или шаблона Azure. Затем приложение будет применять нужные политики в соответствии со входными данными, создавая документ с защитой информации. Образец кода, который вы будете использовать, представляет собой тестовое приложение Azure IP, опубликованное в Github.

Предварительные требования для образца приложения

Операционная система: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2 или Windows Server 2012
Язык программирования: C# (.NET Framework 3.0 или более поздней версии)
Среда разработки: Visual Studio 2015 или более поздней версии

Настройка конфигурации Azure

Чтобы настроить Azure для этого приложения, необходимо создать идентификатор клиента, симметричный ключ и идентификатор субъекта приложения.

Настройка клиента Azure AD

Чтобы настроить среду Azure AD для Azure Information Protection, следуйте инструкциям по активации службы защиты из Azure Information Protection.

После активации службы для выполнения последующих действий потребуются компоненты PowerShell. Для этого следуйте инструкциям по администрированию защиты azure Information Protection с помощью PowerShell.

Получение идентификатора клиента

Откройте PowerShell от имени администратора.
Импортируйте модуль RMS: Import-Module AIPService
Подключитесь к службе, используя назначенные учетные данные пользователя: Connect-AipService –Verbose
Убедитесь в том, что служба RMS включена: enable-aipservice
Получите идентификатор клиента, выполнив следующий командлет: Get-AipServiceConfiguration

Запишите значение BPOSId (идентификатор клиента). Она понадобится в дальнейшем.

Пример выходных данных командлета Get-AadrmConfiguration

Отключитесь от службы: Disconnect-AipServiceService

Создание субъекта-службы

Чтобы создать субъект-службу, выполните указанные ниже действия.

Субъект-служба — это учетные данные, настраиваемые глобально для управления доступом и позволяющие службе проходить проверку подлинности в Microsoft Azure AD и защищать информацию с помощью Microsoft Azure AD Rights Management.

Откройте PowerShell от имени администратора.
Импортируйте модуль Microsoft Azure AD с помощью следующей команды: Import-Module MSOnline
Подключитесь к веб-службе, используя назначенные учетные данные пользователя: Connect-MsolService
Создайте субъект-службу, выполнив следующий командлет: New-MsolServicePrincipal
Укажите имя субъекта-службы.

Запишите симметричный ключ и идентификатор субъекта приложения для использования в будущем.

Пример выходных данных командлета NewMsolServicePrincipal

Добавьте идентификатор субъекта приложения, симметричный ключ и идентификатор клиента в файл App.config приложения.

Пример файла App.config example App.config

ClientID и RedirectUri будут доступны при регистрации приложения в Azure. Дополнительные сведения о регистрации приложения в Azure и получении ClientID и RedirectUri см. в разделе Настройка Azure RMS для проверки подлинности ADAL.

Обзор разработки

На следующей схеме показана архитектура и поток процессов создаваемого приложения. Поэтапное описание его работы приведено ниже. Сводка по проектированию

Входные данные пользователя:
- Путь к защищаемому файлу
- Выбор шаблона или создание специальной политики
Приложение запрашивает проверку подлинности посредством AIP.
AIP подтверждает проверку подлинности.
Приложение запрашивает шаблон у AIP.
AIP возвращает предварительно определенный шаблон.
Приложение находит указанный файл в заданном расположении.
Приложение применяет политику защиты AIP к файлу.

Принцип работы кода

Основой примера решения Azure IP Test является файл Iprotect.cs. Это консольное приложение C#, которое, как и в случае с любым другим приложением с поддержкой AIP, начинает работу с загрузки файла MSIPC.dll, как видно в методе main().

//Loads MSIPC.dll
SafeNativeMethods.IpcInitialize();
SafeNativeMethods.IpcSetAPIMode(APIMode.Server);

Загрузите параметры, необходимые для подключения к Azure.

//Loads credentials for the service principal from App.Config
SymmetricKeyCredential symmetricKeyCred = new SymmetricKeyCredential();
symmetricKeyCred.AppPrincipalId = ConfigurationManager.AppSettings["AppPrincipalId"];
symmetricKeyCred.Base64Key = ConfigurationManager.AppSettings["Base64Key"];
symmetricKeyCred.BposTenantId = ConfigurationManager.AppSettings["BposTenantId"];

Когда вы указываете путь к файлу в консольном приложении, оно проверяет, не зашифрован ли уже документ. Метод принадлежит к классу SafeFileApiNativeMethods.

var checkEncryptionStatus = SafeFileApiNativeMethods.IpcfIsFileEncrypted(filePath);

Если документ не зашифрован, то приложение зашифровывает его, используя предоставленные данные.

if (!checkEncryptionStatus.ToString().ToLower().Contains(alreadyEncrypted))
{
  if (method == EncryptionMethod1)
  {
    //Encrypt a file via AIP template
    ProtectWithTemplate(symmetricKeyCred, filePath);

  }
  else if (method == EncryptionMethod2)
  {
    //Encrypt a file using ad-hoc policy
    ProtectWithAdHocPolicy(symmetricKeyCred, filePath);
  }
}

Если выбрана защита с помощью шаблона, приложение получает список шаблонов с сервера и предлагает пользователю выбрать один из них.

Если вы не изменяли шаблоны, то получите шаблоны по умолчанию из AIP.

public static void ProtectWithTemplate(SymmetricKeyCredential symmetricKeyCredential, string filePath)
{
  // Gets the available templates for this tenant
  Collection<TemplateInfo> templates = SafeNativeMethods.IpcGetTemplateList(null, false, true,
      false, true, null, null, symmetricKeyCredential);

  //Requests tenant template to use for encryption
  Console.WriteLine("Please select the template you would like to use to encrypt the file.");

  //Outputs templates available for selection
  int counter = 0;
  for (int i = 0; i < templates.Count; i++)
  {
    counter++;
    Console.WriteLine(counter + ". " + templates.ElementAt(i).Name + "\n" +
        templates.ElementAt(i).Description);
  }

  //Parses template selection
  string input = Console.ReadLine();
  int templateSelection;
  bool parseResult = Int32.TryParse(input, out templateSelection);

  //Returns error if no template selection is entered
  if (parseResult)
  {
    //Ensures template value entered is valid
    if (0 < templateSelection && templateSelection <= counter)
    {
      templateSelection -= templateSelection;

      // Encrypts the file using the selected template
      TemplateInfo selectedTemplateInfo = templates.ElementAt(templateSelection);

      string encryptedFilePath = SafeFileApiNativeMethods.IpcfEncryptFile(filePath,
          selectedTemplateInfo.TemplateId,
          SafeFileApiNativeMethods.EncryptFlags.IPCF_EF_FLAG_KEY_NO_PERSIST, true, false, true, null,
          symmetricKeyCredential);
    }
  }
}

Если выбрана специальная политика, пользователю приложения необходимо указать адреса электронной почты пользователей, которые получат разрешения. В этом разделе создается лицензия с помощью метода IpcCreateLicenseFromScratch() и применяется новая политика из шаблона.

if (issuerDisplayName.Trim() != "")
{
  // Gets the available issuers of rights policy templates.
  // The available issuers is a list of RMS servers that this user has already contacted.
  try
  {
    Collection<TemplateIssuer> templateIssuers = SafeNativeMethods.IpcGetTemplateIssuerList(
                                                    null,
                                                    true,
                                                    false,
                                                    false, true, null, symmetricKeyCredential);

    // Creates the policy and associates the chosen user rights with it
    SafeInformationProtectionLicenseHandle handle = SafeNativeMethods.IpcCreateLicenseFromScratch(
                                                        templateIssuers.ElementAt(0));
    SafeNativeMethods.IpcSetLicenseOwner(handle, owner);
    SafeNativeMethods.IpcSetLicenseUserRightsList(handle, userRights);
    SafeNativeMethods.IpcSetLicenseDescriptor(handle, new TemplateInfo(null, CultureInfo.CurrentCulture,
                                                            policyName,
                                                            policyDescription,
                                                            issuerDisplayName,
                                                            false));

    //Encrypts the file using the ad hoc policy
    string encryptedFilePath = SafeFileApiNativeMethods.IpcfEncryptFile(
                                    filePath,
                                    handle,
                                    SafeFileApiNativeMethods.EncryptFlags.IPCF_EF_FLAG_KEY_NO_PERSIST,
                                    true,
                                    false,
                                    true,
                                    null,
                                    symmetricKeyCredential);
    }
}

Пример взаимодействия с пользователем

После создания и выполнения приложения его выходные данные должны выглядеть следующим образом:

Вам будет предложено выбрать метод шифрования.
Вам предлагается указать путь к защищаемому файлу.
Вам предлагается ввести адрес электронной почты владельца лицензии (он должен иметь права глобального администратора в клиенте Azure AD).
Вы вводите адреса электронной почты пользователей, которые будут иметь права на доступ к файлу (через пробел).
Вы выбираете из списка разрешения, которые будут предоставлены авторизованным пользователям.
Наконец, вы введете некоторые метаданные политики: имя политики, описание и издатель (Azure AD клиент) отображаемого имени — шаг 6