Microsoft Information Protection SDK

Overview
About Microsoft Information Protection SDK
Quickstarts
Setup and configure MIP SDK
Implement AD RMS support with the MIP SDK
C++
File API
Application initialization (C++)
List sensitivity labels (C++)
Set/get sensitivity labels (C++)
Lowering a sensitivity label on a file (C++)
File API Republishing (C++)
Process email .msg files (C++)
Protection API
Application initialization (C++)
List Templates (C++)
Encrypt/Decrypt Text (C++)
C#
File API
Application initialization (C#)
List sensitivity labels (C#)
Set/get sensitivity labels (C#)
Lowering a sensitivity label on a file (C#)
File API Republishing (C#)
Process email .msg files (C#)
Protection API
Application initialization (C#)
List Templates (C#)

Encrypt/Decrypt Text (C#)

Concepts
The APIs
MIP SDK API Permissions
MipContext object concepts
Cache storage
Profile and Engine (C++)
Profile and Engine object concepts
File API profile (C++)
File API engine (C++)
Policy API profile (C++)
Policy API engine (C++)
Protection API profile (C++)
Protection API engine (C++)
Authentication (C++)
Authentication concepts
Implementing an authentication delegate (C++)
Acquiring an access token (Python)
Consent
Delegation
Handlers
File API handler (C++)
File handler concepts
Auditing
Policy API handler (C++)
Policy handler concepts
Execution state
Compute actions
Auditing
Protection API handler (C++)
Labels and Protection
Labels
Labels and Protection Behavior
User-defined Permissions
Metadata
Observers for async (C++)
Observer concepts
File API observers (C++)
Policy API observers (C++)
Protection API observers (C++)
Proxy Support
Service Discovery Overview
SDK Diagnostics
Supported File Types
Use Cases
File API - Action justification for lowering a sensitivity label on a file
File API - Republishing
File API - Process email .msg files
Reference
C++ library
C++ library Overview
Enums and structs
Classes
AccessDeniedError
Action
ActionData
AddContentFooterAction
AddContentHeaderAction
AddWatermarkAction
AddWatermarkActionData
AdhocProtectionRequiredError
ApplicationActionState
ApplyLabelAction
ArgumentData
AsyncControl
AuditDelegate
AuditEvent
AuthDelegate
AuthDelegate::OAuth2Challenge
AuthDelegate::OAuth2Token
BadInputError
ClassificationData
ClassificationRequest
ClassificationResult
ComputeEngine
ComputeEngine::Settings
ComputeEngineContext
ConditionData
ConsentDelegate
ConsentDeniedError
ContentFormatNotSupportedError
ContentLabel
ContentMarkingActionData
CustomAction
DelegationLicense
DelegationLicenseSettings
DeprecatedApiError
DetailedClassificationResult
DiagnosticDelegate
DocumentState
Error
Event
EventProperty
ExecutionState
FileEngine
FileEngine::Settings
FileExecutionState
FileHandler
FileHandler::Observer
FileInspector
FileIOError
FileProfile
FileProfile::Observer
FileProfile::Settings
GetTemplatesSettings
HttpDelegate
HttpOperation
HttpRequest
HttpResponse
Identity
InsufficientBufferError
InternalError
JustificationRequiredError
JustifyAction
Label
LabelActionData
LabelDisabledError
LabelGroupData
LabelingOptions
LabelNotFoundError
LicenseApplicationData
LicenseConnectionInfo
LicenseDescriptor
LicenseNameAndDescriptionItem
LicenseNotRegisteredError
LoggerDelegate
MetadataAction
MetadataEntry
MetadataVersion
MipContext
MsgAttachmentData
MsgInspector
NetworkError
NoAuthTokenError
NoPermissionsError
NoPolicyError
NotSupportedError
OperationCancelledError
ParsedPublishingLicense
ParsedPublishingLicenseBuilder
PolicyEngine
PolicyEngine::Settings
PolicyHandler
PolicyPackageData
PolicyProfile
PolicyProfile::Observer
PolicyProfile::Settings
PolicyRuleData
PrivilegedRequiredError
PropertyData
ProtectAdhocAction
ProtectAdhocDkAction
ProtectByEncryptOnlyAction
ProtectByTemplateAction
ProtectDoNotForwardAction
ProtectDoNotForwardDkAction
ProtectionActionData
ProtectionCommonSettings
ProtectionDescriptor
ProtectionDescriptorBuilder
ProtectionEngine
ProtectionEngine::Observer
ProtectionEngine::Settings
ProtectionHandler
ProtectionHandler::ConsumptionSettings
ProtectionHandler::Observer
ProtectionHandler::PublishingSettings
ProtectionProfile
ProtectionProfile::Observer
ProtectionProfile::Settings
ProtectionSettings
ProxyAuthenticationError
PublishingLicenseInfo
RecommendLabelAction
RemoveContentFooterAction
RemoveContentHeaderAction
RemoveProtectionAction
RemoveWatermarkAction
RulePackageData
SensitiveTypeClassificationData
SensitivityConditionData
SensitivityTypesRulePackage
ServiceDisabledError
Stream
SyncFileBaseData
SyncFilePolicyData
SyncFileSensitivityData
TaskDispatcherDelegate
TelemetryDelegate
TelemetryEvent
TemplateDescriptor
TemplateNotFoundError
UserRights
UserRoles
C library
Overview
Enumerations
Structures
Functions
.NET API Browser
API Permissions
Resources
Developer blog
FAQs and known issues
Forums
Samples
Security best practices
Version release history
Overview
3/7/2021 • 2 minutes to read
Microsoft Information Protection
Microsoft Information Protection SDK
O P E R AT IN G SY ST E M VE R SIO N S D O W N LO A D S N OT E S
Ubuntu 16.04 C++ [Link]
Ubuntu 18.04 C++ [Link]
Java (Preview) [Link]
.NET Core NuGet (Preview)
RedHat Enterprise Linux 7 with devtoolset-7 C++ [Link]
Debian 9 C++ [Link]
Microsoft Information Protection (MIP) is the unification of Microsoft's classification, labeling, and
protection
services:
Unified administration is provided across Microsoft 365, Azure Information Protection, Windows
Information
Protection, and other Microsoft services.
Third parties can use the MIP SDK to integrate with applications, using a standard, consistent data
labeling
schema and protection service.
What is Office 365 Security and Compliance Center?
What is Azure Information Protection?
How does the protection work in Azure Information Protection?
The MIP SDK exposes the labeling and protection services from Office 365 Security and
Compliance Center, to
third-party applications and services. Developers can use the SDK to build native support for
applying labels
and protection to files. Developers can reason over which actions should be taken when specific
labels are
detected, and reason over MIP-encrypted information.
The labels and protection applied to information across the suite of Microsoft services are
consistent.
Consistency allows applications and services that support MIP to read and write the labels in a
common,
predictable manner.
High-level MIP SDK use cases include:
A line-of-business application that applies classification labels to files on export.
A CAD/CAM design application provides native support for Microsoft Information Protection
labeling.
A cloud access security broker or data loss prevention solution reasons over data encrypted with
Azure
Information Protection.
For a more exhaustive list, review API concepts.
The MIP SDK is supported on the following platforms:
macOS High Sierra and later C++ .zip Xcode development
requires 9.4.1 or greater.
Windows All supported versions,
32/64 bit
C++/.NET Framework 4.6
.zip
C++/.NET NuGet
Java (Preview) .zip
Android 7.0 and later C++ .zip Protection and Policy APIs
only.
iOS All supported versions C++ .zip Protection and Policy APIs
only.
O P E R AT IN G SY ST E M VE R SIO N S D O W N LO A D S N OT E S
Next Steps
Now you're ready to get started with the SDK. The first thing you'll need to do is complete the MIP
SDK setup
and configuration steps. These steps will ensure your Microsoft 365 subscription and client
machine are set up
correctly.
Microsoft Information Protection (MIP) SDK setup
and configuration
3/16/2021 • 10 minutes to read
Prerequisites
IMPORTANT
Sign up for an Office 365 subscription
N A M E SIG N - U P
Office 365 Enterprise E3 Trial (30-day free trial) [Link]
LinkID=403802
Office 365 Enterprise E3 or E5 [Link]
business-software
Enterprise Mobility and Security E3 or E5
[Link]
security
Azure Information Protection Premium P1 or P2
[Link]
Microsoft 365 E3, E5, or F1 [Link]
365-plans
The Quickstart and Tutorial articles are centered around building applications that use the MIP
SDK libraries and
APIs. This article shows you how to set up and configure your Microsoft 365 subscription and client
workstation,
in preparation for using the SDK.
Be sure to review the following topics before getting started:
What is Office 365 Security and Compliance Center?
What is Azure Information Protection?
How does the protection work in Azure Information Protection?
To honor user privacy, you must ask the user to consent before enabling automatic logging. The
following
example is a standard message Microsoft uses for logging notification:
By turning on Error and Performance Logging, you are agreeing to send Error and Performance
Data to Microsoft.
Microsoft will collect error and performance data over the internet (“Data”). Microsoft uses this
Data to provide and
improve the quality, security and integrity of Microsoft products and services. For example, we
analyze performance and
reliability, such as what features you use, how quickly the features respond, device performance,
user interface
interactions, and any problems you experience with the product. Data will also include information
about the
configuration of your software like the software you are currently running, and the IP address.
Many of the SDK samples require access to an Office 365 subscription. If you haven't already, be
sure to sign up
for one of the following subscription types:
Configure sensitivity labels
Configure your client workstation
If you're currently using Azure Information Protection, you must migrate your labels to Office 365
Security and
Compliance Center. For more information on the process, see How to migrate Azure Information
Protection
labels to the Office 365 Security & Compliance Center.
Next, complete the following steps to ensure your client computer is set up and configured
correctly.
1. If you're using a Windows 10 workstation:
Using Windows Update, update your machine to Windows 10 Fall Creators Update (version 1709)
or later. To verify your current version:
Click the Windows icon in the lower left.
Type "About your PC" and press the "Enter" key.
Scroll down to Window s specifications and look under Version.
Ensure "Developer Mode" is enabled on your workstation:
Click the Windows icon in the lower left.
Type "Use developer features" and press the "Enter" key, when you see the Use Developer
Features item show.
On the S ettings dialog, For developers tab, under "Use developer features", select the
Developer mode option.
Close the S ettings dialog.
2. Install Visual Studio 2017, with the following workloads and optional components:
Universal Window s Platform development Windows workload, plus the following optional
components:
C++ Universal Window s Platform tools
Window s 10 S DK 10.0.16299.0 S DK or later, if not included by default
Desktop development w ith C++ Windows workload, plus the following optional components:
Window s 10 S DK 10.0.16299.0 S DK or later, if not included by default
O P E R AT IN G SY ST E M VE R SIO N S D O W N LO A D S N OT E S
Ubuntu 16.04 C++ [Link]
Ubuntu 18.04 C++ [Link]
Java (Preview) [Link]
.NET Core NuGet
(Preview)
3. Install the [Link] PowerShell Module:
PS C:\WINDOWS\system32> install-module -name [Link]
Untrusted repository
You are installing the modules from an untrusted repository. If you trust this repository,
change its
InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to
install the modules from
'PSGallery'?
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): A
PS C:\WINDOWS\system32>
Because administrator rights are required to install modules, first you need to either:
sign in to your computer with an account that has Administrator rights.
run the Windows PowerShell session with elevated rights (Run as Administrator).
Then run the install-module -name [Link] cmdlet:
4. Download SDK files:
The MIP SDK is supported on the following platforms, with separate downloads for each supported
platform/language:
RedHat Enterprise Linux 7 with devtoolset-7 C++ [Link]
Debian 9 C++ [Link]
macOS High Sierra and later C++ .zip Xcode development
requires 9.4.1 or greater.
Windows All supported versions,
32/64 bit
C++/.NET Framework 4.6
.zip
C++/.NET NuGet
Java (Preview) .zip
Android 7.0 and later C++ .zip Protection and Policy APIs
only.
iOS All supported versions C++ .zip Protection and Policy APIs
only.
O P E R AT IN G SY ST E M VE R SIO N S D O W N LO A D S N OT E S
Install-Package [Link]
Install-Package [Link]
Install-Package [Link]
[Link]/.Zip dow nloads
[Link] and .Zip downloads contain compressed files, one for each API. The compressed files are
named as
follows, where <API> = file , protection , or upe , and <OS> = the platform:
mip_sdk_<API>_<OS>_1.[Link] (or .[Link]) . For example, the file for protection API binaries and
headers on Debian would be: mip_sdk_protection_debian9_1.[Link] . Each
contained .[Link]/.zip is
split into three directories:
Bins: Compiled binaries for each platform architecture, where applicable.
Include: Header files (C++).
S amples: Source code for sample applications.
NuGet packages
If you're doing Visual Studio development, the SDK can be also installed via the NuGet Package
Manager
Console:
5. If you're not using the NuGet package, add the paths of the SDK binaries to the PATH
environment
variable. The PATH variable allows the dependent binaries (DLLs) to be found at runtime, by client
applications (OPTIONAL):
If you're using a Windows 10 workstation:
Click the Windows icon in the lower left.
Type "Path" and press the "Enter" key, when you see the Edit the system environment
variables item show.
On the S ystem Proper ties dialog, click Environment Variables.
On the Environment Variables dialog, click the Path variable row under User variables for
<user>, then click Edit....
On the Edit environment variable dialog, click New , which creates a new editable row. Using
Register a client application with Azure Active Directory
IMPORTANT
the full path to each of the file\bins\debug\amd64 , protection\bins\debug\amd64 , and
upe\bins\debug\amd64 subdirectories, add a new row for each. The SDK directories are stored in
a
<API>\bins\<target>\<platform> format, where:
<API> = file , protection , upe
<target> = debug , release
<platform> = amd64 (x64), x86 , etc.
When finished updating the Path variable, click OK. Then click OK when returned to the
Environment Variables dialog.
6. Download SDK samples from GitHub (OPTIONAL):
If you don't have one already, first create a GitHub profile.
Then install the latest version of Software Freedom Conservancy's Git client tools (Git Bash)
Using Git Bash, download the sample(s) of interest:
Use the following query to view the repositories: [Link]
utf8=%E2%9C%93&q=MipSdk.
Using Git Bash, use git clone [Link] to download each
sample repository.
As part of the Microsoft 365 subscription provisioning process, an associated Azure Active
Directory (Azure AD)
tenant is created. The Azure AD tenant provides identity and access management for Microsoft
365 user
accounts and application accounts. Applications that require access to secured APIs (such as MIP
APIs), require
an application account.
For authentication and authorization at runtime, accounts are represented by a security principal,
which is
derived from the account's identity information. Security principals that represent an application
account are
referred to as a service principal.
To register an application account in Azure AD for use with the Quickstarts and MIP SDK samples:
To access Azure AD tenant management for account creation, you'll need to sign in to the Azure
portal with a user
account that is a member of the "Owner" role on the subscription. Depending on the configuration
of your tenant, you
may also need to be a member of the "Global Admininstrator" directory role to register an
application. We recommend
testing with a restricted account. Be sure the account only has rights to access the necessary SCC
endpoints. Cleartext
passwords passed via commandline may be collected by logging systems.
1. Follow the steps in Register an app with Azure AD, Register a new application section. For
testing
purposes, use the following values for the given properties as you go through the guide steps:
S uppor ted Account Types - Select "Accounts in this organizational directory only."
Redirect UR I - Set the redirect URI type to "Public client (mobile & desktop)." If your application is
using the Microsoft Authentication Library (MSAL), use [Link] . Otherwise, use something
in the format <app-name>://authorize .
2. When finished, you'll be returned to the Registered app page for your new application
registration.
Copy and save the GUID in the Application (client) ID field, as you will need it for the Quickstarts.
3. Then click API permissions to add the APIs and permissions to which the client will need access.
Click
Add a permission to open the "Request API permissions" blade.
Request an Information Protection Integration Agreement (IPIA)
4. Now you'll add the MIP APIs and permissions the application will require at runtime:
On the S elect an API page, click Azure R ights Management S er vices.
On the Azure R ights Management S er vices API page, click Delegated permissions.
On the S elect permissions section, check the user_impersonation permission. This right allows
the application to create and access protected content on behalf of a user.
Click Add permissions to save.
5. Repeat step #4, but this time when you get to the S elect an API page, you'll need to search for
the API.
On the S elect an API page, click APIs my organization uses then in the search box type
Microsoft Information Protection S ync S er vice, and select it.
On the Microsoft Information Protection S ync S er vice API page, click Delegated permissions.
Expand the UnifiedPolicy node and check [Link]
Click Add permissions to save.
6. When you're back on the API permissions page, click Grant admin consent for (Tenant Name),
then Yes. This step gives pre-consent to the application using this registration, to access the APIs
under
the specified permissions. If you signed in as a global administrator, consent is recorded for all
users in
the tenant that run the application; otherwise, it applies only to your user account.
When finished, application registration and API permissions should look similar to the following
examples:
For more information on adding APIs and permissions to a registration, see Configure a client
application to
access web APIs. Here you'll find information on adding the APIs and permissions needed by a
client application.
Already have a signed IPIA?
Ensure your app has the required runtime
NOTE
Before you can release an application developed with MIP, you must apply for and complete a
formal agreement
with Microsoft.
1. Obtain your IPIA by sending an email to IPIA@[Link] with the following information:
S ubject: Requesting IPIA for Company Name
In the body of the email, include:
Application and product name
First and last name of the requester
Email address of the requester
2. Upon receipt of your IPIA request, we'll send you a form (as a Word document). Review the
terms and
conditions of the IPIA, and return the form to IPIA@[Link] with the following information:
Legal name of the Company
State/Province (US/Canada) or Country of Incorporation
Company URL
Email address of the contact person
Additional addresses of the company (optional)
Name of the Company Application
Brief Description of the Application
Azure Tenant ID
App ID for the application
Company contacts, email, and phone for Critical Situation Correspondence
3. When we receive your form, we'll send you the final IPIA link to digitally sign. After your signing,
it will be
signed by the appropriate Microsoft representative, completing the agreement.
If you already have a signed IPIA and want to add a new App ID for an application you are
releasing, send an
email to IPIA@[Link] and provide us with the following information:
Name of the Company Application
Brief Description of the Application
Azure Tenant ID (even if the same one as before)
App ID for the application
Company contacts, email, and phone for Critical Situation Correspondence
Upon the sending of the email, allow up to 72 hours for an acknowledgment of the receipt.
This step is necessary only if deploying the application to a machine without Visual Studio, or if the
Visual Studio
installation lacks the Visual C++ Runtime components.
Applications built with the MIP SDK require the Visual C++ 2015 or Visual C++ 2017 runtime to be
installed, if
not already present.
Microsoft Visual C++ 2015 Redistributable Update 3
Microsoft Visual C++ Redistributable for Visual Studio 2017
Next Steps
These will only work if the application has been built as Release. If the application is built as
Debug, then the
Visual C++ runtime debug DLLs must be included with the application or installed on the machine.
If you're a C++ developer
If you're a C# developer, when you're ready to get some experience with the SDK, start with
Quickstart: Client
application initialization (C#).
Be sure to read Observers concepts before you start the Quickstart section, to learn about the
asynchronous nature of the C++ APIs.
When you're ready to get some experience with the SDK, start with Quickstart: Client application
initialization (C++).
Quickstart: Active Directory Rights Management
Server (AD RMS) Protection
3/7/2021 • 4 minutes to read
NOTE
Prerequisites
Service Discovery
Configuring File API in C# to use AD RMS
Update the File Engine Settings to use AD RMS with an Identity
This quickstart will show you how to implement support for Active Directory Rights Management
Server (AD
RMS) using MIP SDK.
The steps outlined in this quickstart applicable to only File API for C# or C++ and Protection API for
C++ only.
If you haven't already, be sure to:
Complete Quickstart: Client application initialization (C++) first, which builds a starter Visual Studio
solution.
Complete Quickstart: List sensitivity labels (C++) or Quickstart: List sensitivity labels (C#)
Deploy AD RMS with Mobile Device Extension.
Optionally, ensure that the DNS SRV record for AD RMS MDE is published.
The SDK does service discovery based on the mip::Identity provided via FileEngineSettings or
ProtectionEngineSettings by using the UPN or mail address suffix. It first searches the domain
hierarchy for the
_rmsdisco record for MDE. For more details on that process, review Specifying the DNS SRV
records for the AD
RMS mobile device extension. If that DNS SRV record isn't found, it defaults to the Azure
Information Protection
service as the service location.
If an identity isn't available, or the DNS SRV record for MDE hasn't been published, the service
discovery process
can be overridden by explicitly settings the cloud endpoint URL.
Two minor changes are required if your application is using Active Directory Authentication Library
(ADAL) and
the File API on C#. The FileEngineSettings object and AuthenticationContext constructor must be
updated to
function with AD RMS and Active Directory Federations Services (ADFS).
If you've deployed the mobile device extension DNS SRV record and plan to pass in a user principal
name or
email address, follow the instructions for using an identity.
If you don't have the mobile device extension DNS SRV record, or won't have an identity at
runtime, follow the
explicit endpoint instructions.
If the DNS SRV record for MDE has been published and [Link]
has been
provided as part of the engine settings, the only required code change is to set
[Link] = true . This property must be set as labeling (policy)
operations aren't
supported for AD RMS protection endpoints.
// Configure FileEngineSettings as protection only engine.
var engineSettings = new FileEngineSettings("", authDelegate, "", "en-US")
{
// Provide the identity for service discovery.
Identity = identity,
// Set ProtectionOnlyEngine to true for AD RMS as labeling isn't supported
ProtectionOnlyEngine = true
};
Update the File Engine Settings to use AD RMS with an explicit endpoint
// Configure FileEngineSettings as protection only engine and generate a unique engine id.
var engineSettings = new FileEngineSettings("", authDelegate, "", "en-US")
{
// Set ProtectionOnlyEngine to true for AD RMS as labeling isn't supported
ProtectionOnlyEngine = true,
// Provide the explicit AD RMS endpoint
ProtectionCloudEndpointBaseUrl = "[Link]
};
Update the authentication delegate
AuthenticationContext authContext = new AuthenticationContext(authority, false, tokenCache);
Configuring File API in C++ to use AD RMS
Update the FileEngine::Settings to use AD RMS with an Identity
FileEngine::Settings engineSettings(mip::Identity(mUsername), "");
[Link] = true;
Update the FileEngine::Settings to use AD RMS with an explicit endpoint
If the DNS SRV record for MDE isn't published, or [Link] isn't
available to
pass in when creating the FileEngine , there are two required code changes. is to set
[Link] = true . This property must be set as labeling (policy)
operations aren't
supported for AD RMS protection endpoints.
If you're using the ADAL in your .NET application, you'll need to make a change to the
[Link] implementation to disable authority validation.
Disable authority
validation by setting validateAuthority in the AuthenticationContext constructor to false.
If you've deployed the mobile device extension DNS SRV record and plan to pass in a user principal
name or
email address, follow the instructions for using an identity.
If you don't have the mobile device extension DNS SRV record, or won't have an identity at
runtime, follow the
explicit endpoint instructions.
If the DNS SRV record for MDE has been published and mip::Identity is provided in the
FileEngine::Settings ,
then the only action is to set the engine to a protection-only engine.
If the DNS SRV record for MDE isn't published, or an identity isn't available for service discovery,
then the
engine must be set to protection only and the explicit cloud endpoint URL provided via
SetProtectionCloudEndpointBaseUrl() .
FileEngine::Settings engineSettings("", authDelegate, "");
[Link] = true;
[Link]("[Link]
Configuring Protection API in C++ to use AD RMS
Set the ProtectionEngine::Settings to use AD RMS with an Identity
ProtectionEngine::Settings engineSettings(mip::Identity(mUsername), authDelegate, "");
Set the ProtectionEngine::Settings to use AD RMS with an explicit endpoint
ProtectionEngine::Settings engineSettings("", authDelegate, "");
[Link]("[Link]
Remove or Comment Label References
Next Steps
If you've deployed the mobile device extension DNS SRV record and plan to pass in a user principal
name or
email address, follow the instructions for using an identity.
If you don't have the mobile device extension DNS SRV record, or won't have an identity at
runtime, follow the
explicit endpoint instructions.
If the DNS SRV record for mobile device extension has been published, and an identity provided in
the
ProtectionEngine::Settings , no extra code changes are required to use AD RMS. Service discovery
will find the
AD RMS endpoint and use it for protection operations.
If the DNS SRV record isn't published or an identity isn't provided in the
ProtectionEngine::Settings , then the
protection endpoint URL must be set explicitly via SetProtectionCloudEndpointBaseUrl() .