Quickstart: Active Directory Rights Management Server (AD RMS) Protection

This quickstart will show you how to implement support for Active Directory Rights Management Server (AD RMS) using MIP SDK.

Note

The steps outlined in this quickstart applicable to only File API for C# or C++ and Protection API for C++ only.

Prerequisites

If you haven't already, be sure to:

Service Discovery

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.

Configuring File API in C# to use AD RMS

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.

Update the File Engine Settings to use AD RMS with an Identity

If the DNS SRV record for MDE has been published and Microsoft.InformationProtection.Identity has been provided as part of the engine settings, the only required code change is to set FileEngineSettings.ProtectionOnlyEngine = 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

If the DNS SRV record for MDE isn't published, or Microsoft.InformationProtection.Identity isn't available to pass in when creating the FileEngine, there are two required code changes. is to set FileEngineSettings.ProtectionOnlyEngine = true. This property must be set as labeling (policy) operations aren't supported for AD RMS protection endpoints.

// 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 = "https://rms.contoso.com"
};

Update the authentication delegate

If you're using the ADAL in your .NET application, you'll need to make a change to the Microsoft.InformationProtection.AuthDelegate implementation to disable authority validation. Disable authority validation by setting validateAuthority in the AuthenticationContext constructor to false.

AuthenticationContext authContext = new AuthenticationContext(authority, false, tokenCache);

Configuring File API in C++ to use AD RMS

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.

Update the FileEngine::Settings to use AD RMS with an Identity

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.

FileEngine::Settings engineSettings(mip::Identity(mUsername), "");
engineSettings.SetProtectionOnlyEngine = true;

Update the FileEngine::Settings to use AD RMS with an explicit endpoint

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, "");
engineSettings.SetProtectionOnlyEngine = true;
engineSettings.SetProtectionCloudEndpointBaseUrl("https://rms.contoso.com");

Configuring Protection API in C++ to use AD RMS

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.

Set the ProtectionEngine::Settings to use AD RMS with an Identity

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.

ProtectionEngine::Settings engineSettings(mip::Identity(mUsername), authDelegate, "");

Set the ProtectionEngine::Settings to use AD RMS with an explicit endpoint

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().

ProtectionEngine::Settings engineSettings("", authDelegate, "");
engineSettings.SetProtectionCloudEndpointBaseUrl("https://RMS.CONTOSO.COM");

Remove or Comment Label References

If you build the application from one of the quickstart guides, you'll find that your application has references to labels in the form of fileEngine.SensitivityLabels or engine->ListSensitivityLabels();. Because the application has been set to protection only, these blocks of code must be commented out or removed as running them will cause an exception.

Next Steps

Now that you've made the changes to support AD RMS, your application can perform any protection-only operations using the AD RMS service as the protection provider.