Início rápido: inicialização do aplicativo cliente (C#)

  • Artigo

Esse início rápido mostra como implementar o padrão de inicialização do cliente, usado pelo wrapper .NET do SDK da PIM em tempo de execução.

Observação

As etapas descritas neste início rápido são necessárias para todos os aplicativos clientes que usam SDKs de Proteção, de Política ou de Arquivos de wrapper .NET da PIM. Embora esse guia de início rápido demonstre o uso dos SDKs de Arquivo, esse mesmo padrão é aplicável aos clientes que usam os SDKs de Política e de Proteção. Os próximos inícios rápidos devem ser realizados em ordem, pois cada um deles se baseia no anterior e este é o primeiro. Esse código destina-se a demonstrar como começar a usar o SDK da PIM e não se destina ao uso para produção.

Pré-requisitos

Caso ainda não tenha feito, faça o seguinte:

Criar uma solução e um projeto do Visual Studio

Primeiro, criamos e configuramos a solução e o projeto iniciais do Visual Studio, nos quais os outros inícios rápidos serão baseados.

  1. Abra o Visual Studio 2019, selecione o menu Arquivo, Novo, Projeto. Na caixa de diálogo Novo Projeto:

    • No painel esquerdo, em Instalado, Visual C#, selecione Área de Trabalho do Windows.

    • No painel central, selecione Aplicativo de Console (.NET Framework)

    • No painel inferior, atualize corretamente o Nome e a Localização do projeto e o Nome da solução que o contém.

    • Ao terminar, clique no botão OK, no canto inferior direito.

      Visual Studio solution creation

  2. Adicione o pacote Nuget do SDK de Arquivos da PIM ao seu projeto:

    • No Gerenciador de Soluções, clique com o botão direito do mouse sobre o nó do projeto (logo abaixo do nó superior/da solução) e selecione Gerenciar pacotes NuGet...:
    • Quando a guia Gerenciador de Pacotes NuGet for aberta na área de guias do Grupo do Editor:
      • Selecione Procurar.
      • Insira "Microsoft.InformationProtection" na caixa de pesquisa.
      • Selecione o pacote "Microsoft.InformationProtection.File".
      • Clique em "Instalar", depois clique em "OK" quando a caixa de diálogo de confirmação Visualizar alterações for exibida.

  3. Repita as etapas acima para adicionar o pacote do SDK de Arquivo da PIM, mas adicione "Microsoft.Identity.Client" ao aplicativo.

Implementar um representante de autenticação

O SDK da PIM implementa a autenticação usando a extensibilidade de classe, que oferece um mecanismo para compartilhar o trabalho de autenticação com o aplicativo cliente. O cliente precisa adquirir um token de acesso OAuth2 adequado e fornecê-lo ao SDK da PIM no runtime.

Agora, crie uma implementação para um representante de autenticação estendendo a interface Microsoft.InformationProtection.IAuthDelegate do SDK e substituindo/implementando a função virtual IAuthDelegate.AcquireToken(). O representante de autenticação é instanciado e usado mais tarde pelos objetos FileProfile e FileEngine.

  1. Clique com o botão direito do mouse no nome do projeto no Visual Studio, selecione Adicionar e, em seguida, Classe.

  2. Insira "AuthDelegateImplementation" no campo Nome. Clique em Adicionar.

  3. Adicione usando instruções para a MSAL (Biblioteca de Autenticação da Microsoft) e a biblioteca MIP:

    using Microsoft.InformationProtection;
using Microsoft.Identity.Client;

  4. Defina AuthDelegateImplementation para herdar Microsoft.InformationProtection.IAuthDelegate e implementar uma variável privada de Microsoft.InformationProtection.ApplicationInfo e um construtor que aceite o mesmo tipo.

    public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}

    O objeto ApplicationInfo contém três propriedades. _appInfo.ApplicationId será usado na classe AuthDelegateImplementation para fornecer a ID do cliente à biblioteca de autenticação. ApplicationName e ApplicationVersion serão exibidos nos Relatórios de análise da Proteção de Informações do Azure.

  5. Adicione o método public string AcquireToken(). Esse método deve aceitar Microsoft.InformationProtection.Identity e três cadeias de caracteres: URL de autoridade, URI de recurso e declarações, se necessário. Essas variáveis de cadeia de caracteres serão passadas para a biblioteca de autenticação pela API e não devem ser manipuladas. Insira o GUID do locatário do portal do Azure para seu locatário. A edição de cadeia de caracteres diferentes do GUID do locatário pode resultar em falha na autenticação.

    public string AcquireToken(Identity identity, string authority, string resource, string claims)
{
   var authorityUri = new Uri(authority);
   authority = String.Format("https://{0}/{1}", authorityUri.Host, "<Tenant-GUID>");

   _app = PublicClientApplicationBuilder.Create(_appInfo.ApplicationId).WithAuthority(authority).WithDefaultRedirectUri().Build();
   var accounts = (_app.GetAccountsAsync()).GetAwaiter().GetResult();

   // Append .default to the resource passed in to AcquireToken().
   string[] scopes = new string[] { resource[resource.Length - 1].Equals('/') ? $"{resource}.default" : $"{resource}/.default" };
   var result = _app.AcquireTokenInteractive(scopes).WithAccount(accounts.FirstOrDefault()).WithPrompt(Prompt.SelectAccount)
              .ExecuteAsync().ConfigureAwait(false).GetAwaiter().GetResult();

   return result.AccessToken;
}

Agora crie uma implementação para um representante de consentimento estendendo a interface Microsoft.InformationProtection.IConsentDelegate do SDK e substituindo/implementando GetUserConsent(). Uma instância do representante de consentimento é criada e será usada mais tarde pelos objetos Perfil de arquivo e Mecanismo de arquivo. O representante de consentimento recebe o endereço do serviço para o qual o usuário deve dar consentimento usando o parâmetro url. O representante geralmente deve fornecer algum fluxo que permita que o usuário aceite ou rejeite o consentimento para acesso ao serviço. Para este início rápido embutido em código Consent.Accept.

  1. Usando o mesmo recurso "Adicionar Classe" do Visual Studio usado anteriormente, adicione outra classe ao seu projeto. Dessa vez, insira "ConsentDelegateImplementation" no campo Nome da Classe.

  2. Agora, atualize ConsentDelegateImpl.cs para implementar sua nova classe representante de consentimento. Adicione a instrução using para Microsoft.InformationProtection e defina a classe para herdar IConsentDelegate.

    class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}

  3. Opcionalmente, tente compilar a solução para garantir que ela seja compilada sem erros.

Inicializar o wrapper gerenciado do SDK da PIM

  1. No Gerenciador de Soluções, abra o arquivo .cs no projeto que contém a implementação do método Main(). Ele usa como padrão o mesmo nome que o projeto em que está contido, que você especificou durante a criação do projeto.

  2. Remova a implementação gerada de main().

  3. O wrapper gerenciado inclui uma classe estática, Microsoft.InformationProtection.MIP, usada para inicialização, criando um MipContext, carregando perfis e liberando recursos. Para inicializar o wrapper para operações no SDK de Arquivo, chame MIP.Initialize(), passando MipComponent.File para carregar as bibliotecas necessárias para as operações com arquivos.

  4. Em Main() em Program.cs, adicione o seguinte, substituindo <application-id> pela ID do Registro de Aplicativo do Microsoft Entra criado anteriormente.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.Exceptions;
using Microsoft.InformationProtection.File;
using Microsoft.InformationProtection.Protection;

namespace mip_sdk_dotnet_quickstart
{
    class Program
    {
        private const string clientId = "<application-id>";
        private const string appName = "<friendly-name>";

        static void Main(string[] args)
        {
            //Initialize Wrapper for File SDK operations
            MIP.Initialize(MipComponent.File);
            
        }
    }
}

Construir um Mecanismo e um Perfil de Arquivo

Como já foi mencionado, os objetos Perfil e Mecanismo são necessários para os clientes do SDK que usam as APIs da PIM. Conclua a parte de codificação deste início rápido, adicionando código para carregar as DLLs nativas e então instanciar os objetos Perfil e Mecanismo.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.File;

namespace mip_sdk_dotnet_quickstart
{
  class Program
  {
       private const string clientId = "<application-id>";
       private const string appName = "<friendly-name>";

       static void Main(string[] args)
       {
            // Initialize Wrapper for File SDK operations.
            MIP.Initialize(MipComponent.File);

            // Create ApplicationInfo, setting the clientID from Microsoft Entra App Registration as the ApplicationId.
            ApplicationInfo appInfo = new ApplicationInfo()
            {
                 ApplicationId = clientId,
                 ApplicationName = appName,
                 ApplicationVersion = "1.0.0"
            };

            // Instantiate the AuthDelegateImpl object, passing in AppInfo.
            AuthDelegateImplementation authDelegate = new AuthDelegateImplementation(appInfo);

            // Create MipConfiguration Object
            MipConfiguration mipConfiguration = new MipConfiguration(appInfo, "mip_data", LogLevel.Trace, false);

            // Create MipContext using Configuration
            MipContext mipContext = MIP.CreateMipContext(mipConfiguration);

            // Initialize and instantiate the File Profile.
            // Create the FileProfileSettings object.
            // Initialize file profile settings to create/use local state.
            var profileSettings = new FileProfileSettings(mipContext,
                                     CacheStorageType.OnDiskEncrypted,
                                     new ConsentDelegateImplementation());

            // Load the Profile async and wait for the result.
            var fileProfile = Task.Run(async () => await MIP.LoadFileProfileAsync(profileSettings)).Result;

            // Create a FileEngineSettings object, then use that to add an engine to the profile.
            // This pattern sets the engine ID to user1@tenant.com, then sets the identity used to create the engine.
            var engineSettings = new FileEngineSettings("user1@tenant.com", authDelegate, "", "en-US");
            engineSettings.Identity = new Identity("user1@tenant.com");

            var fileEngine = Task.Run(async () => await fileProfile.AddEngineAsync(engineSettings)).Result;

            // Application Shutdown
            // handler = null; // This will be used in later quick starts.
            fileEngine = null;
            fileProfile = null;
            mipContext.ShutDown();
            mipContext = null;
       }
  }
}

  1. Substitua os valores de espaço reservado no código-fonte que você colou, usando os seguintes valores:

    Espaço reservado Valor Exemplo
    <application-id> ID de Aplicativo do Microsoft Entra atribuída ao aplicativo registrado na "Instalação e configuração do SDK da PIM" (2 instâncias). 0edbblll-8773-44de-b87c-b8c6276d41eb
    <friendly-name> Um nome amigável definido pelo usuário para o seu aplicativo. AppInitialization
    <Tenant-GUID> ID do seu locatário do Microsoft Entra TenantID

  2. Agora, faça uma compilação final do aplicativo e resolva todos os erros. Seu código deve ser compilado com sucesso.

Próximas etapas

Agora que o seu código de inicialização está completo, você está pronto para o próximo início rápido, onde começará a experimentar os SDKs de arquivo da PIM.

Listar rótulos de confidencialidade