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: Der Bezeichnungsadministrator definiert diese Rechte im Microsoft Purview-Portal. Diese Bezeichnungen werden zentral verwaltet, und Konfigurationsänderungen 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: Der Endbenutzer oder die Anwendung definiert diese Rechte zum Zeitpunkt der Bezeichnung. Übergeben Sie Berechtigungen an das MIP SDK als Sammlung von Zuordnungen von Benutzern zu Rollen bzw. von Benutzern zu Rechten. Das MIP SDK schreibt diese Rechte in die Veröffentlichungslizenz für das geschützte Dokument. Im Gegensatz zu vorlagenbasierten Berechtigungen können Sie diese Rechte nach der Freigabe nicht zentral verwalten oder ändern, ohne direkt auf das Dokument zuzugreifen und es zu ändern.

Benutzer, Rechte und Rollen

Da der Benutzer rechte zum Zeitpunkt der Bezeichnung definiert, muss Ihre Anwendung eine Benutzeroberfläche für den Benutzer oder Dienst bereitstellen, um E-Mail-Adressen und Rechte oder Rollen einzugeben. Übergeben Sie zum Konfigurieren des Zugriffs eine Sammlung von UserRoles- oder UserRights-Objekten, die definieren, wer welche Zugriffsebene auf die Dokumente hat.

// 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 eine List<UserRights> Sammlung, die angibt, dass sowohl Alice als auch Bob über die Berechtigungen VIEW und EDIT für die geschützte Datei verfügen. 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, übergeben Sie die neuen Benutzer und Berechtigungen, und fügen Sie sie dann durch Aufrufen userRightsList.Add(userRights2)der List<UserRights> Auflistung hinzu.

Das gleiche Muster gilt für UserRoles. Zur Implementierung ersetzen Sie Rechte durch Rollen und erstellen eine List<UserRoles> Sammlung.

Schutz für eine Domäne

Das Anwenden von benutzerdefinierten Berechtigungen für eine Domäne erfordert ein bekanntes E-Mail-Präfix und die Zieldomäne als E-Mail-Adresse. Diese Adresse sieht wie folgt AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@contoso.comaus.

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

Diese bekannte Gruppe ist auch, wie Sie allen authentifizierten Benutzern in einer Organisation Rechte gewähren. Die Gruppe AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ enthält jeden Benutzer im angegebenen Microsoft Entra-Mandanten und entspricht damit am ehesten der Gruppe ANYONE aus Active Directory Rights Management Services (AD RMS). Der Geltungsbereich ist immer auf einen einzelnen Mandanten beschränkt: Es gibt keine mandantenübergreifende Identität, die jedem authentifizierten Benutzer überall Berechtigungen verleiht, fügen Sie also für jede Organisation, die Sie einbeziehen möchten, einen separaten AllStaff-...@domain Eintrag hinzu. Weitere Informationen finden Sie unter Konfigurieren von Nutzungsrechten für Azure-Informationsschutz.

Im folgenden Beispiel gibt der Benutzer alice@contoso.com und ganz Fabrikam.com als gültige Empfänger an.

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

Um den Schutz festzulegen, erstellen Sie einen ProtectionDescriptor aus dem Objekt List<UserRights> oder List<UserRoles> und übergeben Sie diesen Deskriptor dann an FileHandler.SetProtection(). 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 mithilfe von FileHandler.SetLabel() eine Bezeichnung festlegen, verfügt das MIP SDK über alles, was es benötigt, um entsprechende Maßnahmen zu ergreifen und den entsprechenden Schutz anzuwenden. Wenn eine Bezeichnung benutzerdefinierte Berechtigungen (UDP) verwendet, hat Ihre Anwendung keine Möglichkeit, vorab zu 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. Ihr FileHandler-Code sollte diese Ausnahme abfangen und dann Ihre Benutzer- oder Dienstschnittstelle veranlassen, die benutzerdefinierten Berechtigungen zu definieren. Nachdem dieser Vorgang abgeschlossen ist, können Sie den Schutz festlegen. Das folgende Beispiel zeigt das End-to-End-Muster, es wird jedoch davon ausgegangen, 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

Sie können diesen Prozess auch verwenden, um nur den Schutz festzulegen, indem Sie den Schutz festlegen und den SetLabel() Schritt überspringen. Wenn Ihre Anwendung keine Bezeichnung anwenden muss, ist der Ausnahmehandler nicht erforderlich. Zum Festlegen des Schutzes folgen Sie dem ProtectionDescriptor Muster ->SetProtection() ->CommitAsync() .

Nächste Schritte

  • Zuletzt aktualisiert um