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

  • Artigo

Este guia de início rápido mostrará como implementar o padrão de inicialização do cliente, usado pelo wrapper .NET do MIP SDK em tempo de execução.

Nota

As etapas descritas neste início rápido são necessárias para qualquer aplicativo cliente que use os SDKs de arquivo, política ou proteção do wrapper MIP .NET. Embora este 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 proteção. Os futuros Quickstarts devem ser feitos em série, pois cada um se baseia no anterior, sendo este o primeiro. Este código destina-se a demonstrar como começar a usar o MIP SDK e não se destina ao uso em produção.

Pré-requisitos

Se ainda não o fez, certifique-se de:

  • Conclua as etapas na instalação e configuração do SDK do Microsoft Information Protection (MIP). Este Guia de início rápido de "inicialização do aplicativo cliente" depende da instalação e configuração adequadas do SDK.
  • Opcionalmente:
    • Revise os objetos do perfil e do mecanismo. Os objetos de perfil e mecanismo são conceitos universais, exigidos por clientes que usam os SDKs de arquivo/política/proteção MIP.
    • Analise 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, sobre os quais os outros Quickstarts 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 o contém de acordo.

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

      Visual Studio solution creation

  2. Adicione o pacote Nuget para o MIP File SDK ao seu projeto:

    • No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto (diretamente abaixo do nó superior/solução) e selecione Gerenciar pacotes NuGet...:
    • Quando a guia Gerenciador de Pacotes NuGet for aberta na área de guias Grupo de Editores:
      • Selecione Procurar.
      • Digite "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 de alterações de visualização 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 MIP SDK 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 MIP SDK em tempo de execução.

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 FileProfile e usado posteriormente pelos objetos e FileEngine .

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

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

  3. Adicione instruções using para a Microsoft Authentication Library (MSAL) 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 aceita 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. O _appInfo.ApplicationId será usado na AuthDelegateImplementation classe para fornecer o ID do cliente para a biblioteca de autenticação. ApplicationName e ApplicationVersion serão apresentados nos relatórios da Análise de Proteção de Informações do Azure.

  5. Adicione o public string AcquireToken() método. 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. Introduza o GUID do Inquilino a partir do portal do Azure para o seu inquilino. 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;
}

Agora crie uma implementação para um delegado de consentimento, estendendo a interface do Microsoft.InformationProtection.IConsentDelegate SDK e substituindo/implementando GetUserConsent(). O delegado de consentimento é instanciado e usado posteriormente, pelos objetos File profile e File engine. 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 ao usuário aceitar ou rejeitar o consentimento para acessar o serviço. Para este código Consent.Acceptrígido de início rápido.

  1. Usando o mesmo recurso "Adicionar classe" do Visual Studio que usamos anteriormente, adicione outra classe ao seu projeto. Desta vez, digite "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 e defina a classe para Microsoft.InformationProtection 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 MIP SDK

  1. No Gerenciador de Soluções, abra o arquivo de .cs em seu projeto que contém a Main() implementação do método. O 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 do main().

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

  4. Em Main() Programa.cs adicione o seguinte, substituindo <application-id> pela ID do Registro de Aplicativo 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 perfil de arquivo e um mecanismo

Como mencionado, os objetos de perfil e mecanismo são necessários para clientes SDK que usam APIs MIP. Conclua a parte de codificação deste Guia de início rápido, adicionando código para carregar as DLLs nativas e, em seguida, instancie 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;
       }
  }
}

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

    Marcador de Posição Valor Exemplo
    <ID do aplicativo> O ID do Aplicativo Microsoft Entra atribuído ao aplicativo registrado em "MIP SDK setup and configuration" (2 instâncias). 0edbblll-8773-44de-b87c-b8c6276d41eb
    <nome-amigável> Um nome amigável definido pelo usuário para seu aplicativo. AppInitialization
    <GUID do locatário> ID de locatário para seu locatário do Microsoft Entra TenantID

  2. Agora faça uma compilação final do aplicativo e resolva quaisquer erros. Seu código deve ser compilado com êxito.

Passos Seguintes

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

Listar rótulos de sensibilidade