Microsoft Information Protection SDK - Service Discovery
Overview
The Microsoft Information Protection SDK supports the Azure commercial cloud, sovereign/government clouds and on-premises Active Directory Rights Management Service (AD RMS). There are different mechanisms used to discover which endpoint the SDK should use. This article will cover the discovery mechanisms and how to use each.
Service discovery with mip::Identity
When creating any of the three engine types, the MIP SDK requires that the developer specifies either a mip::Identity
or a mip::Cloud
as part of the engine settings object. Take the File SDK as an example:
FileEngine::Settings engineSettings(mip::Identity(mUsername),
mAuthDelegate,
"",
"en-US",
false);
The FileEngine::Settings
object accepts a mip::Identity
as the first parameter of the constructor. The UPN or email suffix provided via the mip::Identity
is used first to determine whether the enterprise has any Active Directory Rights Management Service (AD RMS) cluster that should be used instead of Azure. This is done by attempting to resolve the _rmsdisco._http._tcp DNS SRV record under the domain suffix obtained from the mip::Identity
. If name resolution fails for this SRV record, the SDK defaults to commercial cloud.
When an AD RMS cluster is found, the
mip::FileEngine::FileEngineSettings
propertyIsProtectionOnlyEngine
must be set to true. The Policy SDK cannot be used in conjuction with AD RMS publishing (Hold Your Own Key).
For example, if the mip::Identity
is Bob@contoso.com, the SDK uses the mail address suffix contoso.com to generate a DNS query for SRV record. If the AD RMS Mobile Device Extensions (MDE) SRV record for Contoso (_rmsdisco._http._tcp.contoso.com) is found, the SDK will attempt to connect to the service referred to by the SRV record. If the Contoso record isn't found, the SDK defaults to the commercial endpoint at https://api.aadrm.com
. For additional details on AD RMS configuration and DNS registration, please review the AD RMS MDE documentation.
Service discovery with mip::Cloud
If the identity of the user isn't know at engine creation, or the customer is in a sovereign cloud that doesn't support implicit service discovery, the mip::Cloud
enum can be used to explicitly tell the SDK which cloud to use.
FileEngine::Settings engineSettings("engineGUID",
mAuthDelegate,
"",
"en-US",
false);
engineSettings.SetCloud(mip::Cloud::US_GCC); // Tell engine to use US_GCC
The above sample passes in some unique engine GUID instead of mip::Identity
and uses the SetCloud()
method on the settings object to tell the SDK to use the United States Government Computing Cloud for both policy and protection functions. Expliticly setting the cloud applies to File, Protection, and Policy SDKs.
Service discovery override with explicit endpoint
The last, least common way that applications can set the service endpoints is to override the service base URL by using one of the following APIs.
SDK | API | Purpose |
---|---|---|
File | SetProtectionCloudEndpointBaseUrl() | Sets the protection endpoint to be used by the engine. |
File | SetPolicyCloudEndpointBaseUrl() | Sets the policy endpoint to be used by the engine. |
Policy | SetCloudEndpointBaseUrl() | Sets the policy endpoint to be used by the engine. |
Protection | SetCloudEndpointBaseUrl() | Sets the protection endpoint to be used by the engine. |
Each can be set on the engine settings object in the relevent engines settings object for that SDK.
Protected Content Consumption
When protected content is consumed by the MIP SDK, service discovery is performed based on the licensing endpoint stored in the protected document. The application must still create a file or protection engine relevent to their own identity. When the mip::FileHandler
object is created, the SDK will parse the license information and connect to the appropriate endpoint. If authentication is required, the user may be prompted to authenticate.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for