Rövid útmutató: Ügyfélalkalmazás inicializálása (C++)

Cikk
01/30/2024

Ez a rövid útmutató bemutatja, hogyan implementálhatja az ügyfél inicializálási mintáját, amelyet a MIP C++ SDK használ futásidőben.

Megjegyzés:

Az ebben a rövid útmutatóban ismertetett lépésekre minden olyan ügyfélalkalmazás esetében szükség van, amely a MIP-fájlt, szabályzatot vagy védelmi SDK-t használja. Bár ez a rövid útmutató bemutatja a Fájl SDK-k használatát, ugyanez a minta vonatkozik a Szabályzat és védelem SDK-kat használó ügyfelekre is. Töltse ki a többi rövid útmutatót egymás után, mivel mindegyik az előzőre épül, és ez az első.

Előfeltételek

Ha még nem tette meg, ügyeljen a következőre:

Hajtsa végre a Microsoft Information Protection (MIP) SDK beállításának és konfigurálásának lépéseit. Ez az "ügyfélalkalmazás inicializálása" rövid útmutató az SDK megfelelő beállítására és konfigurálására támaszkodik.
Tetszés szerint:
- Profil- és motorobjektumok áttekintése. A profil- és motorobjektumok univerzális fogalmak, amelyeket a MIP-fájlokat/szabályzatokat/védelmi SDK-okat használó ügyfelek igényelnek.
- Tekintse át a hitelesítési fogalmakat , és ismerje meg, hogyan valósítja meg a hitelesítést és a hozzájárulást az SDK és az ügyfélalkalmazás.
- Tekintse át a megfigyelői fogalmakat , hogy többet tudjon meg a megfigyelőkről és azok implementálásáról. A MIP SDK a megfigyelői mintát használja az aszinkron eseményértesítések implementálásához.

Visual Studio-megoldás és projekt létrehozása

Először létrehozzuk és konfiguráljuk a Visual Studio kezdeti megoldását és projektét, amelyre a többi rövid útmutató épül.

Nyissa meg a Visual Studio 2017-et, válassza a Fájl menü Új, Projekt parancsát. Az Új projekt párbeszédpanelen:
- A bal oldali panelEn, a Telepített egyéb nyelvek területen válassza a Visual C++ lehetőséget.
- A középső panelen válassza a Windows Konzolalkalmazás lehetőséget
- Az alsó panelen ennek megfelelően frissítse a projekt nevét, helyét és az azt tartalmazó megoldásnevet .
- Ha végzett, kattintson az OK gombra a jobb alsó sarokban.
Adja hozzá a MiP File SDK Nuget-csomagját a projekthez:
- A Megoldáskezelő kattintson a jobb gombbal a projektcsomópontra (közvetlenül a felső/megoldáscsomópont alatt), és válassza a NuGet-csomagok kezelése...:
- Amikor megnyílik a NuGet Csomagkezelő lap a Szerkesztőcsoport lapfülek területén:
  - Válassza a Tallózás lehetőséget.
  - Írja be a "Microsoft.InformationProtection" kifejezést a keresőmezőbe.
  - Válassza a "Microsoft.InformationProtection.File" csomagot.
  - Kattintson a "Telepítés", majd az "OK" gombra, amikor megjelenik az Előzetes verzió módosításainak megerősítése párbeszédpanel.

Megfigyelőosztály implementálása a fájlprofil és a motorobjektumok figyeléséhez

Most hozzon létre egy alapszintű implementációt egy fájlprofil megfigyelőosztályához az SDK osztályának mip::FileProfile::Observer kibővítésével. A megfigyelő példányosítása és későbbi használata a Fájlprofil objektum betöltésének figyelésére és a motorobjektum profilhoz való hozzáadására szolgál.

Adjon hozzá egy új osztályt a projekthez, amely a fejléc/.h és a implementáció/.cpp fájlokat is létrehozza Önnek:
- A Megoldáskezelő kattintson ismét a jobb gombbal a projektcsomópontra, válassza a Hozzáadás, majd az Osztály lehetőséget.
- Az Osztály hozzáadása párbeszédpanelen:
  - Az Osztálynév mezőben adja meg a "profile_observer" értéket. Figyelje meg, hogy a .h fájl és a .cpp fájlmező is automatikusan ki lesz töltve a megadott név alapján.
  - Ha végzett, kattintson az OK gombra.

Az osztály .h és .cpp fájljainak létrehozása után mindkét fájl megnyílik a Szerkesztőcsoport lapon. Most frissítse az egyes fájlokat az új megfigyelői osztály implementálásához:

Frissítse a "profile_observer.h" értéket a létrehozott profile_observer osztály kiválasztásával/törlésével. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket. Ezután másolja/illessze be a következő forrást a fájlba a meglévő előfeldolgozási irányelvek után:

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

Frissítse a "profile_observer.cpp" fájlt a létrehozott profile_observer osztály implementációjának kiválasztásával/törlésével. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket. Ezután másolja/illessze be a következő forrást a fájlba a meglévő előfeldolgozási irányelvek után:

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

Ha szeretné, az F6 (Build Solution) használatával futtassa a megoldás egy fordítási/csatolási tesztét, hogy a folytatás előtt biztosan sikeres legyen a buildelés.

Hitelesítési meghatalmazott implementálása

A MIP SDK az osztály bővíthetőségével valósítja meg a hitelesítést, amely lehetővé teszi a hitelesítés megosztását az ügyfélalkalmazással. Az ügyfélnek be kell szereznie egy megfelelő OAuth2 hozzáférési jogkivonatot, és futásidőben meg kell adnia a MIP SDK-nak.

Most hozzon létre egy implementációt egy hitelesítési delegált számára az SDK osztályának mip::AuthDelegate kibővítésével, valamint a mip::AuthDelegate::AcquireOAuth2Token() tiszta virtuális függvény felülbírálásával/implementálásával. A hitelesítési meghatalmazottat a fájlprofil és a fájlmotor objektumai később példányosítják és használják.

Az előző szakasz 1. lépésében használt Visual Studio "Osztály hozzáadása" funkcióval vegyen fel egy másik osztályt a projektbe. Ezúttal írja be a "auth_delegate" kifejezést az Osztálynév mezőbe.

Most frissítse az egyes fájlokat az új hitelesítési delegált osztály implementálásához:

Frissítse a "auth_delegate.h"-t úgy, hogy az összes létrehozott auth_delegate osztálykódot lecseréli a következő forrásra. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket:

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

Frissítse a "auth_delegate.cpp" fájlt úgy, hogy az összes létrehozott auth_delegate osztály-implementációt lecseréli a következő forrásra. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket.
Fontos

Az alábbi jogkivonat-beszerzési kód éles használatra nem alkalmas. Éles környezetben ezt olyan kódra kell cserélni, amely dinamikusan szerez be egy jogkivonatot a következő használatával:
- A Microsoft Entra-alkalmazásregisztrációban megadott appId és válasz/átirányítás URI (a válasz/átirányítás URI-nak meg kell egyeznie az alkalmazásregisztrációval)
- Az argumentumban challenge az SDK által átadott szolgáltatói és erőforrás-URL-cím (az erőforrás URL-címének meg kell egyeznie az alkalmazásregisztráció API-jával/engedélyével)
- Érvényes alkalmazás-/felhasználói hitelesítő adatok, ahol a fiók megfelel az identity SDK által átadott argumentumnak. Az OAuth2 "natív" ügyfeleinek felhasználói hitelesítő adatokat kell kérnie, és az "engedélyezési kód" folyamatot kell használniuk. Az OAuth2 "bizalmas ügyfelek" használhatják a saját biztonságos hitelesítő adataikat az "ügyfél hitelesítő adatai" folyamattal (például egy szolgáltatással), vagy kérhetik a felhasználói hitelesítő adatok megadását az "engedélyezési kód" folyamat (például egy webalkalmazás) használatával.
Az OAuth2-jogkivonatok beszerzése egy összetett protokoll, amelyet általában egy kódtár használatával hajtanak végre. A TokenAcquireOAuth2Token() metódust csak a MIP SDK hívja meg, szükség szerint.
```
#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;
}
```

Ha szeretné, az F6 (Build Solution) használatával futtassa a megoldás egy fordítási/csatolási tesztét, hogy a folytatás előtt biztosan sikeres legyen a buildelés.

Most hozzon létre egy implementációt egy hozzájárulási delegált számára az SDK osztályának mip::ConsentDelegate kibővítésével, valamint a mip::AuthDelegate::GetUserConsent() tiszta virtuális függvény felülbírálásával/implementálásával. A hozzájárulási meghatalmazottat a fájlprofil és a fájlmotor objektumai később példányosítják és használják.

Ha ugyanazt a Visual Studio "Osztály hozzáadása" funkciót használja, amelyet korábban használt, vegyen fel egy másik osztályt a projektbe. Ezúttal írja be a "consent_delegate" kifejezést az Osztálynév mezőbe.
Most frissítse az egyes fájlokat az új hozzájárulási delegált osztály implementálásához:
- Frissítse a "consent_delegate.h"-t úgy, hogy az összes létrehozott consent_delegate osztálykódot lecseréli a következő forrásra. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket:
```
#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;
};
```
- Frissítse a "consent_delegate.cpp" fájlt úgy, hogy az összes létrehozott consent_delegate osztály-implementációt lecseréli a következő forrásra. Ne távolítsa el az előző lépés (#pragma, #include) által létrehozott előprocesszor-irányelveket.
```
#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;
}
```
Ha szeretné, az F6 (Build Solution) használatával futtassa a megoldás egy fordítási/csatolási tesztét, hogy a folytatás előtt biztosan sikeres legyen a buildelés.

Fájlprofil és -motor létrehozása

Ahogy említettük, profil- és motorobjektumok szükségesek a MIP API-kat használó SDK-ügyfelekhez. Töltse ki a rövid útmutató kódolási részét úgy, hogy kódot ad hozzá a profil és a motorobjektumok példányosításához:

A Megoldáskezelő nyissa meg a metódus implementálását tartalmazó .cpp fájlt a main() projektben. Alapértelmezés szerint ugyanaz a név lesz, mint a projektet tartalmazó projekt, amelyet a projekt létrehozásakor adott meg.
Távolítsa el a generált implementációt.main() Ne távolítsa el a Visual Studio által a projekt létrehozása során létrehozott preprocesszor-irányelveket (#pragma, #include). Az előfeldolgozási irányelvek után fűzze hozzá a következő kódot:

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

Cserélje le az imént beillesztett forráskód összes helyőrző értékét sztringállandók használatával:

Helyőrző	Value	Example
<alkalmazásazonosító>	A Microsoft Entra alkalmazásazonosítója (GUID) a "MIP SDK beállításáról és konfigurációjáról" szóló cikk 2. lépésében regisztrált alkalmazáshoz van hozzárendelve. Cserélje le a 2 példányt.	`"0edbblll-8773-44de-b87c-b8c6276d41eb"`
<alkalmazás neve>	Az alkalmazás felhasználó által definiált rövid neve. Érvényes ASCII-karaktereket kell tartalmaznia (a ";" kivételével), és ideális esetben megegyezik a Microsoft Entra-regisztrációban használt alkalmazásnévvel.	`"AppInitialization"`
<alkalmazásverzió>	Felhasználó által megadott verzióadatok az alkalmazáshoz. Érvényes ASCII-karaktereket kell tartalmaznia (a ";" kivételével).	`"1.1.0.0"`
<motorfiók>	A motor identitásához használt fiók. Ha felhasználói fiókkal hitelesít a jogkivonatok beszerzése során, annak meg kell egyeznie ezzel az értékkel.	`"user1@tenant.onmicrosoft.com"`
<motorállapot>	A motorhoz társítandó felhasználó által definiált állapot.	`"My App State"`

Most készítse el az alkalmazás végleges buildjét, és oldja meg a hibákat. A kódnak sikeresnek kell lennie, de a következő rövid útmutató befejezéséig még nem fog megfelelően futni. Az alkalmazás futtatásakor az alábbihoz hasonló kimenet jelenik meg. A következő rövid útmutató befejezéséig nem lesz hozzáférési jogkivonata.

Következő lépések

Most, hogy elkészült az inicializálási kód, készen áll a következő rövid útmutatóra, ahol megkezdheti a MIP-fájl SDK-k használatát.

Bizalmassági címkék listázása

Rövid útmutató: Ügyfélalkalmazás inicializálása (C++)

Előfeltételek

Visual Studio-megoldás és projekt létrehozása

Megfigyelőosztály implementálása a fájlprofil és a motorobjektumok figyeléséhez

Hitelesítési meghatalmazott implementálása

Fájlprofil és -motor létrehozása

Következő lépések

Visszajelzés

Visszajelzés

További források

Rövid útmutató: Ügyfélalkalmazás inicializálása (C++)

Előfeltételek

Visual Studio-megoldás és projekt létrehozása

Megfigyelőosztály implementálása a fájlprofil és a motorobjektumok figyeléséhez

Hitelesítési meghatalmazott implementálása

Hozzájárulási meghatalmazott implementálása

Fájlprofil és -motor létrehozása

Következő lépések

Visszajelzés

Visszajelzés

További források