Entwickeln Ihrer AnwendungDeveloping your application

In diesem Beispiel erstellen Sie eine einfache Konsolenanwendung, die mit dem AIP-Dienst (Azure Information Protection-Dienst) interagiert.In this example you are going to build a simple console application that interacts with the Azure Information Protection service (AIP). Sie übernimmt als Eingabe den Pfad eines zu schützenden Dokuments und schützt es anschließend mit einer Ad-hoc-Richtlinie oder einer Azure-Vorlage.It will take as input the path of a document to protect, then protect it with an ad-hoc policy or an Azure template. Die Anwendung wendet dann die richtigen Richtlinien entsprechend den Eingaben an, um ein geschütztes Dokument zu erstellen.The application will then apply the correct policies according to the inputs, creating a information protected document. Der zu verwendende Beispielcode ist eine Azure IP-Testanwendung, die sich auf Github befindet.The sample code you will be using is Azure IP test application and is on Github.

Voraussetzungen für die Beispiel-AppSample app prerequisites

  • Betriebssystem: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2 oder Windows Server 2012Operating System: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2, or Windows Server 2012
  • Programmiersprache: C# (.NET Framework 3.0 und höher)Programming Language: C# (.NET Framework 3.0 and above)
  • Entwicklungsumgebung: Visual Studio 2015 (und höher)Development environment: Visual Studio 2015 (and later)

Einrichten der Azure-KonfigurationSetting up your Azure Configuration

Das Einrichten von Azure für diese App erfordert, dass Sie eine Mandanten-ID, einen symmetrischen Schlüssel und eine Anwendungsprinzipal-ID erstellen.Getting Azure set up for this app requires you to create a Tenant ID, a Symmetric Key, and an Application Principal ID.

Azure AD-MandantenkonfigurationAzure AD Tenant configuration

Wenn Sie die Azure AD Umgebung für Azure Information Protection konfigurieren möchten, befolgen Sie die Anweisungen unter Aktivieren des Schutz Dienstanbieter von Azure Information Protection.To configure the Azure AD environment for Azure Information Protection, follow the guidance in Activating the protection service from Azure Information Protection.

Nachdem der Dienst aktiviert wurde, benötigen Sie PowerShell-Komponenten für die nächsten Schritte.Once the service is activated you will need PowerShell components for the next steps. Befolgen Sie hierzu die Schritte zum Verwalten des Schutzes von Azure Information Protection mithilfe von PowerShell .Follow Administering protection from Azure Information Protection by using PowerShell to accomplish this.

Abrufen der Mandanten-IDGetting your Tenant ID

  • Führen Sie PowerShell als Administrator aus.As an administrator, run PowerShell.
  • Importieren Sie das RMS-Modul: Import-Module AIPService.Import the RMS module: Import-Module AIPService
  • Stellen Sie eine Verbindung mit dem Dienst mithilfe der zugewiesenen Benutzeranmeldeinformationen her: Connect-AipService –VerboseConnect to the service with the assigned user credentials: Connect-AipService –Verbose
  • Stellen Sie sicher, dass RMS aktiviert ist: enable-aipserviceEnsure RMS is enabled: enable-aipservice
  • Rufen Sie Ihre Mandanten-ID ab, indem Sie Folgendes ausführen: Get-AipServiceConfigurationGet your tenant ID by running: Get-AipServiceConfiguration

Notieren Sie den BPOSId-Wert (Mandanten-ID).Record the BPOSId (tenant ID) value. Sie wird später benötigt.You will need it in future steps.

Beispielausgabe  Cmdlet-AusgabeExample output cmdlet output

  • Trennen Sie die Verbindung mit dem Dienst: Disconnect-AipServiceServiceDisconnect from the service: Disconnect-AipServiceService

Erstellen eines DienstprinzipalsCreate a service Principal

Führen Sie die folgenden Schritte aus, um einen Dienstprinzipal zu erstellen:Follow these steps to create a Service Principal:

Ein Dienstprinzipal besteht aus Anmeldeinformationen, die für die globale Zugriffssteuerung konfiguriert sind und einem Dienst die Authentifizierung mit Microsoft Azure AD und das Schützen von Informationen mithilfe von Microsoft Azure AD Rights Management ermöglichen.A service principal is credentials configured globally for access control that allow a service to authenticate with Microsoft Azure AD and to protect information using Microsoft Azure AD Rights Management

  • Führen Sie PowerShell als Administrator aus.As an administrator, run PowerShell
  • Importieren Sie das Microsoft Azure AD-Modul mithilfe von: Import-Module MSOnlineImport the Microsoft Azure AD module using: Import-Module MSOnline
  • Stellen Sie eine Verbindung mit Ihrem Onlinedienst mithilfe der zugewiesenen Benutzeranmeldeinformationen her: Connect-MsolServiceConnect to your online service with the assigned user credentials: Connect-MsolService
  • Erstellen sie einen neuen Dienstprinzipal, indem Sie Folgendes ausführen: New-MsolServicePrincipalCreate a new service principal by running: New-MsolServicePrincipal
  • Geben Sie einen Namen für Ihre Dienstprinzipal an.Provide a name for your service principal

    Notieren Sie den symmetrischen Schlüssel und die Anwendungsprinzipal-ID für die spätere Verwendung.Record the symmetric key and application principal id for future use.

Beispielausgabe  Cmdlet-AusgabeExample output cmdlet output

  • Fügen Sie Ihre Anwendungsprinzipal-ID, den symmetrischen Schlüssel und die Mandanten-ID zur Datei „App.config“ der Anwendung hinzu.Add your application principal id, symmetric key, and tenant ID to the application’s App.config file.

Beispiel App.config Datei  Cmdlet-AusgabeExample App.config file cmdlet output

  • ClientID und RedirectUri wurden Ihnen beim Registrieren Ihrer Anwendung in Azure zur Verfügung gestellt.The ClientID and RedirectUri will be available to you from when you registered your application in Azure. Weitere Informationen zum Registrieren Ihrer Anwendung in Azure und zum Abrufen von ClientID und RedirectUri finden Sie unter Konfigurieren von Azure RMS für die ADAL-Authentifizierung.For more information on how to register your application in Azure and to acquire a ClientID and RedirectUri see, Configure Azure RMS for ADAL authentication.

EntwurfszusammenfassungDesign summary

Im folgenden Diagramm sind der Architektur- und Prozessverlauf für die zu erstellende App veranschaulicht und die erforderlichen Schritte unten erläutert.The following diagram depicts an architecture and process flow for the app you're creating, steps outlined below. Entwurfszusammenfassungdesign summary

  1. Benutzereingabe:The user inputs:
    • Pfad zu der zu schützenden DateiThe path of the file to be protected
    • Vorlage auswählen oder Ad-hoc-Richtlinie erstellenSelects a template or creates an ad-hoc policy
  2. Anwendung fordert Authentifizierung mit AIP anThe application requests authentication with AIP.
  3. AIP bestätigt AuthentifizierungAIP confirms authentication
  4. Anwendung fordert Vorlagen von AIP anThe application requests templates from the AIP.
  5. Vordefinierte Vorlagen werden von AIP zurückgegebenAIP returns pre-defined templates.
  6. Anwendung sucht angegebene Datei am bereitgestellten SpeicherortThe application locates the specified file with given location.
  7. Anwendung wendet AIP-Schutzrichtlinie auf die Datei anThe application applies the AIP protection policy to the file.

Funktionsweise des CodesHow the code works

Im Beispiel zum Azure IP-Test beginnt die Lösung mit der Datei „Iprotect.cs“.In the sample, Azure IP Test, the solution begins up with the file Iprotect.cs. Dies ist ein C#-Konsolenanwendungsprojekt, und wie bei jeder anderen AIP-fähigen Anwendung beginnen Sie mit beim Laden der Datei „msipc.dll“, wie in der main()-Methode veranschaulicht.This is a C# console application and, like with any other AIP enabled application, you begin with loading the MSIPC.dll as shown in the main() method.

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

Laden der für die Verbindung mit Azur erforderlichen ParameterLoad the parameters needed to connect to 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"];

Wenn Sie den Dateipfad in der Konsolenanwendung angeben, prüft die Anwendung, ob das Dokument bereits verschlüsselt ist.When you provide the file path in the console application, the application checks if the document is already encrypted. Die Methode stammt aus der Klasse SafeFileApiNativeMethods.The method is of the SafeFileApiNativeMethods class.

var checkEncryptionStatus = SafeFileApiNativeMethods.IpcfIsFileEncrypted(filePath);

Wenn das Dokument nicht verschlüsselt ist, wird mit der Verschlüsselung des Dokuments mit der bei der Aufforderung bereitgestellten Auswahl fortgefahren.If the document is not encrypted, then it proceeds to encrypt the document with the selection provided on the prompt.

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

Die Option zum Schützen mit Vorlage fährt mit dem Abrufen der Vorlagenliste vom Server fort und bietet dem Benutzer die Auswahlmöglichkeit.The protect with template option proceeds to get the template list from the server and provides the user the option to select.

Wenn Sie keine Vorlagen geändert haben, erhalten Sie Standardvorlagen von AIP.If you did not Modify templates then you will get default templates from 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);
    }
  }
}

Wenn Sie die Ad-hoc-Richtlinie auswählen, muss der Benutzer der Anwendung E-Mails der Personen bereitstellen, die Berechtigungen erhalten sollen.If you select ad-hoc policy, the user of the application has to provide emails of the people that would have rights. In diesem Abschnitt wird die Lizenz mit der Methode IpcCreateLicenseFromScratch() erstellt und die neue Richtlinie auf die Vorlage angewendet.In this section the license is created using the IpcCreateLicenseFromScratch() method and applying the new policy on the template.

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

Beispiel für die BenutzerinteraktionUser interaction example

Nachdem alles erstellt und ausgeführt wurde, sollte die Ausgabe der Anwendung wie folgt aussehen:Once you get everything built and executing, the outputs of the application should look like the following:

  1. Sie werden aufgefordert, eine Verschlüsselungsmethode auszuwählen.You are prompted to select an encryption method. App-Ausgabe – Schritt 1app output - step 1

  2. Sie werden aufgefordert, den Pfad zu der zu schützenden Datei bereitzustellen.You are asked to provide the path to the file to be protected. App-Ausgabe – Schritt 2app output - step 2

  3. Sie werden aufgefordert, eine E-Mail-Adresse des Lizenzbesitzers einzugeben (dieser Besitzer muss über globale Administratorrechte auf dem Azure AD-Mandanten verfügen).You are prompted to enter a license owner’s email (this owner must have Global Administrator privileges on the Azure AD Tenant). App-Ausgabe – Schritt 3app output - step 3

  4. Sie geben E-Mail-Adressen von Benutzern ein, die Zugriff auf die Datei haben sollen (E-Mails müssen durch Leerzeichen getrennt werden).You enter email addresses of users who will have rights to access the file (emails must be separated by spaces). App-Ausgabe – Schritt 4app output - step 4

  5. Sie wählen aus einer Liste die Rechte aus, die die autorisierten Benutzer erhalten sollen.You select from a list of rights to be given to the authorized users. App-Ausgabe – Schritt 5app output - step 5

  6. Abschließend geben Sie einige Richtlinienmetadaten ein: Richtlinienname, Beschreibung und Anzeigename des Ausstellers (Azure AD-Mandant) App-Ausgabe – Schritt 6Finally, you enter some policy metadata: policy name, description, and issuer (Azure AD Tenant) display name app output - step 6