Microsoft Information Protection SDK - permissões definidas pelo utilizador

O SDK Microsoft Information Protection suporta dois tipos principais de permissões orientadas por rótulos: baseadas em modelos e definidas pelo utilizador.

  • Permissões baseadas em modelos: O administrador da etiqueta define estes direitos no portal do Microsoft Purview. Estas etiquetas são geridas centralmente, e as alterações de configuração afetam utilizadores que já possuem cópias dos ficheiros. Por exemplo, se o administrador remover um utilizador da lista de utilizadores autorizados, esse utilizador deixará de ter acesso aos dados protegidos na próxima vez que tentar obter uma licença.

  • Permissões definidas pelo utilizador: O utilizador final ou a aplicação define estes direitos no momento da rotulagem. Transmita permissões para o SDK do MIP na forma de uma coleção de mapeamentos entre utilizadores e funções ou entre utilizadores e direitos. O SDK MIP insere estes direitos na licença de publicação do documento protegido. Ao contrário das permissões baseadas em modelos, não pode gerir nem modificar centralmente estes direitos depois de o partilhar, sem aceder diretamente ao documento e o modificar.

Utilizadores, direitos e funções

Como o utilizador define direitos no momento da rotulagem, a sua aplicação deve fornecer uma interface para que o utilizador ou serviço possa inserir endereços de email e direitos ou funções. Para configurar o acesso, passe uma coleção de UserRoles ou UserRights objetos que definam quem tem que nível de acesso aos 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
};

O resultado é uma coleção List<UserRights> que especifica que tanto a Alice como o Bob têm permissões de VER e EDITAR sobre o ficheiro protegido. Para adicionar mais utilizadores com um conjunto diferente de permissões, repita o processo para criar um segundo UserRights objeto, passe os novos utilizadores e permissões, e depois adicione-o à List<UserRights> coleção chamando userRightsList.Add(userRights2).

O mesmo padrão aplica-se a UserRoles. Para o implementar, substitua permissões por funções e crie uma coleção List<UserRoles>.

Proteção de um domínio

Aplicar permissões definidas pelo utilizador para um domínio requer um prefixo de email bem conhecido e o domínio de destino como endereço de email. Esse endereço parece ser AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@contoso.com.

Em seu aplicativo, os usuários devem ser capazes de especificar um domínio, como contoso.com ou fabrikam.com. Quando a aplicação cria o descritor de proteção, antepõe AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ ao sufixo do domínio.

Este grupo bem conhecido é também a forma como se concedem direitos a todos os utilizadores autenticados numa organização. O grupo AllStaff-7184AB3F-CCD1-46F3-8233-3E09E9CF0E66@ inclui todos os utilizadores no inquilino Microsoft Entra especificado, pelo que é o equivalente mais próximo ao grupo ANYONE do Active Directory Rights Management Services (AD RMS). O âmbito é sempre um único inquilino: não existe uma identidade entre inquilinos que conceda direitos a qualquer utilizador autenticado em todo o lado, por isso adiciona uma entrada separada AllStaff-...@domain para cada organização que queiras incluir. Para obter mais informações, veja Configurar direitos de utilização para o Azure Information Protection.

No exemplo seguinte, o utilizador especifica alice@contoso.com e todos os Fabrikam.com como destinatários 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
};

Aplicar proteção

Para definir proteção, crie um ProtectionDescriptor objeto a partir do List<UserRights> ou List<UserRoles> e depois passe esse descritor para FileHandler.SetProtection(). Finalmente, confirme a alteração no arquivo para gravar um novo arquivo.

Quando aplicar proteção a arquivos

Quando defines um rótulo usando FileHandler.SetLabel(), o SDK MIP tem tudo o que precisa para agir e aplicar qualquer proteção. Quando um rótulo usa permissões definidas pelo utilizador (UDP), a sua aplicação não tem forma de saber antecipadamente que o rótulo é um rótulo UDP. O SDK MIP exibe essas informações lançando uma exceção do tipo Microsoft.InformationProtection.Exceptions.AdhocProtectionRequiredException. O seu FileHandler código deve detetar esta exceção e depois acionar a sua interface de utilizador ou de serviço para definir as permissões personalizadas. Depois de concluído esse processo, pode definir a proteção. O exemplo seguinte mostra o padrão de ponta a ponta, mas assume que já implementaste uma função para construir o 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;
}

Proteção alfandegária

Também pode utilizar este processo para configurar apenas a proteção, configurando a proteção e ignorando a etapa SetLabel(). Se a sua candidatura não precisar de aplicar um rótulo, o responsável pelas exceções não é obrigatório. Para definir proteção, segue o ProtectionDescriptor padrão ->SetProtection() ->CommitAsync() .

Passos seguintes

  • Última atualização a