Hitelesítőadat-láncok az Azure Identity C++ ügyfélkódtárában

Az Azure Identity-ügyfélkódtár hitelesítő adatokat biztosít – nyilvános típusokat, amelyek az Azure Core-kódtár TokenCredential absztrakt alaposztályából származnak. A hitelesítő adatok egy különálló hitelesítési folyamatot jelentenek a hozzáférési jogkivonat Microsoft Entra-azonosítóból való beszerzéséhez. Ezek a hitelesítő adatok összefűzhetők, hogy a megkísérlendő hitelesítési mechanizmusok rendezett sorozatát alakíthassák ki.

Láncolt hitelesítő működése

Futásidőben egy hitelesítőadat-lánc megpróbálja a hitelesítést a sorozat első hitelesítő adata alapján végrehajtani. Ha a hitelesítő adatok nem szereznek be hozzáférési jogkivonatot, a rendszer megkísérli a következő hitelesítő adatot a sorozatban, és így tovább, amíg egy hozzáférési jogkivonatot nem szerez be sikeresen. A következő szekvenciadiagram ezt a viselkedést szemlélteti:

hitelesítőadatlánc-sorozatot ábrázoló diagram.

Miért érdemes hitelesítőadat-láncokat használni?

A láncolt hitelesítés a következő előnyöket kínálhatja:

Környezettudatosság: Automatikusan kiválasztja a legmegfelelőbb hitelesítő adatokat az alkalmazás futási környezete alapján. Nélküle a következőhöz hasonló kódot kell írnia:

// Set up credential based on environment (Azure or local development)
std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
if (std::getenv("WEBSITE_HOSTNAME"))
{
    credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
}
else
{
    credential = std::make_shared<Azure::Identity::AzureCliCredential>();
}

Zökkenőmentes váltások: Az alkalmazás gond nélkül átállhat a helyi fejlesztésből az előkészítő vagy éles környezetre, anélkül, hogy módosítaná a hitelesítési kódot.
Továbbfejlesztett rugalmasság: Tartalmaz egy tartalék mechanizmust, amely a következő hitelesítő adatokra lép, ha az előző nem szerez be hozzáférési tokent.

Láncolt azonosító kiválasztása

A C++ használatával két lehetőség közül választhat a hitelesítő adatok láncolására:

Előre konfigurált lánchasználata: Használja a DefaultAzureCredential típus által implementált előre konfigurált láncot. Ehhez a megközelítéshez tekintse meg a DefaultAzureCredential áttekintési szakaszát .
Egyéni hitelesítőadat-lánc létrehozása: Kezdje üres lánccal, és csak a szükséges adatokat foglalja bele. Ehhez a megközelítéshez tekintse meg a ChainedTokenCredential áttekintési szakaszát .

DefaultAzureCredential – áttekintés

A DefaultAzureCredential egy véleményezett, előre konfigurált hitelesítőadat-lánc. Kialakítása számos környezetet támogat, a leggyakoribb hitelesítési folyamatokkal és fejlesztői eszközökkel együtt. Grafikus formában az alapul szolgáló lánc a következőképpen néz ki:

A DefaultAzureCredential hitelesítési folyamatot bemutató diagram.

A hitelesítő adatokra tett kísérletek sorrendje a következő. DefaultAzureCredential

Rendelés	Megbízólevél	Leírás
1	Környezet	Beolvassa a környezeti változók gyűjteményét annak megállapításához, hogy az alkalmazáshoz konfigurálva van-e egy alkalmazás-szolgáltatásazonosító (alkalmazásfelhasználó). Ha igen, `DefaultAzureCredential` ezeket az értékeket használja az alkalmazás Azure-beli hitelesítéséhez. Ezt a módszert leggyakrabban kiszolgálókörnyezetekben használják, de helyi fejlesztéskor is használható.
2	Terhelésazonosság	Ha az alkalmazás olyan Azure-gazdagépen van üzembe helyezve, amelyen engedélyezve van a Számítási feladat identitása, hitelesítse ezt a fiókot.
3	Kezelhető identitás	Ha az alkalmazás olyan Azure-gazdagépen van üzembe helyezve, amelyen engedélyezve van a felügyelt identitás, hitelesítse az alkalmazást az Azure-ban ezzel a felügyelt identitással.
4	Azure CLI	Ha a fejlesztő az Azure CLI `az login` parancsával hitelesítette az Azure-t, azonos fiókkal hitelesítse az alkalmazást az Azure-ban.

Legegyszerűbb formájában a DefaultAzureCredential paraméter nélküli verzióját használhatja az alábbiak szerint:

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

A DefaultAzureCredential testreszabása

Az alábbi szakaszok a láncban szereplő hitelesítő adatok szabályozására szolgáló stratégiákat ismertetik.

Hitelesítőadat-típus kategória kizárása

Ha ki akarja zárni az összes Developer tool vagy Deployed service hitelesítő adatot, állítsa be a AZURE_TOKEN_CREDENTIALS környezeti változót prod vagy dev értékre. Ha egy értéket prod használ, a mögöttes hitelesítőadat-lánc a következőképpen néz ki:

A DefaultAzureCredential értéket ábrázoló diagram AZURE_TOKEN_CREDENTIALS

Ha a(z) dev értéket használjuk, a lánc csak a(z) AzureCliCredential-t tartalmazza.

Annak érdekében, hogy a környezeti változó definiálva legyen, és egy támogatott sztringre legyen állítva, adja át true a DefaultAzureCredential konstruktornak:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Fontos

A fent említett konstruktor túlterhelését az 1.13.1-s és újabb csomagverziók támogatják azure-identity-cpp .

Adott hitelesítő adat használata

Ha egy kivételével minden hitelesítő adatot ki szeretne zárni, állítsa be a környezeti változót AZURE_TOKEN_CREDENTIALS a hitelesítő adatok nevére. Például a DefaultAzureCredential láncot AzureCliCredential-re csökkentheti azzal, hogy a AZURE_TOKEN_CREDENTIALS értékét AzureCliCredential-re állítja be. A sztring-összehasonlítás kis- és nagybetűkre érzéketlen módon történik. A környezeti változó érvényes sztringértékei a következők:

AzureCliCredential
EnvironmentCredential
ManagedIdentityCredential
WorkloadIdentityCredential

Annak érdekében, hogy a környezeti változó definiálva legyen, és egy támogatott sztringre legyen állítva, adja át true a DefaultAzureCredential konstruktornak:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Fontos

A fent említett konstruktor túlterhelését az 1.13.1-s és újabb csomagverziók támogatják azure-identity-cpp .

ChainedTokenCredential áttekintés

A ChainedTokenCredential egy üres lánc, amelyhez hitelesítő adatokat ad hozzá az alkalmazás igényeinek megfelelően. Például:

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

Az előző kódminta egy személyre szabott hitelesítőadat-láncot hoz létre, amely két hitelesítő adatból áll. ManagedIdentityCredential-t kísérlik meg először, majd szükség esetén AzureCliCredential-et. Grafikus formában a lánc a következőképpen néz ki:

A ManagedIdentityCredential és az AzureCliCredential elemekből álló ChainedTokenCredential-példány hitelesítési folyamatát bemutató ábra.

Jótanács

A jobb teljesítmény érdekében optimalizálja a hitelesítő adatok sorrendjét ChainedTokenCredential a legtöbbtől a legkevésbé használt hitelesítő adatokig.

Használati útmutató a DefaultAzureCredentialhoz

DefaultAzureCredential kétségtelenül az Azure Identity-ügyfélkódtár használatának legegyszerűbb módja, de ezzel a kényelemmel kompromisszumok is járnak. Miután üzembe helyezi az alkalmazást az Azure-ban, ismernie kell az alkalmazás hitelesítési követelményeit. Ezért cserélje le a DefaultAzureCredential egy adott TokenCredential implementációra, például ManagedIdentityCredential.

A következőkért:

Hibakeresési problémák: Ha a hitelesítés sikertelen, a hibás hitelesítő adatok hibakeresése és azonosítása kihívást jelenthet. Engedélyeznie kell a naplózást, hogy láthassa az egyik hitelesítő adatból a következőbe való előrehaladást, valamint az egyes hitelesítő adatok sikerességi/sikertelenségi állapotát. További információ: Láncolt hitelesítő adatok hibakeresése.
Teljesítményterhelés: A több hitelesítő adat egymás utáni kipróbálásának folyamata teljesítményterhelést okozhat. Ha például helyi fejlesztőgépen fut, a felügyelt identitás nem érhető el. ManagedIdentityCredential Ezért a helyi fejlesztési környezetben mindig meghiúsul.
Kiszámíthatatlan viselkedés: DefaultAzureCredential bizonyos környezeti változók jelenlétét ellenőrzi. Lehetséges, hogy valaki hozzáadhatja vagy módosíthatja ezeket a környezeti változókat a gazdaszámítógép rendszerszintjén. Ezek a módosítások globálisan érvényesek, és ezért módosítják a DefaultAzureCredential futásidőben való viselkedését a számítógépen futó alkalmazásokban.

Láncolt hitelesítő adatok hibakeresése

Egy váratlan probléma diagnosztizálásához vagy a láncolt hitelesítő adatok használatának megértéséhez engedélyezze a naplózást az alkalmazásban. Ábrakészítés céljából tegyük fel, hogy a paraméter nélküli formátum DefaultAzureCredential a Blob Storage-fiókra irányuló kérések hitelesítésére szolgál. Az alkalmazás a helyi fejlesztési környezetben fut, és a fejlesztő az Azure CLI használatával hitelesítve van az Azure-ban. Az alkalmazás futtatásakor az alábbi vonatkozó bejegyzések jelennek meg a kimenetben:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from ManagedIdentityCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

Az előző kimenetben figyelje meg, hogy:

EnvironmentCredential, WorkloadIdentityCredentialés ManagedIdentityCredential ebben a sorrendben nem sikerült beszerezni a Microsoft Entra hozzáférési jogkivonatot.
ManagedIdentityCredential sikeres lesz, amint azt egy "Successfully got token from ManagedIdentityCredential" kezdetű bejegyzés jelzi.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-11-24