開發您的應用程式

重要

2020年3月之前發行的 Microsoft Rights Management Service SDK 版本已被取代;使用舊版的應用程式必須更新為使用2020年3月版本。 如需完整的詳細資訊,請參閱淘汰 通知

Microsoft Rights Management Service SDK 尚未規劃任何進一步的增強功能。 我們強烈建議採用 Microsoft 資訊保護 SDK 來進行分類、標記和保護服務。

在這個範例中,您將建置一個與 Azure 資訊保護服務 (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 資訊保護的 Azure AD 環境,請遵循 從 Azure 資訊保護啟用保護服務的指導方針。

一旦服務啟動後,您會需要 PowerShell 元件進行後續的步驟。 請 使用 PowerShell 來管理 Azure 資訊保護的保護 ,以完成此動作。

取得您的租用戶識別碼

  • 以系統管理員身分執行 PowerShell。
  • 匯入 RMS 模組︰Import-Module AIPService
  • 使用指派的使用者認證連線到服務︰Connect-AipService –Verbose
  • 請確定已啟用 RMS:enable-aipservice
  • 執行下列項目取得租用戶識別碼︰Get-AipServiceConfiguration

記錄 BPOSId (租用戶識別碼) 值。 您在之後的步驟中將會用到它。

範例輸出 >get-aadrmconfiguration Cmdlet 輸出

  • 中斷連接服務︰Disconnect-AipServiceService

建立服務主體

請依照下列步驟建立服務主體︰

服務主體是針對存取控制全域設定的認證,可允許服務使用 Microsoft Azure AD 驗證,以及使用 Microsoft Azure AD Rights Management 保護資訊

  • 以系統管理員身分執行 PowerShell
  • 使用下列項目匯入 Microsoft Azure AD 模組:Import-Module MSOnline
  • 使用指派的使用者認證連線到您的線上服務:Connect-MsolService
  • 執行下列項目以建立新的服務主體︰New-MsolServicePrincipal
  • 提供服務主體的名稱

    記錄對稱金鑰和應用程式主體識別碼以供日後使用。

範例輸出 NewMsolServicePrincipal Cmdlet 輸出

  • 將您的應用程式主體識別碼、對稱金鑰以及租用戶識別碼加入到應用程式的 App.config 檔案。

範例 App.config 檔案 範例 App.config 檔案

  • 當您在 Azure 中註冊您的應用程式時,ClientIDRedirectUri 將可供您使用。 如需如何在 Azure 中註冊您的應用程式和取得 ClientIDRedirectUri 的詳細資訊,請參閱 設定 Azure RMS 以進行 ADAL 驗證

設計摘要

下圖說明您正在建立之應用程式的架構和程序流程,如下所述。 設計摘要

  1. 使用者輸入︰
    • 受保護檔案的路徑
    • 選取範本或建立臨機操作原則
  2. 應用程式要求使用 AIP 進行驗證。
  3. AIP 確認驗證
  4. 應用程式會從 AIP 要求範本。
  5. AIP 傳回預先定義的範本。
  6. 應用程式會使用給定的位置找出指定的檔案。
  7. 應用程式會將 AIP 保護原則套用至檔案。

程式碼的運作方式

在範例中,解決方案 Azure IP 測試會由 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);
    }
}

使用者互動範例

一旦您建置好所有項目並執行,應用程式的輸出看起來應該像下面這樣︰

  1. 系統會提示您選取加密方法。 應用程式輸出 - 步驟 1

  2. 系統會要求您提供要保護之檔案的路徑。 應用程式輸出 - 步驟 2

  3. 系統會提示您輸入授權擁有者的電子郵件 (此擁有者必須在 Azure AD 租用戶上具備全域系統管理員權限)。 應用程式輸出 - 步驟 3

  4. 輸入將具備檔案存取權限之使用者的電子郵件地址 (電子郵件必須以空格分隔)。 應用程式輸出 - 步驟 4

  5. 從要提供給授權使用者之權限的清單中選取。 應用程式輸出 - 步驟 5

  6. 最後,您可以輸入一些原則中繼資料︰原則名稱、描述和簽發者 (Azure AD 租用戶) 顯示名稱 應用程式輸出 - 步驟 6