Démarrage rapide : Initialisation des applications clientes pour les SDK Protection (C++)

Article
01/30/2024

Ce guide de démarrage rapide vous montre comment implémenter le modèle d’initialisation de client, utilisé par le SDK MIP C++ lors du runtime.

Remarque

Les étapes décrites dans ce guide de démarrage rapide sont nécessaires pour toute application cliente qui utilise les SDK MIP Protection. Ces guides de démarrage rapide doivent être suivis dans l’ordre après l’initialisation de l’application et l’implémentation des classes Délégué d’authentification et Délégué de consentement.

Prérequis

Si ce n’est déjà fait, veillez à :

Suivre les étapes dans Installation et configuration du kit de développement logiciel (SDK) Microsoft Information Protection. Ce Démarrage rapide « Initialisation des applications clientes » repose sur l’installation et la configuration appropriées du kit de développement logiciel (SDK).
Si vous le souhaitez :
- Passez en revue Objets de profil et de moteur. Les objets de profil et de moteur sont des concepts universels requis par les clients qui utilisent les kits de développement logiciel (SDK) MIP File/Policy/Protection.
- Passez en revue les concepts d’authentification pour voir comment l’authentification et le consentement sont implémentés par le kit de développement logiciel (SDK) et l’application cliente.
- Passez en revue les Concepts d’observateur pour en savoir plus sur les observateurs et leur implémentation. Le kit de développement logiciel (SDK) MIP utilise le modèle d’observateur pour implémenter les notifications d’événements asynchrones.

Créer une solution et un projet Visual Studio

Tout d’abord, nous créons et configurons la solution et le projet Visual Studio initiaux sur lesquels repose l’autre build de démarrages rapides.

Ouvrez Visual Studio 2017, sélectionnez le menu Fichier, puis Nouveau et Projet. Dans la boîte de dialogue Nouveau projet :
- Dans le volet de gauche, sous Installé, Autres langages, sélectionnez Visual C++.
- Dans le volet central, sélectionnez Application console Windows.
- Dans le volet inférieur, mettez à jour le Nom du projet, l’Emplacement et le Nom de la solution qui le contient en conséquence.
- Lorsque vous avez terminé, cliquez sur le bouton OK en bas à droite.
Ajoutez le package NuGet du SDK MIP Protection à votre projet :
- Dans l’Explorateur de solutions, cliquez avec le bouton de droite sur le nœud du projet (directement sous le nœud supérieur/de la solution), puis sélectionnez Gérer les packages NuGet… :
- Lorsque l’onglet Gestionnaire de packages NuGet s’ouvre dans la zone des onglets du groupe d’éditeurs :
  - Cliquez sur Parcourir.
  - Entrez « Microsoft.InformationProtection » dans la zone de recherche.
  - Sélectionnez le package « Microsoft.InformationProtection.Protection ».
  - Cliquez sur « Installer », puis sur « OK » lorsque la boîte de dialogue de confirmation Aperçu des modifications s’affiche.

Implémenter des classes d’observateur pour monitorer les objets de profil et de moteur Protection

À présent, créez une implémentation de base pour une classe d’observateur de profil Protection, en étendant la classe mip::ProtectionProfile::Observer du SDK. L’observateur est instancié et utilisé ultérieurement pour monitorer le chargement de l’objet de profil Protection et l’ajout de l’objet de moteur au profil.

Ajoutez une nouvelle classe à votre projet, ce qui génère pour vous les fichiers header/.h et implementation/.cpp :
- Dans l’Explorateur de solutions, cliquez avec le bouton de droite sur le nœud du projet une nouvelle fois, puis sélectionnez Ajouter et Classe.
- Dans la boîte de dialogue Ajouter une classe :
  - Dans le champ Nom de la classe, entrez « profile_observer ». Notez que les deux champs Fichier .h et Fichier .cpp sont automatiquement renseignés en fonction du nom que vous entrez.
  - Lorsque vous avez terminé, cliquez sur le bouton OK.

Après la génération des fichiers .h et .cpp pour la classe, les deux fichiers sont ouverts sous les onglets du groupe d’éditeurs. Maintenant, mettez à jour chaque fichier pour implémenter votre nouvelle classe d’observateur :

Mettez à jour « profile_observer.h » en sélectionnant/supprimant la classe profile_observer générée. Ne supprimez pas les directives de préprocesseur générées à l’étape précédente (#pragma, #include). Ensuite, copiez/collez la source suivante dans le fichier, après les directives de préprocesseur existantes :

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

Mettez à jour « profile_observer.cpp » en sélectionnant/supprimant l’implémentation de la classe profile_observer générée. Ne supprimez pas les directives de préprocesseur générées à l’étape précédente (#pragma, #include). Ensuite, copiez/collez la source suivante dans le fichier, après les directives de préprocesseur existantes :

#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);
}

Après avoir effectué les étapes de la section 1, ajoutez une nouvelle classe pour l’observateur du moteur Protection « engine_observer » à votre projet, ce qui génère pour vous les fichiers header/.h et implementation/.cpp.

Mettez à jour « engine_observer.h » en sélectionnant/supprimant la classe engine_observer générée. Ne supprimez pas les directives de préprocesseur générées à l’étape précédente (#pragma, #include). Ensuite, copiez/collez la source suivante dans le fichier, après les directives de préprocesseur existantes :

#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;

};

Mettez à jour « engine_observer.cpp » en sélectionnant/supprimant l’implémentation de la classe engine_observer générée. Ne supprimez pas les directives de préprocesseur générées à l’étape précédente (#pragma, #include). Ensuite, copiez/collez la source suivante dans le fichier, après les directives de préprocesseur existantes :

#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);
  };

Utilisez éventuellement CTRL+MAJ+B (Générer la solution) pour exécuter une compilation/liaison de test de votre solution afin de vous assurer qu’elle est correctement générée avant de continuer.

Le kit de développement logiciel (SDK) MIP implémente l’authentification à l’aide de l’extensibilité de la classe, ce qui fournit un mécanisme pour partager le travail d’authentification avec l’application cliente. Le client doit acquérir un jeton d’accès OAuth2 approprié et le fournir au kit de développement logiciel (SDK) MIP lors du runtime.

Créez une implémentation pour un délégué d’authentification en étendant la classe mip::AuthDelegate du SDK et en substituant/implémentant la fonction purement virtuelle mip::AuthDelegate::AcquireOAuth2Token(). Suivez les étapes détaillées dans le guide de démarrage rapide pour l’initialisation de l’application SDK File. Le délégué d’authentification est instancié et utilisé ultérieurement par les objets de profil Protection et de moteur Protection.

Maintenant, créez une implémentation pour un délégué de consentement en étendant la classe mip::ConsentDelegate du SDK et en substituant/implémentant la fonction purement virtuelle mip::AuthDelegate::GetUserConsent(). Suivez les étapes détaillées dans le guide de démarrage rapide pour l’initialisation de l’application SDK File. Le délégué de consentement est instancié et utilisé ultérieurement par les objets de profil Protection et de moteur Protection.

Construire un profil et un moteur Protection

Comme mentionné, les objets de profil et de moteur sont requis par les clients du kit de développement logiciel (SDK) qui utilisent les API MIP. Complétez la partie de code de ce Démarrage rapide en ajoutant du code pour instancier les objets de profil et de moteur :

Dans l’Explorateur de solutions, ouvrez le fichier .cpp dans votre projet qui contient l’implémentation de la méthode main(). Par défaut, il a le même nom que le projet qui le contient et que vous avez spécifié lors de la création du projet.
Supprimez l’implémentation générée de main(). Ne supprimez pas les directives de préprocesseur générées par Visual Studio pendant la création du projet (#pragma, #include). Ajoutez le code suivant après chaque directive de préprocesseur :

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

Remplacez toutes les valeurs d’espace réservé du code source que vous venez de coller en utilisant des constantes de chaîne :

Paramètre substituable	Valeur	Exemple
<application-id>	ID d’application Microsoft Entra (GUID) attribué à l’application inscrite à l’étape 2 de l’article « Installation et configuration du Kit de développement logiciel (SDK) MIP » (setup-configure-mip.md). Remplacez 2 instances.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<application-name>	Nom convivial défini par l’utilisateur pour votre application. Doit contenir des caractères ASCII valides (à l’exception de « ; ») et dans l’idéal correspondre au nom d’application que vous avez utilisé dans votre inscription Microsoft Entra.	`"AppInitialization"`
<application-version>	Version définie par l’utilisateur pour votre application. Doit contenir des caractères ASCII valides (à l’exception de « ; »).	`"1.1.0.0"`
<engine-account>	Compte utilisé pour l’identité du moteur. Lorsque vous vous authentifiez avec un compte d’utilisateur lors de l’acquisition d’un jeton, celui-ci doit correspondre à cette valeur.	`"user1@tenant.onmicrosoft.com"`
<engine-state>	État défini par l’utilisateur à associer au moteur.	`"My App State"`

Maintenant, procédez à une dernière génération de l’application et résolvez les erreurs éventuelles. Votre code devrait être généré avec succès, mais il ne s’exécutera pas encore correctement tant que vous n’aurez pas suivi le prochain Démarrage rapide. Si vous exécutez l’application, vous voyez une sortie similaire à la suivante. L’application crée le profil Protection et le moteur Protection, mais ne déclenche pas le module d’authentification. En outre, vous n’aurez pas de jeton d’accès tant que vous n’aurez pas suivi le prochain guide de démarrage rapide.
```
 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 . . .
```

Étapes suivantes

Maintenant que votre code d’initialisation est terminé, vous êtes prêt pour le prochain guide de démarrage rapide, où vous allez commencer à utiliser le SDK MIP Protection.

Répertorier les modèles de protection

Partager via

Démarrage rapide : Initialisation des applications clientes pour les SDK Protection (C++)

Prérequis

Créer une solution et un projet Visual Studio

Implémenter des classes d’observateur pour monitorer les objets de profil et de moteur Protection

Construire un profil et un moteur Protection

Étapes suivantes

Commentaires

Ressources supplémentaires

Partager via

Démarrage rapide : Initialisation des applications clientes pour les SDK Protection (C++)

Prérequis

Créer une solution et un projet Visual Studio

Implémenter des classes d’observateur pour monitorer les objets de profil et de moteur Protection

Implémenter un délégué d’authentification et un délégué de consentement

Implémenter un délégué de consentement

Construire un profil et un moteur Protection

Étapes suivantes

Commentaires

Ressources supplémentaires