Microsoft Information Protection SDK – användardefinierade behörigheter

Microsoft Information Protection SDK stöder två primära typer av etikettdrivna behörigheter: Mallbaserad och användardefinierad.

  • Mallbaserade behörigheter: Dessa rättigheter definieras av etikettadministratören i Security and Compliance Center. Dessa etiketter hanteras centralt och ändringar i konfigurationen påverkar användare som redan har kopior av filerna. Om administratören till exempel tar bort en användare från listan över behöriga användare kommer användaren inte längre att ha åtkomst till skyddade data nästa gång de försöker hämta en licens.

  • Användardefinierade behörigheter: Dessa rättigheter definieras vid tidpunkten för etikettering av slutanvändaren eller programmet. Behörigheter skickas till MIP SDK i form av en samling mappningar från användare till roller eller användare till rättigheter. Dessa rättigheter är skrivna i publiceringslicensen för det skyddade dokumentet och kan, till skillnad från mallbaserade behörigheter, inte hanteras centralt eller ändras efter delning utan direkt åtkomst och ändring av dokumentet.

Användare, rättigheter och roller

Eftersom det förväntas att rättigheter definieras av användaren vid tidpunkten för etikettering, måste ditt program tillhandahålla ett gränssnitt som gör att användaren eller tjänsten kan ange indata för de e-postadresser och rättigheter eller roller som användaren kommer att ha. Den här konfigurationen utförs genom att skicka in en samling UserRoles eller UserRights objekt som specifikt definierar vem som ska ha vilken åtkomstnivå till dokumenten.

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

Resultatet är att du har en List<UserRights> samling som anger att både Alice och Bob har VIEW och EDIT på den skyddade filen. Om du vill lägga till fler användare med en annan uppsättning behörigheter upprepar du processen för att skapa ett andra UserRights objekt, skickar in de nya användarna och behörigheterna och lägger sedan till i List<UserRights> samlingen genom att anropa userRightsList.Add(userRights2).

Det här mönstret gäller även för UserRoles och kan implementeras genom att helt enkelt ersätta rättigheter med roller och skapa en List<UserRoles> samling.

Skydda för en domän

Användning av användardefinierade behörigheter för en domän kräver att du använder ett välkänt e-postprefix och måldomänen som e-postadress. Adressen ser ut så här: AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@contoso.com.

I ditt program bör användarna kunna ange en domän, till exempel contoso.com eller fabrikam.com. När programmet skapar skyddsbeskrivningen måste det lägga till AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ till domänsuffixet.

I exemplet nedan antar vi att användaren har angett alice@contoso.com och alla Fabrikam.com som giltiga mottagare.

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

Tillämpa skydd

Du kan uppnå skydd för inställningar genom att skapa en ProtectionDescriptor från List<UserRights>- eller List<UserRoles>-objektet, och sedan skicka den till FileHandler.SetProtection(). Genomför slutligen ändringen i filen för att skriva en ny fil.

När du ska tillämpa skydd på filer

När du anger en etikett via FileHandler.SetLabel() MIP SDK har allt den behöver för att vidta åtgärder och tillämpa alla skydd. När etiketten har konfigurerats för användardefinierade behörigheter (UDP) har ditt program inget sätt att veta i förväg att etiketten är en UDP-etikett. MIP SDK visar den här informationen genom att utlösa ett undantag av typen Microsoft.InformationProtection.Exceptions.AdhocProtectionRequiredException. Koden FileHandler bör fånga det här undantaget och sedan utlösa användar- eller tjänstgränssnittet för att definiera de anpassade behörigheterna. När du är klar kan du ange skydd. I följande exempel visas mönstret från slutpunkt till slutpunkt, men förutsätter att du redan har implementerat en funktion för att skapa List<UserRights> objektet.

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

Anpassat skydd

Den här processen kan också användas för att endast ange skydd genom att ange skydd och hoppa över SetLabel() steget. Om ditt program inte behöver använda en etikett krävs inte undantagshanteraren och skydd kan anges genom att följa ProtectionDescriptor ->SetProtection() ->CommitAsync() mönstret.

Nästa steg

  • Last updated on