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 SDK for C# or C++ and Protection SDK for C++ only.

Prerequisites

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.

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.

Configuring File SDK in C# to use AD RMS

Two minor changes are required if your application is using Active Directory Authentication Library (ADAL) and the File SDK 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.

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 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 SDK 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.

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;

Configuring Protection SDK 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.

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, "");

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.