Guia de início rápido: inicialização de aplicativo cliente para SDKs de proteção (C++)

Artigo
01/30/2024

Este guia de início rápido mostra como implementar o padrão de inicialização do cliente, usado pelo MIP C++ 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 proteção MIP. Esses inícios rápidos devem ser feitos em série após a inicialização do aplicativo e a implementação das classes de delegado de autenticação e delegado de consentimento.

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.
- Analise os conceitos do Observer para saber mais sobre os observadores e como eles são implementados. O MIP SDK usa o padrão de observador para implementar notificações de eventos 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, sobre os quais os outros Quickstarts 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 de Console do Windows
- 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.
Adicione o pacote Nuget para o SDK de Proteção MIP 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.Protection".
  - 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.

Implementar classes de observador para monitorar o perfil de proteção e os objetos do mecanismo

Agora, crie uma implementação básica para uma classe de observador de perfil de proteção, estendendo a classe do mip::ProtectionProfile::Observer SDK. O observador é instanciado e usado posteriormente, para monitorar o carregamento do objeto de perfil de proteção e adicionar o objeto de mecanismo ao perfil.

Adicione uma nova classe ao seu projeto, que gera os arquivos header/.h e implementation/.cpp para você:
- No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto novamente, selecione Adicionar e, em seguida, selecione Classe.
- Na caixa de diálogo Adicionar classe:
  - No campo Nome da classe, digite "profile_observer". Observe que os campos de arquivo .h e 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, após quaisquer diretivas de pré-processador existentes:

#include <memory>
#include "mip/protection/protection_profile.h"
using std::exception_ptr;
using std::shared_ptr;


class ProtectionProfileObserver final : public mip::ProtectionProfile::Observer {
public:
     ProtectionProfileObserver() { }
     void OnLoadSuccess(const std::shared_ptr<mip::ProtectionProfile>& profile, const std::shared_ptr<void>& context) override;
     void OnLoadFailure(const std::exception_ptr& Failure, const std::shared_ptr<void>& context) override;
     void OnAddEngineSuccess(const std::shared_ptr<mip::ProtectionEngine>& engine, const std::shared_ptr<void>& context) override;
     void OnAddEngineFailure(const std::exception_ptr& Failure, const std::shared_ptr<void>& context) override;
};

Atualize "profile_observer.cpp", selecionando/excluindo a implementação da 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, após quaisquer diretivas de pré-processador existentes:

#include <future>

using std::promise;
using std::shared_ptr;
using std::static_pointer_cast;
using mip::ProtectionEngine;
using mip::ProtectionProfile;

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

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

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

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

Seguindo as etapas em 1. adicione uma nova classe para Observador do mecanismo de proteção - "engine_observer" ao seu projeto, que gera os arquivos header/.h e implementation/.cpp para você.

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 "engine_observer.h", selecionando/excluindo a classe gerada engine_observer . Não remova as diretivas de pré-processador geradas pela etapa anterior (#pragma, #include). Em seguida, copie/cole a seguinte fonte no arquivo, após quaisquer diretivas de pré-processador existentes:

#include <memory>
#include "mip/protection/protection_engine.h"
using std::vector;
using std::exception_ptr;
using std::shared_ptr;

class ProtectionEngineObserver final : public mip::ProtectionEngine::Observer {
  public:
  ProtectionEngineObserver() {}
  void OnGetTemplatesSuccess(const vector<std::shared_ptr<mip::TemplateDescriptor>>& templateDescriptors, const shared_ptr<void>& context) override;
  void OnGetTemplatesFailure(const exception_ptr& Failure, const shared_ptr<void>& context) override;

};

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

#include "mip/protection/protection_profile.h"
#include "engine_observer.h"

using std::promise;
void ProtectionEngineObserver::OnGetTemplatesSuccess(const vector<shared_ptr<mip::TemplateDescriptor>>& templateDescriptors,const shared_ptr<void>& context) {
    auto loadPromise = static_cast<promise<vector<shared_ptr<mip::TemplateDescriptor>>>*>(context.get());
    loadPromise->set_value(templateDescriptors);
  };

  void ProtectionEngineObserver::OnGetTemplatesFailure(const exception_ptr& Failure, const shared_ptr<void>& context) {
    auto loadPromise = static_cast<promise<shared_ptr<mip::ProtectionProfile>>*>(context.get());
    loadPromise->set_exception(Failure);
  };

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

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.

Crie uma implementação para um delegado de autenticação, estendendo a classe do mip::AuthDelegate SDK e substituindo/implementando a função virtual pura mip::AuthDelegate::AcquireOAuth2Token() . Siga as etapas detalhadas em File SDK Application Initialization Quickstart. O delegado de autenticação é instanciado e usado posteriormente, pelos objetos Perfil de proteção e Mecanismo de proteção.

Agora, crie uma implementação para um delegado de consentimento, estendendo a classe do mip::ConsentDelegate SDK e substituindo/implementando a função virtual pura mip::AuthDelegate::GetUserConsent() . Siga as etapas detalhadas em File SDK Application Initialization Quickstart. O delegado de consentimento é instanciado e usado posteriormente, pelos objetos Perfil de proteção e Mecanismo de proteção.

Construir um perfil e um motor de proteção

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

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

#include "mip/mip_init.h"
#include "mip/mip_context.h"  
#include "auth_delegate.h"
#include "consent_delegate.h"
#include "profile_observer.h"
#include"engine_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::ProtectionProfile;
using mip::ProtectionEngine;

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>"};

  std::shared_ptr<mip::MipConfiguration> mipConfiguration = std::make_shared<mip::MipConfiguration>(mAppInfo,
				                                                                                               "mip_data",
                                                                                      			         mip::LogLevel::Trace,
                                                                                                     false);

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

  auto profileObserver = make_shared<ProtectionProfileObserver>(); // 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
  ProtectionProfile::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<ProtectionProfile>>>();
  auto profileFuture = profilePromise->get_future();
  try
  {
    mip::ProtectionProfile::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
  ProtectionEngine::Settings engineSettings(       
     mip::Identity("<engine-account>"),         // Engine identity (account used for authentication)
     authDelegateImpl,                          // Reference to mip::AuthDelegate implementation
     "",                                        // ClientData field
     "en-US");                                  // Locale (default = en-US)

  // Set the engineId so it can be cached and reused. 
  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<ProtectionEngine>>>();
  auto engineFuture = enginePromise->get_future();
  profile->AddEngineAsync(engineSettings, enginePromise);
  std::shared_ptr<ProtectionEngine> 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.
  engine = nullptr;
  profile = nullptr;
  mipContext.Shutdown();
  mipContext = nullptr;

  return 0;
}

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

Marcador de Posição	Valor	Exemplo
<ID do aplicativo>	O Microsoft Entra Application ID (GUID) atribuído ao aplicativo registrado na etapa #2 do artigo "MIP SDK setup and configuration"(setup-configure-mip.md). Substitua 2 instâncias.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<nome-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 que você usou em seu registro do Microsoft Entra.	`"AppInitialization"`
<aplicação-versão>	Informações de versão definidas pelo usuário para seu aplicativo. Deve conter caracteres ASCII válidos (excluindo ';').	`"1.1.0.0"`
<conta-motor>	A conta usada para a identidade do mecanismo. Quando você se autentica com uma conta de usuário durante a aquisição do token, ela deve corresponder a esse valor.	`"user1@tenant.onmicrosoft.com"`
<estado-motor>	Estado definido pelo usuário a ser associado ao mecanismo.	`"My App State"`

Agora faça uma compilação 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 Guia de início rápido. Se você executar o aplicativo, verá uma saída semelhante à seguinte. O aplicativo construiria o perfil de proteção e o mecanismo de proteção com sucesso, mas não teria acionado o módulo de autenticação e você ainda não terá um token de acesso até concluir o próximo Guia de início rápido.
```
 C:\MIP Sample Apps\ProtectionQS\Debug\ProtectionQS.exe (process 8252) exited with code 0.
 To automatically close the console when debugging stops, enable Tools->Options->Debugging->Automatically close the console when debugging stops.
 Press any key to close this window . . .
```

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 o SDK de Proteção MIP.

Modelos de proteção de lista

Partilhar via

Guia de início rápido: inicialização de aplicativo cliente para SDKs de proteção (C++)

Pré-requisitos

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

Implementar classes de observador para monitorar o perfil de proteção e os objetos do mecanismo

Construir um perfil e um motor de proteção

Passos Seguintes

Comentários

Recursos adicionais

Partilhar via

Guia de início rápido: inicialização de aplicativo cliente para SDKs de proteção (C++)

Pré-requisitos

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

Implementar classes de observador para monitorar o perfil de proteção e os objetos do mecanismo

Implementar um delegado de autenticação e um delegado de consentimento

Implementar um delegado de consentimento

Construir um perfil e um motor de proteção

Passos Seguintes

Comentários

Recursos adicionais