Microsoft Information Protection SDK - user-defined permissions

The Microsoft Information Protection SDK supports two primary types of label-driven permissions: template-based and user-defined.

  • Template-based permissions: The label administrator defines these rights in the Microsoft Purview portal. These labels are centrally managed, and configuration changes affect users who already have copies of the files. For example, if the administrator removes a user from the list of authorized users, that user no longer has access to the protected data the next time they attempt to fetch a license.

  • User-defined permissions: The end user or application defines these rights at the time of labeling. Pass permissions to the MIP SDK in the form of a collection of user-to-roles or users-to-rights mappings. The MIP SDK writes these rights into the publishing license for the protected document. Unlike template-based permissions, you can't centrally manage or modify these rights after sharing without direct access and modification of the document.

Users, rights, and roles

Because the user defines rights at the time of labeling, your application must provide an interface for the user or service to enter email addresses and rights or roles. To configure access, pass in a collection of UserRoles or UserRights objects that define who has what level of access to the documents.

// Create a List<string> of the first set of permissions. 
List<string> users = new List<string>()
{
    "alice@contoso.com",
    "bob@contoso.com"
};

// Create a List<string> of the Rights the above users should have. 
List<string> rights = new List<string>()
{
    Rights.View,
    Rights.Edit                
};

// Create a UserRights object containing the defined users and rights.
UserRights userRights = new UserRights(users, rights);

// Add them to a new List<UserRights>
List<UserRights> userRightsList = new List<UserRights>()
{
    userRights
};

The result is a List<UserRights> collection that specifies that both Alice and Bob have VIEW and EDIT on the protected file. To add more users with a different set of permissions, repeat the process to create a second UserRights object, pass in the new users and permissions, and then add it to the List<UserRights> collection by calling userRightsList.Add(userRights2).

The same pattern applies to UserRoles. To implement it, replace rights with roles and create a List<UserRoles> collection.

Protecting for a domain

Applying user-defined permissions for a domain requires a well-known mail prefix and the target domain as the mail address. That address looks like AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@contoso.com.

In your application, users should be able to specify a domain, like contoso.com or fabrikam.com. When the application creates the protection descriptor, it prepends AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ to the domain suffix.

This well-known group is also how you grant rights to all authenticated users in an organization. The AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ group contains every user in the specified Microsoft Entra tenant, so it's the closest equivalent to the ANYONE group from Active Directory Rights Management Services (AD RMS). Scope is always a single tenant: there's no cross-tenant identity that grants rights to any authenticated user everywhere, so add a separate AllStaff-...@domain entry for each organization you want to include. For more information, see Configure usage rights for Azure Information Protection.

In the following sample, the user specifies alice@contoso.com and all of Fabrikam.com as valid recipients.

// Create a List<string> of the first set of permissions. 
List<string> users = new List<string>()
{
    "alice@contoso.com",
    "AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@fabrikam.com"
};

// Create a List<string> of the Rights the above users should have. 
List<string> rights = new List<string>()
{
    Rights.View,
    Rights.Edit                
};

// Create a UserRights object containing the defined users and rights.
UserRights userRights = new UserRights(users, rights);

// Add them to a new List<UserRights>
List<UserRights> userRightsList = new List<UserRights>()
{
    userRights
};

Apply protection

To set protection, create a ProtectionDescriptor from the List<UserRights> or List<UserRoles> object, and then pass that descriptor to FileHandler.SetProtection(). Finally, commit the change to the file to write a new file.

When to apply protection to files

When you set a label by using FileHandler.SetLabel(), the MIP SDK has all it needs to take action and apply any protection. When a label uses user-defined permissions (UDP), your application has no way to know ahead of time that the label is a UDP label. The MIP SDK surfaces this information by throwing an exception of the type Microsoft.InformationProtection.Exceptions.AdhocProtectionRequiredException. Your FileHandler code should catch this exception, and then trigger your user or service interface to define the custom permissions. After that process is complete, you can set protection. The following example shows the end-to-end pattern, but assumes you've already implemented a function to build the List<UserRights> object.

try
{
    // Attempt to set the label. If it's a UDP label, this will throw. 
    handler.SetLabel(engine.GetLabelById(options.LabelId), labelingOptions, new ProtectionSettings());
}

catch (Microsoft.InformationProtection.Exceptions.AdhocProtectionRequiredException)
{
    // Assumes you've create a function that returns the List<UserRights> as previously detailed. 
    List<UserRights> userRightsList = GetUserRights();

    // Create a ProtectionDescriptor using the set of UserRights.
    ProtectionDescriptor protectionDescriptor = new ProtectionDescriptor(userRightsList);
    
    // Apply protection to the file using the new ProtectionDescriptor. 
    handler.SetProtection(protectionDescriptor, new ProtectionSettings());

    // Set the label. This will now succeed as protection has been defined. 
    handler.SetLabel(engine.GetLabelById(options.LabelId), labelingOptions, new ProtectionSettings());

    // Commit the change. 
    var result = Task.Run(async () => await handler.CommitAsync("myFileOutput.xlsx")).Result;
}

Custom protection

You can also use this process to set only protection by setting protection and skipping the SetLabel() step. If your application doesn't need to apply a label, the exception handler isn't required. To set protection, follow the ProtectionDescriptor -> SetProtection() -> CommitAsync() pattern.

Next steps

  • Last updated on