Quickstart: Initialisatie van clienttoepassingen (C++)
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-bestands-, beleids- of beveiligings-SDK's. Hoewel in deze quickstart het gebruik van de bestands-SDK's wordt gedemonstreert, is hetzelfde patroon van toepassing op clients die gebruikmaken van de SDK's voor beleid en beveiliging. Voltooi de resterende quickstarts serieel, omdat elke quickstart voortbouwt op de vorige, waarbij dit de eerste is.
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 File 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.File.
- Klik op Installeren en klik vervolgens op OK wanneer het bevestigingsvenster voor wijzigingen in het voorbeeld wordt weergegeven.
Een waarnemersklasse implementeren om het bestandsprofiel en engineobjecten te bewaken
Maak nu een eenvoudige implementatie voor een waarnemersklasse voor bestandsprofielen door de klasse van de SDK uit te mip::FileProfile::Observer breiden. De waarnemer wordt geïnstantieerd en later gebruikt om het laden van het object Bestandsprofiel te controleren 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_observerklasse 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/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; };Werk profile_observer.cpp bij door de gegenereerde
profile_observerklasse-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::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); }
Gebruik eventueel F6 (Build Solution) om een testcompilatie/koppeling van uw oplossing uit te voeren om ervoor te zorgen dat deze correct wordt gebouwd voordat u doorgaat.
Een verificatiedelegatie implementeren
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 nu 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. De verificatiedelegatie wordt geïnstantieerd en later gebruikt door de bestandsprofiel- en bestandsengineobjecten.
Met dezelfde Visual Studio-functie 'Klasse toevoegen' die we in stap 1 van de vorige sectie hebben gebruikt, voegt u nog een klasse toe aan uw project. Voer deze keer 'auth_delegate' in het veld Klassenaam in.
Werk nu elk bestand bij om uw nieuwe gemachtigde klasse voor verificatie te implementeren:
Werk 'auth_delegate.h' bij door alle gegenereerde
auth_delegateklassecode te vervangen door de volgende bron. Verwijder de preprocessorrichtlijnen die zijn gegenereerd door de vorige stap niet (#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; };Werk 'auth_delegate.cpp' bij door alle gegenereerde
auth_delegateklasse-implementatie te vervangen door de volgende bron. Verwijder de preprocessorrichtlijnen die door de vorige stap zijn gegenereerd (#pragma, #include) niet .Belangrijk
De volgende code voor het verkrijgen van tokens is niet geschikt voor productiegebruik. In productie moet dit worden vervangen door code die dynamisch een token verkrijgt, met behulp van:
- De appId en antwoord-/omleidings-URI die is opgegeven in uw Microsoft Entra-app-registratie (antwoord-/omleidings-URI moet overeenkomen met uw app-registratie)
- De instantie- en resource-URL die door de SDK wordt doorgegeven in het
challengeargument (resource-URL moet overeenkomen met de API/machtigingen van uw app-registratie) - Geldige app-/gebruikersreferenties, waarbij het account overeenkomt met het
identityargument dat door de SDK wordt doorgegeven. OAuth2-clients moeten om gebruikersreferenties vragen en de stroom 'autorisatiecode' gebruiken. OAuth2 'vertrouwelijke clients' kunnen hun eigen beveiligde referenties gebruiken met de stroom 'clientreferenties' (zoals een service) of vragen om gebruikersreferenties met behulp van de stroom 'autorisatiecode' (zoals een web-app).
OAuth2-tokenverwerving is een complex protocol en wordt normaal gesproken bereikt met behulp van een bibliotheek. TokenAcquireOAuth2Token() wordt alleen aangeroepen door de MIP SDK, indien nodig.
#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; }
Gebruik eventueel F6 (Build Solution) om een testcompilatie/koppeling van uw oplossing uit te voeren om ervoor te zorgen dat deze correct wordt gebouwd voordat u doorgaat.
Een gedelegeerde voor toestemming implementeren
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. De gemachtigde voor toestemming wordt geïnstantieerd en later gebruikt door de bestandsprofiel- en bestandsengineobjecten.
Met dezelfde Visual Studio-functie Klasse toevoegen die we eerder hebben gebruikt, voegt u een andere klasse toe aan uw project. Voer deze keer 'consent_delegate' in het veld Klassenaam in.
Werk nu elk bestand bij om uw nieuwe machtigingsdelegenklasse te implementeren:
Werk 'consent_delegate.h' bij door alle gegenereerde
consent_delegateklassecode te vervangen door de volgende bron. Verwijder de preprocessorrichtlijnen die zijn gegenereerd door de vorige stap niet (#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; };Werk 'consent_delegate.cpp' bij door alle gegenereerde
consent_delegateklasse-implementatie te vervangen door de volgende bron. Verwijder de preprocessorrichtlijnen die door de vorige stap zijn gegenereerd (#pragma, #include) niet .#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; }
Gebruik eventueel F6 (Build Solution) om een testcompilatie/koppeling van uw oplossing uit te voeren om ervoor te zorgen dat deze correct wordt gebouwd voordat u doorgaat.
Een bestandsprofiel 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_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;
}
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 'INSTALLATIE en configuratie van de MIP SDK' . 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. U hebt geen toegangstoken om op te geven, totdat u de volgende quickstart hebt voltooid.
Volgende stappen
Nu uw initialisatiecode is voltooid, bent u klaar voor de volgende quickstart, waar u de MIP-bestands-SDK's gaat ervaren.