Microsoft Information Protection SDK – benutzerdefinierte Berechtigungen

Das Microsoft Information Protection SDK unterstützt zwei primäre Typen von bezeichnungsgesteuerten Berechtigungen: Vorlagenbasierte und benutzerdefinierte Berechtigungen.

  • Vorlagenbasierte Berechtigungen: Diese Rechte werden vom Bezeichnungsadministrator im Security and Compliance Center definiert. Diese Bezeichnungen werden zentral verwaltet, und Änderungen in der Konfiguration wirken sich auf Benutzer aus, die bereits Über Kopien der Dateien verfügen. Wenn der Administrator beispielsweise einen Benutzer aus der Liste der autorisierten Benutzer entfernt, hat dieser Benutzer keinen Zugriff mehr auf die geschützten Daten, wenn er das nächste Mal versucht, eine Lizenz abzurufen.

  • Benutzerdefinierte Berechtigungen: Diese Rechte werden zum Zeitpunkt der Bezeichnung durch den Endbenutzer oder die Anwendung definiert. Berechtigungen werden in Form einer Sammlung von Benutzer-zu-Rollen oder Benutzer-zu-Rechte-Zuordnungen an das MIP SDK übergeben. Diese Rechte werden in die Veröffentlichungslizenz für das geschützte Dokument geschrieben und können im Gegensatz zu vorlagenbasierten Berechtigungen nach der Freigabe ohne direkten Zugriff und Änderung des Dokuments nicht zentral verwaltet oder geändert werden.

Benutzer, Rechte und Rollen

Da es erwartet wird, dass die Rechte zum Zeitpunkt der Kennzeichnung durch den Benutzer definiert werden, muss Ihre Anwendung eine Schnittstelle bereitstellen, die es ermöglicht, Informationen zu den E-Mail-Adressen und den Rechten oder Rollen bereitzustellen, über die der Benutzer verfügt. Diese Konfiguration wird erreicht, indem eine Sammlung von UserRoles- oder UserRights-Objekten übergeben wird, die speziell definieren, wer über welche Zugriffsebene für die Dokumente verfügen soll.

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

Das Ergebnis ist, dass Sie eine List<UserRights> Sammlung haben, die angibt, dass sowohl Alice als auch Bob Ansicht und Bearbeitung in der geschützten Datei haben. Wenn Sie weitere Benutzer mit einer anderen Gruppe von Berechtigungen hinzufügen möchten, wiederholen Sie den Vorgang, um ein zweites UserRights Objekt zu erstellen, indem Sie die neuen Benutzer und Berechtigungen übergeben und dann durch Aufrufen userRightsList.Add(userRights2)der List<UserRights> Sammlung hinzufügen.

Dieses Muster gilt auch für UserRoles und kann einfach implementiert werden, indem Rechte durch Rollen ersetzt und eine List<UserRoles> Sammlung erstellt wird.

Schutz für eine Domäne

Für das Anwenden von benutzerdefinierten Berechtigungen für eine Domäne ist die Verwendung eines bekannten E-Mail-Präfixes und der Zieldomäne als E-Mail-Adresse erforderlich. Diese Adresse sieht wie folgt aus: AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@contoso.com.

In Ihrer Anwendung sollten Benutzer in der Lage sein, eine Domäne wie contoso.com oder fabrikam.com anzugeben. Wenn die Anwendung die Schutzbeschreibung erstellt, muss sie dem Domänensuffix "AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ " vorangestellt werden.

Im folgenden Beispiel gehen wir davon aus, dass der Benutzer alice@contoso.com sowie alle E-Mail-Adressen von Fabrikam.com als gültige Empfänger angegeben hat.

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

Schutz anwenden

Das Festlegen des Schutzes kann erreicht werden, indem ein ProtectionDescriptor-Objekt aus dem List<UserRights>-Objekt oder dem List<UserRoles>-Objekt erstellt und anschließend an FileHandler.SetProtection() übergeben wird. Setzen Sie schließlich die Änderung an die Datei fest, um eine neue Datei zu schreiben.

Wann muss der Schutz auf Dateien angewendet werden?

Wenn Sie ein Label mit FileHandler.SetLabel() dem MIP SDK festlegen, hat es alles, was es braucht, um Maßnahmen zu ergreifen und jeglichen Schutz zu anwenden. Wenn die Bezeichnung für benutzerdefinierte Berechtigungen (UDP) konfiguriert ist, kann Ihre Anwendung nicht vorab wissen, dass es sich bei der Bezeichnung um eine UDP-Bezeichnung handelt. Das MIP SDK zeigt diese Informationen an, indem eine Ausnahme des Typs Microsoft.InformationProtection.Exceptions.AdhocProtectionRequiredExceptionausgelöst wird. Der FileHandler Code sollte diese Ausnahme abfangen und dann die Benutzeroberfläche oder die Dienstschnittstelle veranlassen, um die benutzerdefinierten Berechtigungen zu definieren. Nach Abschluss des Vorgangs können Sie den Schutz festlegen. Das folgende Beispiel zeigt das End-to-End-Muster, geht jedoch davon aus, dass Sie bereits eine Funktion zum Erstellen des List<UserRights> Objekts implementiert haben.

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

Benutzerdefinierter Schutz

Dieser Prozess kann auch verwendet werden, um nur den Schutz festzulegen, indem der Schutz festgelegt und der SetLabel() Schritt übersprungen wird. Wenn Ihre Anwendung keine Bezeichnung anwenden muss, ist der Ausnahmehandler nicht erforderlich, und der Schutz kann festgelegt werden, indem Sie dem Muster ProtectionDescriptor ->SetProtection() ->CommitAsync() folgen.

Nächste Schritte

  • Last updated on