Microsoft Information Protection SDK - Policy SDK engine concepts

mip::PolicyEngine implements all operations that the Policy SDK can perform, with the exception of loading the profile.

Implementation: Add a policy engine

Implementation: Create policy engine settings

Similar to a profile, the engine also requires a settings object, mip::PolicyEngine::Settings. This object stores the unique engine identifier, an object of your mip::AuthDelegate implementation, customizable client data for debugging or telemetry, and, optionally, the locale.

The following example creates a PolicyEngine::Settings object called engineSettings by using the identity of the application user:

PolicyEngine::Settings engineSettings(
  mip::Identity(mUsername), // mip::Identity.  
  authDelegateImpl,         // Auth delegate object
  "",                       // Client data. Customizable by developer, stored with engine.
  "en-US",                  // Locale.
  false);                   // Load sensitive information types for driving classification.

When creating engineSettings in this manner, also explicitly set a unique engineId:

engineSettings.SetEngineId(engineId);

Using the username or email helps ensure that the same engine loads each time the user uses the service or application.

Also valid is providing a custom engine ID:

PolicyEngine::Settings engineSettings(
  "myEngineId",     // String
  authDelegateImpl, // Auth delegate object
  "",               // Client data in string format. Customizable by developer, stored with engine.
  "en-US",          // Locale. Default is en-US
  false);           // Load sensitive information types for driving classification. Default is false.

As a best practice, use a first parameter, id, that connects the engine to the associated user, preferably the user principal name.

Implementation: Add the policy engine

To add the engine, return to the future/promise pattern used to load the profile. Instead of creating the promise for mip::Profile, use mip::PolicyEngine.


  // Auto profile will be std::shared_ptr<mip::Profile>.
  auto profile = profileFuture.get();

  // Create the delegate
  auto authDelegateImpl = std::make_shared<sample::auth::AuthDelegateImpl>(appInfo, userName, password);


  // Create the PolicyEngine::Settings object.
  PolicyEngine::Settings engineSettings("UniqueID", authDelegateImpl, "");

  // Create a promise for std::shared_ptr<mip::PolicyEngine>.
  auto enginePromise = std::make_shared<std::promise<std::shared_ptr<mip::PolicyEngine>>>();

  // Instantiate the future from the promise.
  auto engineFuture = enginePromise->get_future();

  // Add the engine using AddEngineAsync, passing in the engine settings and the promise.
  profile->AddEngineAsync(engineSettings, enginePromise);

  // Get the future value and store in std::shared_ptr<mip::PolicyEngine>.
  auto engine = engineFuture.get();

The code adds an engine for the authenticated user to the profile.

Implementation: List sensitivity labels

Using the added engine, you can list all sensitivity labels available to the authenticated user by calling engine->ListSensitivityLabels().

ListSensitivityLabels() fetches the list of labels and attributes of those labels for a specific user from the service. The result is stored in a vector of std::shared_ptr<mip::Label>.

Implementation: ListSensitivityLabels()

std::vector<shared_ptr<mip::Label>> labels = engine->ListSensitivityLabels();

Implementation: Print the labels

//Iterate through all labels in the vector
for (const auto& label : labels) {
  //print the label name
  cout << label->GetName() << endl;
  //Iterate through all child labels
  for (const auto& child : label->GetChildren()) {
    //Print the label with some formatting
    cout << "->  " << child->GetName() << endl;
  }
}

Printing the names shows that the application successfully pulled policy from the service and got the labels. To apply the label, you need the label identifier. Modify the previous snippet to return the label ID:

for (const auto& label : labels) {
  //Print label name and GUID
  cout << label->GetName() << " : " << label->GetId() << endl;

  //Print child label name and GUID
  for (const auto& child : label->GetChildren()) {
    cout << "->  " << child->GetName() <<  " : " << child->GetId() << endl;
  }
}

You can use the collection of mip::Label returned by ListSensitivityLabels() to display all labels available to the user and then, when selected, use the ID to apply labels to a file.

Next steps

  • Last updated on