Uygulamanızı geliştirmeDeveloping your application

Bu örnekte, Azure Information Protection hizmetiyle (AIP) etkileşimli çalışan basit bir konsol uygulaması oluşturacaksınız.In this example you are going to build a simple console application that interacts with the Azure Information Protection service (AIP). Bu uygulama, korunacak belgenin yolunu giriş olacak alacak ve ardından geçici bir ilke veya Azure şablonuyla belgeyi koruyacak.It will take as input the path of a document to protect, then protect it with an ad-hoc policy or an Azure template. Ardından uygulama, girişlere göre doğru ilkeleri uygulayacak ve bilgi korumalı belgeler oluşturacak.The application will then apply the correct policies according to the inputs, creating a information protected document. Kullanacağınız örnek kod Azure IP test uygulamasıdır ve Github üzerindedir.The sample code you will be using is Azure IP test application and is on Github.

Örnek uygulama önkoşullarıSample app prerequisites

  • İşletim sistemi: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2 veya Windows Server 2012Operating System: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2, or Windows Server 2012
  • Programlama dili: C#(.NET framework 3.0 ve üstü)Programming Language: C# (.NET Framework 3.0 and above)
  • Geliştirme ortamı: Visual Studio 2015 (veya üzeri)Development environment: Visual Studio 2015 (and later)

Azure Yapılandırmanızı ayarlamaSetting up your Azure Configuration

Azure’u bu uygulamaya göre ayarlamak için bir Kiracı Kimliği, Simetrik Anahtar ve Uygulama Birincil Kimliği oluşturmanız gerekir.Getting Azure set up for this app requires you to create a Tenant ID, a Symmetric Key, and an Application Principal ID.

Azure AD Kiracısı yapılandırmasıAzure AD Tenant configuration

Azure AD ortamını Azure Information Protection’a göre yapılandırmak için, Azure Hak Yönetimi’ni etkinleştirme konusunda verilen yönergeleri izleyin.To configure the Azure AD environment for Azure Information Protection, follow the guidance in Activating Azure Rights Management.

Hizmet etkinleştirildikten sonra, izleyen adımlar için PowerShell bileşenlerine ihtiyacınız olacak.Once the service is activated you will need PowerShell components for the next steps. Bunu elde etmek için Windows PowerShell kullanarak Azure Rights Management hizmetini yönetme yönergelerini izleyin.Follow Administering the Azure Rights Management service by using Windows PowerShell to accomplish this.

Kiracı Kimliğinizi almaGetting your Tenant ID

  • PowerShell’i yönetici olarak çalıştırın.As an administrator, run PowerShell.
  • RMS modülünü içeri aktarın: Import-Module AADRMImport the RMS module: Import-Module AADRM
  • Atanan kullanıcı kimlik bilgileriyle hizmete bağlanın: Connect-AadrmService –VerboseConnect to the service with the assigned user credentials: Connect-AadrmService –Verbose
  • RMS’nin etkinleştirildiğinden emin olun: Enable-AADRMEnsure RMS is enabled: Enable-AADRM
  • Şu komutu çalıştırarak kiracı kimliğinizi alın: Get-AadrmConfigurationGet your tenant ID by running: Get-AadrmConfiguration

BPOSId (kiracı kimliği) değerini kaydedin.Record the BPOSId (tenant ID) value. Bu değer sonraki adımlarda gerekecektir.You will need it in future steps.

Örnek çıkış cmdlet çıkışıExample output cmdlet output

  • Hizmetle bağlantıyı kesin: Disconnect-AadrmServiceDisconnect from the service: Disconnect-AadrmService

Hizmet asıl adı oluşturmaCreate a service Principal

Hizmet Asıl Adı oluşturmak için bu adımları izleyin:Follow these steps to create a Service Principal:

Hizmet asıl adı, erişim denetimi için yapılandırılan, hizmetin Microsoft Azure AD ile kimlik doğrulaması yapmasına ve Microsoft Azure AD Hak Yönetimi’ni kullanarak bilgileri korumasına olanak tanıyan kimlik bilgileridir.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

  • PowerShell’i yönetici olarak çalıştırınAs an administrator, run PowerShell
  • Şu komutu kullanarak Microsoft Azure AD modülünü içeri aktarın: Import-Module MSOnlineImport the Microsoft Azure AD module using: Import-Module MSOnline
  • Atanan kullanıcı kimlik bilgileriyle çevrimiçi hizmetinize bağlanın: Connect-MsolServiceConnect to your online service with the assigned user credentials: Connect-MsolService
  • Şu komutu kullanarak yeni bir hizmet asıl adı oluşturun: New-MsolServicePrincipalCreate a new service principal by running: New-MsolServicePrincipal
  • Hizmet asıl adınız için bir ad girinProvide a name for your service principal > Simetrik anahtarı ve uygulama birincil kimliğini gelecekte kullanmak üzere kaydedin.Record the symmetric key and application principal id for future use.

Örnek çıkış cmdlet çıkışıExample output cmdlet output

  • Uygulama birincil kimliğinizi, simetrik anahtarınızı ve kiracı kimliğinizi uygulamanın App.config dosyasına ekleyin.Add your application principal id, symmetric key, and tenant ID to the application’s App.config file.

Örnek App.config dosyası cmdlet çıkışıExample App.config file cmdlet output

  • ClientID ve RedirectUri değerleri, uygulamanızı Azure’a kaydettiğinizde size sağlanacaktır.The ClientID and RedirectUri will be available to you from when you registered your application in Azure. Uygulamanızı Azure’a nasıl kaydedeceğiniz ve ClientID ile RedirectUri değerlerini nasıl alacağınız hakkında bilgi için bkz. Azure RMS’yi ADAL kimlik doğrulaması için yapılandırma.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.

Tasarım özetiDesign summary

Aşağıdaki diyagramda oluşturduğunuz uygulamanın mimarisi ve süreç akışı gösterilir; adımlar aşağıda açıklanmıştır.The following diagram depicts an architecture and process flow for the app you're creating, steps outlined below. tasarım özetidesign summary

  1. Kullanıcı girişleri:The user inputs:
    • Korunacak dosyanın yoluThe path of the file to be protected
    • Şablon seçer ve geçici bir ilke oluştururSelects a template or creates an ad-hoc policy
  2. Uygulama AIP ile kimlik doğrulaması ister.The application requests authentication with AIP.
  3. AIP kimlik doğrulamasını onaylarAIP confirms authentication
  4. Uygulama AIP’den şablonları ister.The application requests templates from the AIP.
  5. AIP önceden tanımlanmış şablonları döndürür.AIP returns pre-defined templates.
  6. Uygulama belirtilen dosyayı verili konumda bulur.The application locates the specified file with given location.
  7. Uygulama dosyaya AIP koruma ilkesini uygular.The application applies the AIP protection policy to the file.

Kod nasıl çalışırHow the code works

Azure IP Testi örneğinde, çözüm Iprotect.cs dosyasıyla başlar.In the sample, Azure IP Test, the solution begins up with the file Iprotect.cs. Bur bir C# konsol uygulamasıdır ve AIP özellikli diğer tüm uygulamalar gibi main() yönteminde gösterildiği şekilde MSIPC.dll’yi yükleyerek başlarsınız.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);

Azure bağlanmak için gereken parametreleri yükleyinLoad 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"];

Konsol uygulamasında dosya yolunu sağladığınızda, uygulama dosyanın zaten şifrelenmiş olup olmadığını denetler.When you provide the file path in the console application, the application checks if the document is already encrypted. Yöntem, SafeFileApiNativeMethods sınıfındadır.The method is of the SafeFileApiNativeMethods class.

var checkEncryptionStatus = SafeFileApiNativeMethods.IpcfIsFileEncrypted(filePath);

Belge şifrelenmemişse, bilgi isteminde sağlanan seçimle belgeyi şifrelemeye devam eder.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);
  }

Şablon seçeneğiyle korumak için sunucudan şablon listesini almaya devam eder ve kullanıcıya belirtilecek seçeneği sağlar.The protect with template option proceeds to get the template list from the server and provides the user the option to select.

Şablonlarda değişiklik yapmadıysanız, AIP’den varsayılan şablonları alırsınızIf 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);
      }
    }
  }

Geçici bir ilke seçerseniz, uygulama kullanıcısının haklara sahip olacak kişilerin e-postalarını sağlaması gerekir.If you select ad-hoc policy, the user of the application has to provide emails of the people that would have rights. Bu bölümde IpcCreateLicenseFromScratch() yöntemi kullanılarak ve şablona yeni ilke uygulanarak lisans oluşturulur.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);
   }
}

Kullanıcı etkileşimi örneğiUser interaction example

Her şeyi oluşturduktan ve yürüttükten sonra, uygulamanın çıkışları aşağıdaki gibi görünmelidir:Once you get everything built and executing, the outputs of the application should look like the following:

1.Şifreleme yöntemi seçmeniz istenir.1.You are prompted to select an encryption method. uygulama çıkışı - 1. adımapp output - step 1

  1. Korunacak dosyaların yolunu sağlamanız istenir.You are asked to provide the path to the file to be protected. uygulama çıkışı - 2. adımapp output - step 2

  2. Lisans sahibinin e-postasını girmeniz istenir (bu lisans sahibinin Azure AD Kiracısı üzerinde Genel Yönetici ayrıcalıkları olmalıdır).You are prompted to enter a license owner’s email (this owner must have Global Administrator privileges on the Azure AD Tenant). uygulama çıkışı - 3. adımapp output - step 3

  3. Dosyaya erişim haklarına sahip olacak kullanıcıların e-posta adreslerini girersiniz (e-postalar boşluklarla ayrılmalıdır).You enter email addresses of users who will have rights to access the file (emails must be separated by spaces). uygulama çıkışı - 4. adımapp output - step 4

  4. Yetkili kullanıcılara verilecek hakları listeden seçersiniz.You select from a list of rights to be given to the authorized users. uygulama çıkışı - 5. adımapp output - step 5

  5. Son olarak, bazı ilke meta verilerini girersiniz: ilke adı, açıklama ve ilkeyi verenin (Azure AD Kiracısı) görünen adı uygulama çıkışı - 6. adımFinally, you enter some policy metadata: policy name, description, and issuer (Azure AD Tenant) display name app output - step 6