SDK de Microsoft Information Protection: permisos definidos por el usuario

El SDK de Microsoft Information Protection admite dos tipos principales de permisos controlados por etiquetas: basado en plantillas y definidos por el usuario.

  • Permisos basados en plantillas: Estos derechos se definen mediante el administrador de etiquetas en el Centro de seguridad y cumplimiento. Estas etiquetas se administran de forma centralizada y los cambios en la configuración afectarán a los usuarios que ya tienen copias de los archivos. Por ejemplo, si el administrador quita un usuario de la lista de usuarios autorizados, ese usuario ya no tendrá acceso a los datos protegidos la próxima vez que intente capturar una licencia.

  • Permisos definidos por el usuario: estos derechos se definen en el momento de etiquetar por el usuario final o la aplicación. Los permisos se pasan al SDK de MIP en forma de una colección de asignaciones de usuarios a roles o usuarios a derechos. Estos derechos se escriben en la licencia de publicación para el documento protegido y, a diferencia de los permisos basados en plantillas, no se pueden administrar o modificar centralmente después del uso compartido sin acceso directo y modificación del documento.

Usuarios, derechos y roles

Dado que se espera que el usuario defina los derechos en el momento del etiquetado, la aplicación debe proporcionar una interfaz para permitir que el usuario o el servicio proporcionen una entrada en las direcciones de correo electrónico y los derechos o roles que tendrá el usuario. Esta configuración se logra pasando una colección de UserRoles objetos o UserRights que definen específicamente quién debe tener el nivel de acceso a los documentos.

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

El resultado es una colección de List<UserRights> que especifica que Alice y Bob tienen los derechos VIEW y EDIT para el archivo protegido. Para agregar más usuarios con un conjunto diferente de permisos, repetiría el proceso para crear un segundo UserRights objeto, pasando los nuevos usuarios y permisos, y luego agregar a la List<UserRights> colección al llamar a userRightsList.Add(userRights2).

Este patrón también es cierto para UserRoles y se puede implementar simplemente reemplazando los derechos por roles y crear una List<UserRoles> colección.

Protección de un dominio

La aplicación de permisos definidos por el usuario para un dominio requiere el uso de un prefijo de correo conocido y el dominio de destino como dirección de correo. Esa dirección tiene el siguiente aspecto: AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@contoso.com.

En la aplicación, los usuarios deben poder especificar un dominio, como contoso.com o fabrikam.com. Cuando la aplicación crea el descriptor de protección, deberá anteponer AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ al sufijo de dominio.

En el ejemplo siguiente, se supone que el usuario ha especificado alice@contoso.com y todos los Fabrikam.com como destinatarios válidos.

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

Aplicación de protección

La protección se puede establecer creando un ProtectionDescriptor desde el objeto List<UserRights> o List<UserRoles>, y luego pasándolo a FileHandler.SetProtection(). Por último, confirme el cambio en el archivo para escribir un archivo nuevo.

Cuándo aplicar protección a los archivos

Cuando estableces una etiqueta a través del FileHandler.SetLabel() SDK de MIP, este cuenta con todo lo necesario para tomar medidas y aplicar cualquier protección. Cuando la etiqueta está configurada para permisos definidos por el usuario (UDP), la aplicación no tiene forma de saber con antelación que la etiqueta es una etiqueta UDP. El SDK de MIP muestra esta información lanzando una excepción del tipo Microsoft.InformationProtection.Exceptions.AdhocProtectionRequiredException. El FileHandler código debe detectar esta excepción y, a continuación, desencadenar la interfaz de usuario o servicio para definir los permisos personalizados. Una vez completado, podrá establecer la protección. En el ejemplo siguiente se muestra el patrón de un extremo a otro, pero se supone que ya ha implementado una función para compilar el List<UserRights> objeto.

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

Protección personalizada

Este proceso también se puede usar para establecer solo la protección estableciendo la protección y omitiendo el SetLabel() paso. Si la aplicación no necesita aplicar una etiqueta, el controlador de excepciones no es necesario y la protección se puede establecer siguiendo el ProtectionDescriptor patrón - ->SetProtection()>CommitAsync() .

Pasos siguientes

  • Last updated on