Quickstart: Initialisatie van clienttoepassingen voor beveiligings-SDK's (C++)

Artikel
01/30/2024

In deze quickstart ziet u hoe u het initialisatiepatroon van de client implementeert, dat tijdens runtime wordt gebruikt door de MIP C++ SDK.

Notitie

De stappen die in deze quickstart worden beschreven, zijn vereist voor elke clienttoepassing die gebruikmaakt van de MIP Protection SDK's. Deze quickstarts moeten serieel worden uitgevoerd na de initialisatie en implementatie van de klassen Verificatie-gemachtigde en Toestemmingsdelegatie.

Vereisten

Als u dat nog niet hebt gedaan, moet u het volgende doen:

Voer de stappen uit in de installatie en configuratie van microsoft Information Protection (MIP) SDK. Deze quickstart voor de initialisatie van clienttoepassingen is afhankelijk van de juiste SDK-installatie en -configuratie.
Optioneel:
- Profiel- en engineobjecten controleren. Het profiel- en engineobject zijn universele concepten die vereist zijn voor clients die gebruikmaken van de MIP File/Policy/Protection SDK's.
- Bekijk de verificatieconcepten om te leren hoe verificatie en toestemming worden geïmplementeerd door de SDK en de clienttoepassing.
- Bekijk waarnemersconcepten voor meer informatie over waarnemers en hoe ze worden geïmplementeerd. De MIP SDK maakt gebruik van het waarnemerspatroon om asynchrone gebeurtenismeldingen te implementeren.

Een Visual Studio-oplossing en -project maken

Eerst maken en configureren we de eerste Visual Studio-oplossing en -project, waarop de andere quickstarts worden gebouwd.

Open Visual Studio 2017, selecteer het menu Bestand , Nieuw, Project. In het dialoogvenster Nieuw project :
- Selecteer Visual C++ in het linkerdeelvenster onder Geïnstalleerd, Overige talen.
- Selecteer windows-consoletoepassing in het middelste deelvenster
- Werk in het onderste deelvenster de projectnaam, locatie en de naam van de oplossing dienovereenkomstig bij.
- Wanneer u klaar bent, klikt u op de knop OK in de rechterbenedenhoek.
Voeg het Nuget-pakket voor de MIP Protection SDK toe aan uw project:
- Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt (direct onder het bovenste/oplossingsknooppunt) en selecteer NuGet-pakketten beheren...:
- Wanneer het tabblad NuGet Pakketbeheer wordt geopend in het tabbladen editorgroep:
  - Selecteer Bladeren.
  - Voer 'Microsoft.InformationProtection' in het zoekvak in.
  - Selecteer het pakket Microsoft.InformationProtection.Protection.
  - Klik op Installeren en klik vervolgens op OK wanneer het bevestigingsvenster voor wijzigingen in het voorbeeld wordt weergegeven.

Waarnemersklassen implementeren om het beveiligingsprofiel en engineobjecten te bewaken

Maak nu een eenvoudige implementatie voor een waarnemersklasse voor beveiligingsprofielen door de klasse van de SDK uit te mip::ProtectionProfile::Observer breiden. De waarnemer wordt geïnstantieerd en later gebruikt om het laden van het beveiligingsprofielobject te bewaken en het engineobject toe te voegen aan het profiel.

Voeg een nieuwe klasse toe aan uw project, waarmee zowel de header/.h- als de implementation/.cpp-bestanden voor u worden gegenereerd:
- Klik in Solution Explorer opnieuw met de rechtermuisknop op het projectknooppunt, selecteer Toevoegen en selecteer vervolgens Klasse.
- In het dialoogvenster Klasse toevoegen:
  - Voer in het veld Klassenaam 'profile_observer' in. U ziet dat zowel de .h-bestandsvelden als de .cpp-bestandsvelden automatisch worden ingevuld op basis van de naam die u invoert.
  - Wanneer u klaar bent, klikt u op de knop OK .

Nadat u de .h- en CPP-bestanden voor de klasse hebt gegenereerd, worden beide bestanden geopend op tabbladen editorgroep. Werk nu elk bestand bij om uw nieuwe waarnemersklasse te implementeren:

Werk profile_observer.h bij door de gegenereerde profile_observer klasse te selecteren/verwijderen. Verwijder de preprocessorrichtlijnen die door de vorige stap zijn gegenereerd (#pragma, #include) niet . Kopieer/plak vervolgens de volgende bron in het bestand, na eventuele bestaande preprocessorrichtlijnen:

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

Werk profile_observer.cpp bij door de gegenereerde profile_observer klasse-implementatie te selecteren/verwijderen. Verwijder de preprocessorrichtlijnen die door de vorige stap zijn gegenereerd (#pragma, #include) niet . Kopieer/plak vervolgens de volgende bron in het bestand, na eventuele bestaande preprocessorrichtlijnen:

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

Volg de stappen in 1. voeg een nieuwe klasse toe voor waarnemer van de Protection-engine: 'engine_observer' aan uw project, waarmee zowel de header/.h- als de implementation/.cpp-bestanden voor u worden gegenereerd.

Nadat u de .h- en CPP-bestanden voor de klasse hebt gegenereerd, worden beide bestanden geopend op tabbladen editorgroep. Werk nu elk bestand bij om uw nieuwe waarnemersklasse te implementeren:

Werk engine_observer.h bij door de gegenereerde engine_observer klasse te selecteren/verwijderen. Verwijder de preprocessorrichtlijnen die door de vorige stap zijn gegenereerd (#pragma, #include) niet . Kopieer/plak vervolgens de volgende bron in het bestand, na eventuele bestaande preprocessorrichtlijnen:

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

};

Werk engine_observer.cpp bij door de gegenereerde engine_observer klasse-implementatie te selecteren/verwijderen. Verwijder de preprocessorrichtlijnen die door de vorige stap zijn gegenereerd (#pragma, #include) niet . Kopieer/plak vervolgens de volgende bron in het bestand, na eventuele bestaande preprocessorrichtlijnen:

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

Gebruik optioneel Ctrl+Shift+B (Build Solution) om een testcompilatie/koppeling van uw oplossing uit te voeren, om ervoor te zorgen dat deze correct wordt gebouwd voordat u doorgaat.

De MIP SDK implementeert verificatie met behulp van klasse-uitbreidbaarheid. Dit biedt een mechanisme voor het delen van verificatie met de clienttoepassing. De client moet een geschikt OAuth2-toegangstoken verkrijgen en tijdens runtime aan de MIP-SDK verstrekken.

Maak een implementatie voor een verificatiedelegatie door de klasse van mip::AuthDelegate de SDK uit te breiden en de mip::AuthDelegate::AcquireOAuth2Token() pure virtuele functie te overschrijven/implementeren. Volg de stappen die worden beschreven onder Quickstart voor initialisatie van bestands-SDK-toepassingen. De verificatiedelegatie wordt geïnstantieerd en later gebruikt door de beveiligingsprofiel- en beveiligingsengineobjecten.

Maak nu een implementatie voor een toestemmingsdelegatie door de klasse van mip::ConsentDelegate de SDK uit te breiden en de mip::AuthDelegate::GetUserConsent() pure virtuele functie te overschrijven/implementeren. Volg de stappen die worden beschreven onder Quickstart voor initialisatie van bestands-SDK-toepassingen. De gemachtigde voor toestemming wordt geïnstantieerd en later gebruikt door de beveiligingsprofiel- en beveiligingsengineobjecten.

Een beveiligingsprofiel en -engine maken

Zoals vermeld, zijn profiel- en engineobjecten vereist voor SDK-clients die GEBRUIKMAKEN van MIP-API's. Voltooi het codegedeelte van deze quickstart door code toe te voegen om het profiel- en engineobject te instantiëren:

Open vanuit Solution Explorer het CPP-bestand in uw project dat de implementatie van de main() methode bevat. Deze wordt standaard ingesteld op dezelfde naam als het project dat het bevat, die u hebt opgegeven tijdens het maken van het project.
Verwijder de gegenereerde implementatie van main(). Verwijder geen preprocessorrichtlijnen die door Visual Studio zijn gegenereerd tijdens het maken van het project (#pragma, #include). Voeg de volgende code toe na eventuele preprocessorrichtlijnen:

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

Vervang alle tijdelijke aanduidingen in de broncode die u zojuist hebt geplakt, met behulp van tekenreeksconstanten:

Tijdelijke aanduiding	Waarde	voorbeeld
<toepassings-id>	De Microsoft Entra-toepassings-id (GUID) die is toegewezen aan de toepassing die is geregistreerd in stap 2 van het artikel over het instellen en configureren van de MIP SDK (setup-configure-mip.md). Vervang 2 exemplaren.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<toepassingsnaam>	Een door de gebruiker gedefinieerde beschrijvende naam voor uw toepassing. Moet geldige ASCII-tekens bevatten (met uitzondering van ';'), en komt idealiter overeen met de toepassingsnaam die u hebt gebruikt in uw Microsoft Entra-registratie.	`"AppInitialization"`
<toepassingsversie>	Door de gebruiker gedefinieerde versiegegevens voor uw toepassing. Moet geldige ASCII-tekens bevatten (met uitzondering van ;).	`"1.1.0.0"`
<engine-account>	Het account dat wordt gebruikt voor de identiteit van de engine. Wanneer u zich verifieert met een gebruikersaccount tijdens het ophalen van tokens, moet deze overeenkomen met deze waarde.	`"user1@tenant.onmicrosoft.com"`
<motorstatus>	Door de gebruiker gedefinieerde status die aan de engine moet worden gekoppeld.	`"My App State"`

Voer nu een definitieve build van de toepassing uit en los eventuele fouten op. Uw code moet correct worden gebouwd, maar wordt nog niet correct uitgevoerd totdat u de volgende quickstart hebt voltooid. Als u de toepassing uitvoert, ziet u uitvoer die er ongeveer als volgt uitziet. De toepassing maakt het beveiligingsprofiel en de beveiligingsengine correct, maar had geen verificatiemodule geactiveerd en u hebt nog geen toegangstoken, totdat u de volgende quickstart hebt voltooid.
```
 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 . . .
```

Volgende stappen

Nu uw initialisatiecode is voltooid, bent u klaar voor de volgende quickstart, waar u de MIP Protection SDK gaat ervaren.

Beveiligingssjablonen weergeven

Delen via

Quickstart: Initialisatie van clienttoepassingen voor beveiligings-SDK's (C++)

Vereisten

Een Visual Studio-oplossing en -project maken

Waarnemersklassen implementeren om het beveiligingsprofiel en engineobjecten te bewaken

Een beveiligingsprofiel en -engine maken

Volgende stappen

Feedback

Aanvullende resources

Delen via

Quickstart: Initialisatie van clienttoepassingen voor beveiligings-SDK's (C++)

Vereisten

Een Visual Studio-oplossing en -project maken

Waarnemersklassen implementeren om het beveiligingsprofiel en engineobjecten te bewaken

Een verificatiedelegatie en een toestemmingsdelegen implementeren

Een gedelegeerde voor toestemming implementeren

Een beveiligingsprofiel en -engine maken

Volgende stappen

Feedback

Aanvullende resources