Auditing in the MIP File SDK

The Azure Information Protection administration portal provides access to administrator reports. These reports provide visibility in to which labels users are applying, manually or automatically, across any applications or services that have integrated the MIP SDK. Development partners using the SDK can enable this functionality to surface information from their applications in customer reports.

Enabling Auditing

By default, MIP SDK does not send audit events. Auditing must be enabled in one or more label policies for audit events to fire from MIP SDK-enabled applications.

To change this behavior, so that audit data is sent by all MIP SDK-enabled applications, do the following:

  • Add the following policy advanced setting using the Office 365 Security & Compliance Center PowerShell:

    • Key: EnableAudit
    • Value: True

    For example, if your label policy is named "Global":

    Set-LabelPolicy -Identity Global -AdvancedSettings @{EnableAudit="True"}
    

    Note

    By default, this advanced setting is not present in the policy, and the audit logs are not sent.

Event Types

There are three types of events that can be submitted via the SDK to Azure Information Protection Analytics. Heartbeat events, discovery events, and change events

Heartbeat Events

Heartbeat events are generated automatically for any application that has integrated the File SDK. Heartbeat events include:

  • TenantId
  • Time Generated
  • User Principal Name
  • Name of the machine where the audit was generated
  • Process Name
  • Platform
  • Application ID - Corresponds to the Azure AD Application ID.

These events are useful in detecting applications across your enterprise that are using the Microsoft Information Protection SDK.

Discovery Events

Discovery events provide information on labeled information that is read or consumed by the File SDK. These events are useful as they surface the devices, location, and users who are accessing information across an organization.

These events are submitted to Azure Information Protection Analytics, by setting the AuditDiscoveryEnabled parameter to true when creating a new mip::FileHandler. Additionally, a content identifier that identifies the file in some human-readable format is provided. It's recommended to use the file path for this identifier.

The example below creates a new mip::FileHandler with audit discovery enabled. The CreateFileHandler() method is called on the mip::FileEngine and AuditDiscoveryEnabled set to true. Once the FileHanlder reads the label, a discovery audit is generated.

// Create FileHandler with discovery enabled
auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
auto handlerFuture = handlerPromise->get_future();
fileEngine->CreateFileHandlerAsync(inputFilePath, actualFilePath, true /*AuditDiscoveryEnabled*/, make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto handler = handlerFuture.get();

// Read label. This generates the discovery audit.
auto label = handler->GetLabel();

Change Events

Change events provide information about the file, the label that was applied or changed, and any justifications provided by the user. Change events are generated by calling NotifyCommitSuccessful() on the mip::FileHandler, after a change has been successfully committed to a file.

// Create labeling options, set label
string contentId = "C:\\users\\myuser\\Documents\\MyPlan.docx";
mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
handler->SetLabel(labelId, labelingOptions, mip::ProtectionSettings());
auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();

// CommitAsync() returns a bool. If the change was successful, call NotifyCommitSuccessful().
fileHandler->CommitAsync(outputFile, commitPromise);
if(commitFuture.get()) {

    // Submit audit event.
    handler->NotifyCommitSuccessful(contentId);
}

Audit Dashboard

Events submitted to the Azure Information Protection audit pipeline will surface in reports at https://portal.azure.com.

Next Steps

For details on the auditing experience in Azure Information Protection, review the preview announcement blog on Tech Community.