Microsoft信息保护 SDK - 用户定义的权限

Microsoft信息保护 SDK 支持两种主要类型的标签驱动权限：基于模板和用户定义的权限。

  • 基于模板的权限： 这些权限由安全与合规中心的标签管理员定义。 这些标签是集中管理的，配置中的更改会影响已有文件副本的用户。 例如，如果管理员从授权用户列表中删除用户，则下次尝试提取许可证时，该用户将不再有权访问受保护的数据。

  • 用户定义的权限：最终用户或应用程序 在标记时 定义这些权限。 权限以用户到角色映射或用户到权限映射集合的形式传递给 MIP SDK。 这些权限写入受保护文档的发布许可证中，与基于模板的权限不同，在共享后无法集中管理或修改，而无需直接访问和修改文档。

用户、权限和角色

由于预期在标记时由用户定义权限，因此应用程序必须提供一个界面，使用户或服务能够提供有关用户将拥有的电子邮件地址和权限或角色的输入。 此配置是通过传入一个UserRoles或UserRights对象的集合来完成的，这些对象专门定义谁应该具有什么级别的文档访问权限。

// 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
};

最终结果是你将拥有一个 List<UserRights> 集合，该集合规定 Alice 和 Bob 可以查看和编辑受保护的文件。 若要添加具有不同权限集的更多用户，需要重复此过程以创建第二UserRights个对象，传入新用户和权限，然后通过调用userRightsList.Add(userRights2)添加到List<UserRights>集合中。

此模式也是真实的 UserRoles ，只需将 权限 替换为 角色 并创建 List<UserRoles> 集合即可实现。

保护域

对域应用用户定义的权限需要使用已知的邮件前缀和目标域作为邮件地址。 该地址如下所示： AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@contoso.com。

在应用程序中，用户应能够指定域，例如 contoso.com 或 fabrikam.com。 当应用程序创建保护描述符时，需要将 AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ 追加到域后缀。

在下面的示例中，我们假定用户已指定 alice@contoso.com 以及所有 Fabrikam.com 作为有效收件人。

// 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
};

应用保护

可以通过从List<UserRights>或List<UserRoles>对象创建ProtectionDescriptor，然后将其传递给FileHandler.SetProtection()来实现保护。 最后，提交对文件所做的更改以写入新文件。

何时对文件应用保护

通过 FileHandler.SetLabel() MIP SDK 设置标签时，只需执行操作并应用任何保护。 为用户定义的权限（UDP）配置标签时，应用程序无法提前知道标签是 UDP 标签。 MIP SDK 通过引发类型的 Microsoft.InformationProtection.Exceptions.AdhocProtectionRequiredException异常来显示此信息。 代码 FileHandler 应捕获此异常，然后触发用户或服务接口来定义自定义权限。 完成后，你将能够设置保护。 以下示例演示端到端模式，但假定你已实现一个函数来生成 List<UserRights> 对象。

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;
}

自定义保护

此过程还可用于通过设置保护并跳过 SetLabel() 步骤来仅设置保护。 如果应用程序不需要应用标签，则不需要异常处理程序，并且可以通过遵循 ProtectionDescriptor ->>SetProtection()CommitAsync() 模式来设置保护。

后续步骤

  • Last updated on