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

2025-04-22

Este início rápido mostra como implementar o padrão de inicialização do cliente, usado pelo SDK do MIP C++ em runtime.

Observação

As etapas descritas neste início rápido são necessárias para qualquer aplicativo cliente que use os SDKs de Proteção, Política ou Arquivo MIP. Embora este 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. Conclua as introduções rápidas restantes sequencialmente, pois cada uma se baseia na anterior, sendo esta a primeira.

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.
- Examine os conceitos do Observer para saber mais sobre observadores e como eles são implementados. O SDK do MIP usa o padrão de observador para implementar notificações de evento assíncronas.

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 são compilados.

Abra o Visual Studio 2017, selecione o menu Arquivo , Novo, Projeto. Na caixa de diálogo Novo Projeto :
- No painel esquerdo, em Instalado, Outros Idiomas, selecione Visual C++.
- No painel central, selecione Aplicativo do Console do Windows
- 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.
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.

Implementar uma classe observadora para monitorar os objetos Mecanismo e Perfil de arquivo

Agora, crie uma implementação básica para uma classe de observador de perfil de arquivo, estendendo a classe do mip::FileProfile::Observer SDK. Uma instância do observador é criada e será usada mais tarde para monitorar o carregamento do objeto Perfil de arquivo e adicionar o objeto Mecanismo ao perfil.

Adicione uma nova classe ao projeto, que gera os arquivos de cabeçalho/.h e implementação/.cpp para você:
- No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto novamente, selecione Adicionar e selecione Classe.
- Na caixa de diálogo Adicionar Classe :
  - No campo Nome da Classe , insira "profile_observer". Observe que o arquivo .h e os campos de arquivo .cpp são preenchidos automaticamente, com base no nome inserido.
  - Quando terminar, clique no botão OK .

Depois de gerar os arquivos .h e .cpp para a classe, ambos os arquivos são abertos nas guias Grupo de Editores. Agora atualize cada arquivo para implementar sua nova classe de observador:

Atualize "profile_observer.h", selecionando/excluindo a classe gerada profile_observer . Não remova as diretivas de pré-processador geradas pela etapa anterior (#pragma, #include). Em seguida, copie/cole a seguinte fonte no arquivo, depois de quaisquer diretivas de pré-processador existentes:

#include <memory>
#include "mip/file/file_profile.h"

class ProfileObserver final : public mip::FileProfile::Observer {
public:
     ProfileObserver() { }
     void OnLoadSuccess(const std::shared_ptr<mip::FileProfile>& profile, const std::shared_ptr<void>& context) override;
     void OnLoadFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
     void OnAddEngineSuccess(const std::shared_ptr<mip::FileEngine>& engine, const std::shared_ptr<void>& context) override;
     void OnAddEngineFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
};

Atualize "profile_observer.cpp", selecionando/excluindo a implementação de classe gerada profile_observer . Não remova as diretivas de pré-processador geradas pela etapa anterior (#pragma, #include). Em seguida, copie/cole a seguinte fonte no arquivo, depois de quaisquer diretivas de pré-processador existentes:

#include <future>

using std::promise;
using std::shared_ptr;
using std::static_pointer_cast;
using mip::FileEngine;
using mip::FileProfile;

void ProfileObserver::OnLoadSuccess(const shared_ptr<FileProfile>& profile, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileProfile>>>(context);
     promise->set_value(profile);
}

void ProfileObserver::OnLoadFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileProfile>>>(context);
     promise->set_exception(error);
}

void ProfileObserver::OnAddEngineSuccess(const shared_ptr<FileEngine>& engine, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileEngine>>>(context);
     promise->set_value(engine);
}

void ProfileObserver::OnAddEngineFailure(const std::exception_ptr& error, const shared_ptr<void>& context) {
     auto promise = static_pointer_cast<std::promise<shared_ptr<FileEngine>>>(context);
     promise->set_exception(error);
}

Opcionalmente, use F6 (Build Solution) para executar uma compilação/link de teste de sua solução, para garantir que ela seja compilada com êxito antes de continuar.

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 classe do mip::AuthDelegate SDK e substituindo/implementando a mip::AuthDelegate::AcquireOAuth2Token() função virtual pura. Uma instância do representante de autenticação é criada e será usada mais tarde pelos objetos Perfil de arquivo e Mecanismo de arquivo.

Usando o mesmo recurso "Adicionar Classe" do Visual Studio que usamos na etapa 1 da seção anterior, adicione outra classe ao seu projeto. Desta vez, insira "auth_delegate" no campo Nome da Classe .

Agora atualize cada arquivo para implementar sua nova classe de delegado de autenticação:

Atualize "auth_delegate.h", substituindo todo o código de classe gerado auth_delegate pela fonte a seguir. Não remova as diretivas de pré-processador geradas pela etapa anterior (#pragma, #include):

#include <string>
#include "mip/common_types.h"

class AuthDelegateImpl final : public mip::AuthDelegate {
public:
     AuthDelegateImpl() = delete;        // Prevents default constructor

     AuthDelegateImpl(
       const std::string& appId)         // AppID for registered AAD app
       : mAppId(appId) {};

     bool AcquireOAuth2Token(            // Called by MIP SDK to get a token
       const mip::Identity& identity,    // Identity of the account to be authenticated, if known
       const OAuth2Challenge& challenge, // Authority (AAD tenant issuing token), and resource (API being accessed; "aud" claim).
       OAuth2Token& token) override;     // Token handed back to MIP SDK

private:
     std::string mAppId;
     std::string mToken;
     std::string mAuthority;
     std::string mResource;
};

Atualize "auth_delegate.cpp", substituindo toda a implementação da classe auth_delegate gerada pela fonte a seguir. Não remova as diretivas de pré-processador geradas pela etapa anterior (#pragma, #include).
Importante

O código de aquisição de token a seguir não é adequado para uso em produção. Na produção, isso deve ser substituído pelo código que adquire dinamicamente um token usando:
- O appId e o URI de resposta/redirecionamento especificados no registro do aplicativo Microsoft Entra (o URI de resposta/redirecionamento deve corresponder ao registro do aplicativo)
- A autoridade e a URL do recurso passadas pelo SDK no argumento challenge (a URL do recurso deve corresponder à API ou às permissões do registro de aplicativo)
- Credenciais válidas de aplicativo/usuário, onde a conta corresponde ao argumento identity passado pelo SDK. Os clientes "nativos" do OAuth2 devem solicitar credenciais do usuário e usar o fluxo de "código de autorização". Os "clientes confidenciais" OAuth2 podem usar suas próprias credenciais seguras com o fluxo de "credenciais do cliente" (como um serviço) ou solicitar credenciais de usuário usando o fluxo de "código de autorização" (como um aplicativo Web).
A aquisição de token OAuth2 é um protocolo complexo e normalmente realizado usando uma biblioteca. O método TokenAcquireOAuth2Token() é chamado apenas quando necessário pelo SDK da PIM.
```
#include <iostream>
using std::cout;
using std::cin;
using std::string;

bool AuthDelegateImpl::AcquireOAuth2Token(const mip::Identity& identity, const OAuth2Challenge& challenge, OAuth2Token& token) 
{
     // Acquire a token manually, reuse previous token if same authority/resource. In production, replace with token acquisition code.
     string authority = challenge.GetAuthority();
     string resource = challenge.GetResource();
     if (mToken == "" || (authority != mAuthority || resource != mResource))
     {
         cout << "\nRun the PowerShell script to generate an access token using the following values, then copy/paste it below:\n";
         cout << "Set $authority to: " + authority + "\n";
         cout << "Set $resourceUrl to: " + resource + "\n";
         cout << "Sign in with user account: " + identity.GetEmail() + "\n";
         cout << "Enter access token: ";
         cin >> mToken;
         mAuthority = authority;
         mResource = resource;
         system("pause");
     }

     // Pass access token back to MIP SDK
     token.SetAccessToken(mToken);

     // True = successful token acquisition; False = failure
     return true;
}
```

Opcionalmente, use F6 (Build Solution) para executar uma compilação/link de teste de sua solução, para garantir que ela seja compilada com êxito antes de continuar.

Agora, crie uma implementação para um delegado de consentimento, estendendo a classe do mip::ConsentDelegate SDK e substituindo/implementando a mip::AuthDelegate::GetUserConsent() função virtual pura. Uma instância do representante de consentimento é criada e será usada mais tarde pelos objetos Perfil de arquivo e Mecanismo de arquivo.

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

Agora atualize cada arquivo para implementar sua nova classe de delegado de consentimento:

Atualize "consent_delegate.h", substituindo todo o código de classe gerado consent_delegate pela fonte a seguir. Não remova as diretivas de pré-processador geradas pela etapa anterior (#pragma, #include):

#include "mip/common_types.h"
#include <string>

class ConsentDelegateImpl final : public mip::ConsentDelegate {
public:
     ConsentDelegateImpl() = default;
     virtual mip::Consent GetUserConsent(const std::string& url) override;
};

Atualize "consent_delegate.cpp", substituindo toda a implementação da classe consent_delegate gerada pela fonte a seguir. Não remova as diretivas de pré-processador geradas pela etapa anterior (#pragma, #include).

#include <iostream>
using mip::Consent;
using std::string;

Consent ConsentDelegateImpl::GetUserConsent(const string& url) 
{
     // Accept the consent to connect to the url
     std::cout << "SDK will connect to: " << url << std::endl;
     return Consent::AcceptAlways;
}

Opcionalmente, use F6 (Build Solution) para executar uma compilação/link de teste de sua solução, para garantir que ela seja compilada com êxito antes de continuar.

Construir um Perfil e um Mecanismo 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 instanciar os objetos de perfil e mecanismo:

No Gerenciador de Soluções, abra o arquivo .cpp 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.
Remova a implementação gerada de main(). Não remova as diretivas de pré-processador geradas pelo Visual Studio durante a criação do projeto (#pragma, #include). Acrescente o seguinte código após quaisquer diretivas de pré-processador:

#include "mip/mip_context.h"  
#include "auth_delegate.h"
#include "consent_delegate.h"
#include "profile_observer.h"

using std::promise;
using std::future;
using std::make_shared;
using std::shared_ptr;
using std::string;
using std::cout;
using mip::ApplicationInfo;
using mip::FileProfile;
using mip::FileEngine;

int main()
{
  // Construct/initialize objects required by the application's profile object
  // ApplicationInfo object (App ID, name, version)
  ApplicationInfo appInfo{"<application-id>",      
                          "<application-name>",
                          "<application-version>"};

  // Create MipConfiguration object.
  std::shared_ptr<mip::MipConfiguration> mipConfiguration = std::make_shared<mip::MipConfiguration>(appInfo,    
				                                                                                               "mip_data", 
                                                                                      			         mip::LogLevel::Trace, 
                                                                                                     false);


  std::shared_ptr<mip::MipContext> mMipContext = mip::MipContext::Create(mipConfiguration);

  auto profileObserver = make_shared<ProfileObserver>();                     // Observer object
  auto authDelegateImpl = make_shared<AuthDelegateImpl>("<application-id>"); // Authentication delegate object (App ID)                 
  auto consentDelegateImpl = make_shared<ConsentDelegateImpl>();             // Consent delegate object

  // Construct/initialize profile object
  FileProfile::Settings profileSettings(
                                mMipContext,
                                mip::CacheStorageType::OnDisk,
                                consentDelegateImpl,
                                profileObserver);

  // Set up promise/future connection for async profile operations; load profile asynchronously
  auto profilePromise = make_shared<promise<shared_ptr<FileProfile>>>();
  auto profileFuture = profilePromise->get_future();

  try
	  { 
		  mip::FileProfile::LoadAsync(profileSettings, profilePromise);
  }
	  catch (const std::exception& e)
	  {
		  cout << "An exception occurred... are the Settings and ApplicationInfo objects populated correctly?\n\n" << e.what() << "'\n";
			
		  system("pause");
		  return 1;
	  }
	  auto profile = profileFuture.get();

  // Construct/initialize engine object
  FileEngine::Settings engineSettings(
                                  mip::Identity("<engine-account>"), // Engine identity (account used for authentication)
                                  authDelegateImpl,		       // Token acquisition implementation
				    "<engine-state>",                  // User-defined engine state
                                  "en-US");                          // Locale (default = en-US)
                                  
  // Set the engineId for caching. 
  engineSettings.SetEngineId("<engine-account>");
  // Set up promise/future connection for async engine operations; add engine to profile asynchronously
  auto enginePromise = make_shared<promise<shared_ptr<FileEngine>>>();
  auto engineFuture = enginePromise->get_future();
  profile->AddEngineAsync(engineSettings, enginePromise);
  std::shared_ptr<FileEngine> engine; 
  try
  {
    engine = engineFuture.get();
  }
  catch (const std::exception& e)
  {
    cout << "An exception occurred... is the access token incorrect/expired?\n\n" << e.what() << "'\n";
     
    system("pause");
    return 1;
  }

  // Application shutdown. Null out profile and engine, call ReleaseAllResources();
  // Application may crash at shutdown if resources aren't properly released.
  // handler = nullptr; // This will be used in later quick starts.
  engine = nullptr;
  profile = nullptr;   
  mMipContext->ShutDown();
  mMipContext = nullptr;

  return 0;
  }

Substitua todos os valores de espaço reservado existentes no código-fonte que você acabou de colar usando constantes de cadeia de caracteres:

Espaço reservado	Valor	Exemplo
<application-id>	O Microsoft Entra Application ID (GUID) atribuído ao aplicativo registrado na etapa #2 do artigo "configuração e instalação do SDK do MIP". Substitua duas instâncias.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<nome do aplicativo>	Um nome amigável definido pelo usuário para seu aplicativo. Deve conter caracteres ASCII válidos (excluindo ';') e, idealmente, corresponde ao nome do aplicativo usado no registro do Microsoft Entra.	`"AppInitialization"`
<versão do aplicativo>	Informações de versão definidas pelo usuário para seu aplicativo. Deve conter caracteres ASCII válidos (excluindo ';').	`"1.1.0.0"`
<engine-account>	Conta usada para a identidade do mecanismo. Quando você se autentica com uma conta de usuário durante a aquisição do token, ele deve corresponder a esse valor.	`"user1@tenant.onmicrosoft.com"`
<estado do mecanismo>	Estado definido pelo usuário a ser associado ao mecanismo.	`"My App State"`

Agora, faça um build final do aplicativo e resolva quaisquer erros. Seu código deve ser compilado com êxito, mas ainda não será executado corretamente até que você conclua o próximo Início Rápido. Se você executar o aplicativo, verá uma saída semelhante à seguinte. Você não terá um token de acesso para fornecer até concluir o próximo início rápido.

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

Compartilhar via