Concept - delegation in the MIP SDK

The Microsoft Information Protection SDK provides two paths for service-based applications to act on behalf of another user. Delegation might be necessary when files need to be labeled, protected, or consumed in the context of a user identity different from the service identity. The application can set this delegated identity at the engine or handler level. The location depends on the use case.

Engine settings-based delegation

The MIP SDK supports providing a delegated user email address in the settings object for the File, Protection, and Policy SDKs. Set the DelegatedUserEmail property on the settings object. The engine initialized with that settings object performs all MIP operations as though it's the user provided to the DelegatedUserEmail property. The SDK fetches policy for that specific user and performs all protection operations as that user, including making the user the owner of protected files.

This pattern is useful when your service-based application needs to operate fully as the user. The application needs to fetch policy only for the specified user and perform any decryption operations in the context of the user identity. When you create this engine, specify an engine ID that's unique to that user, often the mail address. A unique engine ID helps the SDK use caching effectively. If you don't provide a unique engine ID, your application might experience poor performance.

File SDK

The following sample illustrates how to set the delegated identity for a File SDK application in C++ and C#. You can use the same pattern for the Policy SDK.

This sample shows how to create a delegate engine in File SDK in .NET.

// C# Example for creating a delegated file engine
string delegatedUserEmail = "alice@contoso.com";
var engineSettings = new PolicyEngineSettings(delegatedUserEmail, authDelegate, "", "en-US")
{
    // Provide the identity for service discovery.
    Identity = identity,
    // Set the identity for which all MIP operations will be performed.
    DelegatedUserEmail = delegatedUserEmail
};

var engine = Task.Run(async () => await profile.AddEngineAsync(engineSettings)).Result;

This sample shows how to create a delegate engine in File SDK in C++.

// C++ Example for creating a delegated file engine
std::string delegatedUserEmail = "alice@contoso.com";
FileEngine::Settings engineSettings(delegatedUserEmail, mAuthDelegate, "", "en-US", false);
// Set the identity for which all MIP operations will be performed. 
engineSettings.SetDelegatedUserEmail(delegatedUserEmail);

auto enginePromise = std::make_shared<std::promise<std::shared_ptr<FileEngine>>>();
auto engineFuture = enginePromise->get_future();

mProfile->AddEngineAsync(engineSettings, enginePromise);
mEngine = engineFuture.get();

The SDK creates all file engines on behalf of the specified user.

Handler-based delegation

When your application needs only to protect files in the context of a specific user identity, the FileHandler provides a method for passing in the user identity by using a ProtectionSettings object. The authenticated service identity performs policy and decryption operations. The protection action occurs on behalf of the specified user, and that user becomes the owner of MIP protection on the document.

File SDK

File SDK performs only direct or label-based protection as the user provided to the ProtectionSettings object. Pass this object to the SetLabel() or SetProtection() functions in File SDK.

This sample shows how to perform a delegate protection operation in File SDK in .NET.

string delegatedUserEmail = "bob@contoso.com";
ProtectionSettings protectionSettings = new ProtectionSettings()
{
    // Set the delegated mail address 
    DelegatedUserEmail = delegatedUserEmail
};
handler.SetLabel(engine.GetLabelById(options.LabelId), labelingOptions, protectionSettings);
// Similar pattern for SetProtection()
// handler.SetProtection(protectionDescriptor, protectionSettings);

This sample shows how to perform a delegate protection operation in File SDK in C++.

mip::ProtectionSettings protectionSettings;
// Set the delegated mail address 
protectionSettings.SetDelegatedUserEmail(delegatedUserEmail);
handler->SetLabel(mEngine->GetLabelById(labelId), labelingOptions, protectionSettings);

All handler write operations that apply protection run as the delegated user.

Protection SDK

The Protection SDK functions differently than the File SDK. You can create two types of handlers, one for publishing and one for consumption. Similar to the File SDK, set the delegated mail address by using the settings object for each type of handler.

.NET

This sample demonstrates how to perform delegated publishing.

string delegatedUserEmail = "bob@contoso.com";
PublishingSettings publishingSettings = new PublishingSettings(protectionDescriptor)
{
    // Set the delegated mail address 
    DelegatedUserEmail = delegatedUserEmail
};          
var protectionHandler = engine.CreateProtectionHandlerForPublishing(publishingSettings);

This sample demonstrates how to perform delegated consumption.

string delegatedUserEmail = "bob@contoso.com";
ConsumptionSettings consumptionSettings = new ConsumptionSettings(plInfo)
{                
    ContentName = "A few bytes.",
    // Set the delegated mail address 
    DelegatedUserEmail = delegatedUserEmail
};
var protectionHandler = engine.CreateProtectionHandlerForConsumption(consumptionSettings);

C++

This sample demonstrates how to perform delegated publishing.

string delegatedUserEmail = "bob@contoso.com";
mip::ProtectionHandler::PublishingSettings publishingSettings = mip::ProtectionHandler::PublishingSettings(descriptor);
// Set the delegated mail address 
publishingSettings.SetDelegatedUserEmail(delegatedUserEmail);
mEngine->CreateProtectionHandlerForPublishingAsync(publishingSettings, handlerObserver, handlerPromise);
auto handler = handlerFuture.get();	

This sample demonstrates how to perform delegated consumption.

string delegatedUserEmail = "bob@contoso.com";
mip::ProtectionHandler::ConsumptionSettings consumptionSettings = mip::ProtectionHandler::ConsumptionSettings(serializedPublishingLicense);
// Set the delegated mail address 
consumptionSettings.SetDelegatedUserEmail(delegatedUserEmail);
mEngine->CreateProtectionHandlerForConsumptionAsync(consumptionSettings, handlerObserver, handlerPromise);
auto handler = handlerFuture.get();	

Required permissions

Each scenario requires a different set of permissions.

Scenario	Permission required
File SDK Delegated Engine	UnifiedPolicy.Tenant.Read Content.DelegatedReader Content.DelegatedWriter
Policy SDK Delegated Engine	UnifiedPolicy.Tenant.Read
File SDK Delegated Handler	Content.DelegatedWriter
Protection SDK Delegated Publish	Content.DelegatedWriter
Protection SDK Delegated Consumption	Content.DelegatedReader

For a full review of permissions and where to set them, see API permissions for the Microsoft Information Protection SDK.

Next steps

• API permissions for the Microsoft Information Protection SDK