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: Etikettadministratören definierar dessa rättigheter i Microsoft Purview-portal. Dessa etiketter hanteras centralt och konfigurationsändringar 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 har användaren inte längre åtkomst till skyddade data nästa gång de försöker hämta en licens.

  • Användardefinierade behörigheter: Slutanvändaren eller programmet definierar dessa rättigheter vid tidpunkten för etikettering. Skicka behörigheter till MIP SDK i form av en samling mappningar mellan användare och roller eller användare till rättigheter. MIP SDK skriver dessa rättigheter till publiceringslicensen för det skyddade dokumentet. Till skillnad från mallbaserade behörigheter kan du inte centralt hantera eller ändra dessa rättigheter efter delning utan direkt åtkomst och ändring av dokumentet.

Användare, rättigheter och roller

Eftersom användaren definierar rättigheter vid tidpunkten för etikettering måste ditt program tillhandahålla ett gränssnitt för användaren eller tjänsten för att ange e-postadresser och rättigheter eller roller. Om du vill konfigurera åtkomst skickar du in en samling UserRoles eller UserRights objekt som definierar vem som har 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 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 det i samlingen genom att List<UserRights> anropa userRightsList.Add(userRights2).

Samma mönster gäller för UserRoles. Om du vill implementera den ersätter du rättigheter med roller och skapar en List<UserRoles> samling.

Skydda för en domän

För att använda användardefinierade behörigheter för en domän krävs ett välkänt e-postprefix och måldomänen som e-postadress. Den adressen ser ut som 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 lägger det till AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ före domänsuffixet.

Den här välkända gruppen är också hur du beviljar rättigheter till alla autentiserade användare i en organisation. Gruppen AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ innehåller alla användare i den angivna Microsoft Entra klientorganisationen, så det är den närmaste motsvarigheten till gruppen ALLA från služba Active Directory Rights Management Services (AD RMS). Omfattningen avser alltid en enda klientorganisation: det finns ingen identitet över klientorganisationsgränser som ger någon autentiserad användare rättigheter i alla klientorganisationer, så lägg till en separat post av typen AllStaff-...@domain för varje organisation som ska ingå. Mer information finns i Konfigurera användningsrättigheter för Azure Information Protection.

I följande exempel anger användaren alice@contoso.com och hela Fabrikam.com-domänen 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

Om du vill ställa in skydd skapar du en ProtectionDescriptor från objektet List<UserRoles> eller FileHandler.SetProtection() och skickar sedan den beskrivningen till List<UserRights>. 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 ställer in en etikett med FileHandler.SetLabel(), har MIP SDK:n allt som behövs för att vidta åtgärder och tillämpa eventuellt skydd. När en etikett använder användardefinierade behörigheter (UDP) kan ditt program inte 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 processen ä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

Du kan också använda den här processen för att endast ange skydd genom att ange skydd och hoppa över SetLabel() steget. Om programmet inte behöver använda en etikett krävs inte undantagshanteraren. Om du vill ange skydd följer du ProtectionDescriptor mönstret ->SetProtection() ->CommitAsync() .

Nästa steg

  • Uppdaterades senast