Utveckla ditt programDeveloping your application

I det här exemplet ska du skapa ett enkelt konsolprogram som samverkar med Azure Information Protection-tjänsten (AIP).In this example you are going to build a simple console application that interacts with the Azure Information Protection service (AIP). Som utgångspunkt används en sökväg till ett dokument som ska skyddas, sedan skyddas det med en ad hoc-princip eller en Azure-mall.It will take as input the path of a document to protect, then protect it with an ad-hoc policy or an Azure template. Programmet tillämpar därefter korrekta principer enligt indata och skapar ett informationsskyddat dokument.The application will then apply the correct policies according to the inputs, creating a information protected document. Du kommer att använda exempelkoden Azure IP test application och den finns på Github.The sample code you will be using is Azure IP test application and is on Github.

Exempelapp – kravSample app prerequisites

  • Operativsystem: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2 eller Windows Server 2012Operating System: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2, or Windows Server 2012
  • Programmeringsspråk: C# (.NET Framework 3.0 och senare)Programming Language: C# (.NET Framework 3.0 and above)
  • Utvecklingsmiljö: Visual Studio 2015 (och senare)Development environment: Visual Studio 2015 (and later)

Inställning av din Azure-konfigurationSetting up your Azure Configuration

Inställningen av Azure för det här programmet kräver att du skapar ett klient-ID, en symmetrisk nyckel och ett ägar-ID för programmet.Getting Azure set up for this app requires you to create a Tenant ID, a Symmetric Key, and an Application Principal ID.

Azure AD-klient-konfigureringAzure AD Tenant configuration

Om du vill konfigurera Azure AD-miljön för Azure Information Protection följer du rikt linjerna i aktivera skydds tjänsten från 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.

När tjänsten har aktiverats behöver du PowerShell-komponenter för nästa steg.Once the service is activated you will need PowerShell components for the next steps. Följ Administrera skydd från Azure information Protection med hjälp av PowerShell för att åstadkomma detta.Follow Administering protection from Azure Information Protection by using PowerShell to accomplish this.

Få ditt klient-IDGetting your Tenant ID

  • Kör PowerShell som administratör.As an administrator, run PowerShell.
  • Importera RMS-modulen:Import-Module AIPServiceImport the RMS module: Import-Module AIPService
  • Anslut till tjänsten med de tilldelade autentiseringsuppgifterna:Connect-AipService –VerboseConnect to the service with the assigned user credentials: Connect-AipService –Verbose
  • Kontrollera RMS är aktiverat:enable-aipserviceEnsure RMS is enabled: enable-aipservice
  • Få ditt klient-ID genom att köra:Get-AipServiceConfigurationGet your tenant ID by running: Get-AipServiceConfiguration

Spara värdet för BPOSId (klient-ID).Record the BPOSId (tenant ID) value. Du behöver det vid senare steg.You will need it in future steps.

Exempel på utdata  cmdlet-utdataExample output cmdlet output

  • Koppla bort tjänsten:Disconnect-AipServiceServiceDisconnect from the service: Disconnect-AipServiceService

Skapa tjänstens huvudnamnCreate a service Principal

Följ anvisningarna för att skapa ett huvudnamn för tjänsten:Follow these steps to create a Service Principal:

Tjänstens huvudnamn är autentiseringsuppgifter som konfigurerats globalt för åtkomstkontroll som tillåter en tjänst att autentisera med hjälp av Microsoft Azure AD och att skydda information med hjälp av Microsoft Azure AD Rights ManagementA 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

  • Kör PowerShell som administratörAs an administrator, run PowerShell
  • Importera Microsoft Azure AD-modulen med hjälp av:Import-Module MSOnlineImport the Microsoft Azure AD module using: Import-Module MSOnline
  • Anslut till din online-tjänst med de tilldelade autentiseringsuppgifterna:Connect-MsolServiceConnect to your online service with the assigned user credentials: Connect-MsolService
  • Skapa ett nytt huvudnamn för tjänsten genom att köra:New-MsolServicePrincipalCreate a new service principal by running: New-MsolServicePrincipal
  • Ange ett namn för din tjänstProvide a name for your service principal

    Spara den symmetriska nyckeln och programmets ägar-ID för framtida användning.Record the symmetric key and application principal id for future use.

Exempel på utdata  cmdlet-utdataExample output cmdlet output

  • Lägg till programmets ägar-ID, symmetriska nyckel och klient-ID till programmets App.config-fil.Add your application principal id, symmetric key, and tenant ID to the application’s App.config file.

Exempel App.config fil  cmdlet-utdataExample App.config file cmdlet output

  • ClientID och RedirectUri finns tillgängliga från när du registrerade ditt program i Azure.The ClientID and RedirectUri will be available to you from when you registered your application in Azure. Mer information om hur du registrerar ditt program i Azure och får ClientID och RedirectUri finns i Konfigurera Azure RMS för ADAL-autentisering.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.

DesignsammanfattningDesign summary

Följande diagram visar en arkitektur och ett processflöde för den app som du skapar, stegen beskrivs nedan.The following diagram depicts an architecture and process flow for the app you're creating, steps outlined below. designsammanfattningdesign summary

  1. Användarindata:The user inputs:
    • Sökvägen till filen som ska skyddasThe path of the file to be protected
    • Väljer en mall eller skapar en ad hoc-principSelects a template or creates an ad-hoc policy
  2. Programmet begär autentisering med AIP.The application requests authentication with AIP.
  3. AIP bekräftar autentiseringAIP confirms authentication
  4. Programmet begär mallar från AIP.The application requests templates from the AIP.
  5. AIP returnerar fördefinierade mallar.AIP returns pre-defined templates.
  6. Programmet lokaliserar den specificerade filen med angiven plats.The application locates the specified file with given location.
  7. Programmet tillämpar AIP-skyddsprincipen på filen.The application applies the AIP protection policy to the file.

Så här fungerar kodenHow the code works

I exemplet, Azure IP Test, börjar lösningen med filen Iprotect.cs.In the sample, Azure IP Test, the solution begins up with the file Iprotect.cs. Det här är ett C#-konsolprogram och precis som med alla andra AIP-aktiverade program så börjar du med att läsa in MSIPC.dll enligt main()-metoden.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);

Läs in de parametrar som behövs för att ansluta till AzureLoad 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"];

När du anger sökvägen i konsolprogrammet kontrollerar programmet om dokumentet redan är krypterat.When you provide the file path in the console application, the application checks if the document is already encrypted. Metoden är av klassen SafeFileApiNativeMethods.The method is of the SafeFileApiNativeMethods class.

var checkEncryptionStatus = SafeFileApiNativeMethods.IpcfIsFileEncrypted(filePath);

Om dokumentet inte är krypterat fortsätter den sedan att kryptera dokumentet med valet som anges i prompten.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);
  }
}

Alternativet skydda med mall fortsätter med att hämta mallistan från servern och ger användaren möjlighet att välja.The protect with template option proceeds to get the template list from the server and provides the user the option to select.

Om du inte modifierat mallar får du sedan standardmallar från AIPIf 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);
    }
  }
}

Om du väljer ad-hoc-princip måste användare av programmet ange e-postmeddelanden för de personer som ska ha rättigheter.If you select ad-hoc policy, the user of the application has to provide emails of the people that would have rights. I det här avsnittet skapas licensen med hjälp av metoden IpcCreateLicenseFromScratch() och tillämpar den nya principen på mallen.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);
    }
}

Exempel på användarinteraktionUser interaction example

När du skapat allt och kör ska utdata för programmet se ut ungefär som följer:Once you get everything built and executing, the outputs of the application should look like the following:

  1. Du uppmanas att välja en krypterings metod.You are prompted to select an encryption method. programutdata - steg 1app output - step 1

  2. Du uppmanas att ange sökvägen till filen som ska skyddas.You are asked to provide the path to the file to be protected. programutdata - steg 2app output - step 2

  3. Du uppmanas att ange en licensägares e-post (den här ägaren måste ha behörigheter som global administratör i Azure AD-klienten).You are prompted to enter a license owner’s email (this owner must have Global Administrator privileges on the Azure AD Tenant). programutdata - steg 3app output - step 3

  4. Du anger e-postadresser till användare som har behörighet att komma åt filen (e-postadresserna måste avgränsas med blanksteg).You enter email addresses of users who will have rights to access the file (emails must be separated by spaces). programutdata - steg 4app output - step 4

  5. Du väljer från en lista över rättigheter som ska ges till behöriga användare.You select from a list of rights to be given to the authorized users. programutdata - steg 5app output - step 5

  6. Slutligen anger vissa princip-metadata: principens namn, beskrivning och utfärdare (Azure AD-klient) programutdata - steg 6Finally, you enter some policy metadata: policy name, description, and issuer (Azure AD Tenant) display name app output - step 6