Microsoft Purview 資訊保護 SDK 中的存取檢查

發行項
10/18/2023

強制執行合規性入口網站中定義的資訊版權管理許可權，是應用程式開發人員的責任。 SDK 提供一組 API 和列舉值，以簡化這些存取檢查。

下列範例和表格將示範哪些案例需要存取檢查、要檢查的許可權清單，以及如何執行檢查。

許可權清單和結果

如需許可權和描述的完整清單，請參閱設定 Azure 資訊保護的許可權。本文定義應用程式開發人員在許可權強制執行中的責任，並在特定許可權存在或不存在時啟用函式。

重要

這是應用程式開發人員 檢查和強制執行 許可權的回應。執行檢查失敗可能會導致資料遺失。

案例

應用程式執行存取檢查的位置和方式取決於您要建置的應用程式類型。處理完整檔案輸出且沒有使用者介面的應用程式會最常使用 EXTRACT 或 OWNER 許可權。具有使用者介面的應用程式需要最細微的控制項、封鎖對使用者控制項的存取，以及匯出應用程式中的路徑。如需程式碼範例，請參閱執行存取檢查一節。

沒有使用者介面的應用程式

沒有使用者介面的應用程式通常是以服務為基礎的或命令列介面（CLI）。當您的應用程式處理受到 Purview 資訊保護保護的檔案時，它 必須確保 沒有正確許可權的使用者無法使用服務或 CLI，以未受保護的格式匯出檔案。

這些應用程式應該驗證 擁有者 或 EXTRACT 許可權是否存在。擁有 OWNER 的使用者可以執行任何作業。具有 EXTRACT 的使用者可以直接移除保護或儲存到新的格式，即使該格式不支援保護也一樣。

具有使用者介面的應用程式

具有使用者介面的檔案 SDK 應用程式必須實作控制項，限制使用者無法執行的作業。這類應用程式的其中一個範例是 Azure 資訊保護 Viewer。檢視器會暫時解密檔案，並在應用程式視窗中轉譯內容。它會在顯示檔之前執行細微的存取檢查，並根據存取檢查的結果停用使用者介面元素。

執行存取檢查的部分工作流程可能如下所示：

使用者是否擁有 擁有者 許可權？如果是，請啟用所有控制項並停止處理其他許可權。
使用者是否具有 PRINT 許可權？如果是，請啟用列印控制項。如果沒有，請停用列印控制項。
使用者是否有 EXPORT 許可權？如果是，請啟用匯出控制項和 UI 元素。如果沒有，請停用這些元素。
使用者是否具有 EXTRACT 許可權？如果是，請啟用複製和螢幕擷取畫面。如果沒有，請停用這些函式。
使用者是否有編輯許可權？如果是，請啟用編輯並儲存目前的專案。如果沒有，請將專案設為唯讀。

這些檢查應該針對許可權清單和結果資料表中的所有許可權執行，但 VIEW 許可權除外 。若沒有此許可權，就無法存取檔案。

執行存取檢查

執行存取檢查的模式在 C++、.NET 和 JAVA 的檔案與保護 SDK 上很類似。

這些程式碼範例假設您已完成初始化 SDK 的步驟，並具現化引擎和處理常式。

使用 .NET 在檔案 SDK 中執行存取檢查

此程式碼狙擊會假設已建立 FileHandler，並指向有效的檔案。

// Validate that the file referred to by the FileHandler is protected.
if(handler.Protection != null)
{                
    // Validate that user has rights to remove protection from the file.                    
    if(handler.Protection.AccessCheck(Rights.Extract))
    {
        // If user has Extract right, remove protection and commit the change. Otherwise, throw exception. 
        handler.RemoveProtection();
        bool result = handler.CommitAsync(outputPath).GetAwaiter().GetResult();     
        return result;   
    }
    else
    {
        throw new Microsoft.InformationProtection.Exceptions.AccessDeniedException("User lacks EXPORT right.");
    }
}

使用 .NET 在保護 SDK 中執行存取檢查

此程式碼狙擊假設已建立 ProtectionHandler 以供取用。

// Validate that the file referred to by the FileHandler is protected.
if(protectionHandler != null)
{                
    // Validate that user has rights to remove protection from the file.                    
    if(protectionHandler.AccessCheck(Rights.Print))
    {
        // If the user has the print right, enable the control.
        // SetPrintControlEnabled() is an example and not a MIP SDK function.  
        SetPrintControlEnabled(true);
    }
    else
    {
        // If the user does not have the print right, disable the control.
        // SetPrintControlEnabled() is an example and not a MIP SDK function.  
        SetPrintControlEnabled(false);
    }
}

使用 C++ 在檔案 SDK 中執行存取檢查

此程式碼狙擊會假設已建立 FileHandler，並指向有效的檔案。

// Validate that the file referred to by the FileHandler is protected.
if (fileHandler->GetProtection() != nullptr)
{
    if (fileHandler->GetProtection()->AccessCheck(mip::rights::Extract()))
    {
        auto commitPromise = std::make_shared<std::promise<bool>>();
        auto commitFuture = commitPromise->get_future();
        fileHandler->RemoveProtection();
        fileHandler->CommitAsync(outputFile, commitPromise);
        result = commitFuture.get();
    }
    else
    {
        throw std::runtime_error("User doesn't have EXTRACT right.");
    }
}

使用 C++ 在保護 SDK 中執行存取檢查

此程式碼狙擊假設已建立 ProtectionHandler 以供取用。

// Validate that the file referred to by the FileHandler is protected.
if (protectionHandler != nullptr)
{
    if (protectionHandler->AccessCheck(mip::rights::Print()))
    {
        // If the user has the print right, enable the control.
        // SetPrintControlEnabled() is an example and not a MIP SDK function.  
        SetPrintControlEnabled(true);
    }
    else
    {
        // If the user does not have the print right, disable the control.
        // SetPrintControlEnabled() is an example and not a MIP SDK function.  
        SetPrintControlEnabled(false);
    }
}

後續步驟

既然您已瞭解如何正確執行存取檢查，以及強制執行與這些檢查相關聯的許可權，請繼續進行檔案處理常式概念，以深入瞭解如何從檔案移除保護。

共用方式為