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

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

Note

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

Prerequisites

If you haven't already, be sure to:

Service discovery

The MIP SDK automatically discovers the on-premises service endpoint for a FileEngine or ProtectionEngine when you don't provide a service URL explicitly. It uses the user identity provided through 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 information about that process, see Specifying the DNS SRV records for the AD RMS mobile device extension. If that DNS SRV record isn't found, it defaults to the Microsoft Purview Information Protection service as the service location.

Configuring File SDK in C# to use AD RMS

Your application requires two minor changes if it uses the Microsoft Authentication Library (MSAL.NET) and the File SDK on C#. Update the FileEngineSettings object and your MSAL authority configuration to function with AD RMS and Active Directory Federation Services (AD FS).

Note

The Active Directory Authentication Library (ADAL) is deprecated. New applications should use MSAL. For background, see Update your applications to use the Microsoft Authentication Library and Microsoft Graph API.

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 you published the DNS SRV record for MDE and provided Microsoft.InformationProtection.Identity as part of the engine settings, the only required code change is to set FileEngineSettings.ProtectionOnlyEngine = true. You must set this property because AD RMS protection endpoints don't support labeling (policy) operations.

// 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 MSAL.NET in your .NET application, configure the public client application to skip authority validation when targeting an AD FS authority. Set WithAuthority(authority, validateAuthority: false) on the PublicClientApplicationBuilder:

var app = PublicClientApplicationBuilder
    .Create(clientId)
    .WithAuthority(authority, validateAuthority: false)
    .WithRedirectUri(redirectUri)
    .Build();

If you're maintaining a legacy application that still uses the deprecated Active Directory Authentication Library (ADAL), the equivalent change is to pass false for validateAuthority in the AuthenticationContext constructor. Plan to migrate that code to MSAL.

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 you published the DNS SRV record for MDE and provided mip::Identity in the FileEngine::Settings, the only action is to set the engine to a protection-only engine.

FileEngine::Settings engineSettings(mip::Identity(mUsername), authDelegate, "");
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 you published the DNS SRV record for mobile device extension and provided an identity in the ProtectionEngine::Settings, you don't need extra code changes to use AD RMS. Service discovery finds the AD RMS endpoint and uses 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 find that your application has references to labels in the form of fileEngine.SensitivityLabels or engine->ListSensitivityLabels();. Because you set the application to protection only, comment out or remove these blocks of code. Running them causes 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.

  • Last updated on