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

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.

Pré-requisitos

Caso ainda não tenha feito isso, certifique-se de:

• Conclua as etapas na configuração e configuração do SDK da Proteção de Informações da Microsoft (MIP). Este início rápido "Inicialização do aplicativo cliente" se baseia na instalação e configuração adequadas do SDK.
• Opcionalmente:
  • Examine o perfil e os objetos do mecanismo. Os objetos de perfil e motor são conceitos universais, necessários para clientes que usam os SDKs de Arquivo/Política/Proteção da MIP.
  • Examine os conceitos de Autenticação para saber como a autenticação e o consentimento são implementados pelo SDK e pelo aplicativo cliente.

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 criados.

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 o nome do projeto, o local e o nome da solução que contém adequadamente.

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

     

2. Adicione o pacote NuGet para o SDK de Arquivo MIP ao seu projeto:

   • No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto (diretamente no nó superior/solução) e selecione Gerenciar pacotes NuGet...:
   • Quando a guia Gerenciador de Pacotes NuGet é aberta na área de guias Grupo do Editor:
     • Selecione Procurar.
     • Insira "Microsoft.InformationProtection" na caixa de pesquisa.
     • Selecione o pacote "Microsoft.InformationProtection.File".
     • Clique em "Instalar" e, em seguida, 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 MIP File SDK, mas em vez disso adicione "Microsoft.Identity.Client" ao aplicativo.

Implementar um delegado de autenticação

O SDK do MIP implementa a autenticação usando extensibilidade de classe, que fornece um mecanismo para compartilhar o trabalho de autenticação com o aplicativo cliente. O cliente deve adquirir um token de acesso OAuth2 adequado e fornecer ao SDK do MIP em runtime.

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

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

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

3. Adicione instruções de uso 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 implemente uma variável privada do tipo 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 ApplicationInfo objeto 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 auditoria do Microsoft Purview.

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 cadeias de caracteres diferentes do GUID do Locatário pode resultar em uma 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;
   }
   
   

Implementar um delegado de consentimento

Agora, crie uma implementação para um delegado de consentimento, estendendo a interface do Microsoft.InformationProtection.IConsentDelegate 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 delegado de consentimento é fornecido com o endereço do serviço que o usuário deve consentir em usar no url parâmetro. O delegado geralmente deve fornecer algum fluxo que permita que o usuário aceite ou rejeite o consentimento para acessar o serviço. Para este início rápido embutido em código Consent.Accept.

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

2. Agora atualize ConsentDelegateImpl.cs para implementar sua nova classe de delegado 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 criar 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 em seu projeto que contém a implementação do Main() método. Ele usa como padrão o mesmo nome do projeto que o contém, 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, criação de um MipContext, carregamento de perfis e liberação de 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. No Main()Program.cs adicione o seguinte, substituindo <application-id> pelo 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

Conforme mencionado, os objetos de perfil e mecanismo são necessários para clientes do SDK usando APIs de MIP. Conclua a parte de codificação deste Início Rápido adicionando código para carregar as DLLs nativas e instanciar os objetos de 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;
       }
  }
}

3. 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
   <nome amigável>	Um nome amigável definido pelo usuário para seu aplicativo.	Inicialização do Aplicativo
   <GUID do locatário>	ID do seu locatário do Microsoft Entra	TenantID

4. Agora, faça um build final do aplicativo e resolva quaisquer 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.