Sdílet prostřednictvím

Řetězy přihlašovacích údajů v knihovně identit Azure pro .NET

Knihovna Identit Azure poskytuje přihlašovací údaje – veřejné třídy odvozené z třídy TokenCredential knihovny Azure Core. Přihlašovací údaje představují jedinečný tok ověřování pro získání přístupového tokenu z ID Microsoft Entra. Tyto přihlašovací údaje je možné zřetězeny dohromady a vytvořit seřazenou posloupnost ověřovacích mechanismů, které se mají pokusit.

Jak funguje zřetězený přihlašovací údaje

Za běhu se řetěz přihlašovacích údajů pokusí ověřit pomocí prvních přihlašovacích údajů sekvence. Pokud se tento přihlašovací údaj nepodaří získat přístupový token, pokusí se další přihlašovací údaje v této sekvenci atd., dokud se přístupový token úspěšně nezíská. Toto chování znázorňuje následující sekvenční diagram:

Diagram sekvence řetězu přihlašovacích údajů

Proč používat řetězy přihlašovacích údajů

Zřetězený přihlašovací údaje můžou nabídnout následující výhody:

  • Rozpoznávání prostředí: Automaticky vybere nejvhodnější přihlašovací údaje na základě prostředí, ve kterém je aplikace spuštěná. Bez něj byste museli psát kód takto:

    TokenCredential credential;

if (app.Environment.IsProduction() || app.Environment.IsStaging())
{
    credential = new ManagedIdentityCredential(
        ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
}
else
{
    // local development environment
    credential = new VisualStudioCredential();
}

  • Bezproblémové přechody: Aplikace se může přesunout z místního vývoje do přípravného nebo produkčního prostředí beze změny ověřovacího kódu.

  • Vylepšená odolnost: Zahrnuje náhradní mechanismus, který se přesune na další přihlašovací údaje, když se předchozí pokus o získání přístupového tokenu nezdaří.

Výběr zřetězených přihlašovacích údajů

Existují dvě různorodé filozofie pro řetězení přihlašovacích údajů:

  • "Odbourat" řetězec: Začněte předkonfigurovaným řetězem a vylučte, co nepotřebujete. Tento přístup najdete v části s přehledem DefaultAzureCredential.
  • "Sestavte" řetězec: Začněte prázdným řetězem a zahrňte pouze to, co potřebujete. Tento přístup najdete v části Přehled ChainedTokenCredential.

Přehled defaultAzureCredential

DefaultAzureCredential je předkonfigurovaný řetězec přihlašovacích údajů. Je navržená tak, aby podporovala mnoho prostředí spolu s nejběžnějšími toky ověřování a vývojářskými nástroji. Základní řetězec v grafické podobě vypadá takto:

Diagram znázorňující tok ověřování DefaultAzureCredential

Pořadí, ve kterém DefaultAzureCredential se pokoušíte o přihlašovací údaje, následuje.

Objednávka Reference Popis Povoleno ve výchozím nastavení?
0 Prostředí Načte kolekci proměnných prostředí a určí, jestli je pro aplikaci nakonfigurovaný instanční objekt aplikace (uživatel aplikace). Pokud ano, DefaultAzureCredential použije tyto hodnoty k ověření aplikace v Azure. Tato metoda se nejčastěji používá v serverových prostředích, ale dá se použít také při místním vývoji. Ano
2 Identita úloh Pokud je aplikace nasazená na hostitele Azure s povolenou identitou úloh, ověřte tento účet. Ano
3 Spravovaná identita Pokud je aplikace nasazená na hostitele Azure s povolenou spravovanou identitou, ověřte ji v Azure pomocí této spravované identity. Ano
4 Visual Studio Pokud se vývojář ověřil v Azure přihlášením k sadě Visual Studio, ověřte aplikaci do Azure pomocí stejného účtu. Ano
5 Visual Studio Code Pokud se vývojář ověřil prostřednictvím rozšíření Azure Resources ve Visual Studio Code a je nainstalovaný balíček Azure.Identity.Broker, autentizujte tento účet. Ano
6 Azure CLI Pokud se vývojář ověřil v Azure pomocí příkazu Azure CLI az login , ověřte aplikaci v Azure pomocí stejného účtu. Ano
7 Azure PowerShell Pokud se vývojář ověřil v Azure pomocí rutiny Azure PowerShellu Connect-AzAccount , ověřte aplikaci v Azure pomocí stejného účtu. Ano
8 Azure Developer CLI Pokud se vývojář ověřil v Azure pomocí příkazu Azure Developer CLI azd auth login , ověřte ho pomocí daného účtu. Ano
9 Interaktivní prohlížeč Pokud je tato možnost povolená, interaktivně ověřte vývojáře prostřednictvím výchozího prohlížeče aktuálního systému. Ne
10 Makléř Ověřuje se pomocí výchozího účtu přihlášeného k operačnímu systému prostřednictvím zprostředkovatele. Vyžaduje, aby byl nainstalovaný balíček Azure.Identity.Broker . Ano

V nejjednodušší podobě můžete použít bezparametrovou verzi DefaultAzureCredential následujícím způsobem:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));
});

Návod

Metoda UseCredential v předchozím fragmentu kódu se doporučuje použít v aplikacích ASP.NET Core. Další informace najdete v tématu Použití sady Azure SDK pro .NET v aplikacích ASP.NET Core.

Přizpůsobení defaultAzureCredential

Následující části popisují strategie pro kontrolu, které přihlašovací údaje jsou zahrnuty v řetězci.

Vyloučení jednotlivých přihlašovacích údajů

Chcete-li vyloučit jednotlivé přihlašovací údaje z DefaultAzureCredential, použijte odpovídající vlastnost s prefixem Exclude v DefaultAzureCredentialOptions. Příklad:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

V předchozí ukázce kódu , EnvironmentCredentialManagedIdentityCredentiala WorkloadIdentityCredential jsou odebrány z řetězu přihlašovacích údajů. V důsledku toho je prvním pokusem o VisualStudioCredentialpřihlašovací údaje . Upravený řetězec obsahuje pouze přihlašovací údaje pro vývoj a vypadá takto:

DefaultAzureCredential s použitím vlastností Excludes

Poznámka:

InteractiveBrowserCredential je ve výchozím nastavení vyloučena, a proto se v předchozím diagramu nezobrazuje. InteractiveBrowserCredentialZahrnout , buď předat true konstruktor DefaultAzureCredential(Boolean) nebo nastavit vlastnost DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential na false.

Vzhledem k Exclude tomu, že jsou nastaveny další truevlastnosti s předponou (konfigurují se vyloučení přihlašovacích údajů), výhody použití DefaultAzureCredential se snižují. V takových případech ChainedTokenCredential je lepší volbou a vyžaduje méně kódu. Pro ilustraci se tyto dvě ukázky kódu chovají stejným způsobem:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ExcludeBrokerCredential = true,
    });

Vyloučení kategorie typu přihlašovacích údajů

Chcete-li vyloučit všechny přihlašovací údaje Developer tool nebo Deployed service, nastavte proměnnou prostředí AZURE_TOKEN_CREDENTIALS na prod nebo dev. Pokud se použije hodnota prod, základní řetězec přihlašovacích údajů vypadá takto:

DefaultAzureCredential s AZURE_TOKEN_CREDENTIALS nastaveným na 'prod'

Pokud se použije hodnota dev , řetězec vypadá takto:

DefaultAzureCredential s AZURE_TOKEN_CREDENTIALS nastaveným na dev

Chcete-li zajistit, aby byla proměnná prostředí definována a nastavena na podporovaný řetězec, použijte DefaultAzureCredential(String, DefaultAzureCredentialOptions) konstruktoru přetížení.

Použití konkrétních přihlašovacích údajů

Pokud chcete vyloučit všechny přihlašovací údaje kromě jednoho, nastavte proměnnou AZURE_TOKEN_CREDENTIALS prostředí na název přihlašovacích údajů. Například můžete zmenšit DefaultAzureCredential řetěz na VisualStudioCredential tím, že nastavíte AZURE_TOKEN_CREDENTIALS na VisualStudioCredential. Porovnání řetězců se provádí bez rozlišování velkých a malých písmen. Platné řetězcové hodnoty pro proměnnou prostředí zahrnují:

  • AzureCliCredential
  • AzureDeveloperCliCredential
  • AzurePowerShellCredential
  • BrokerCredential
  • EnvironmentCredential
  • InteractiveBrowserCredential
  • ManagedIdentityCredential
  • VisualStudioCredential
  • VisualStudioCodeCredential
  • WorkloadIdentityCredential

Důležité

AZURE_TOKEN_CREDENTIALS Proměnná prostředí podporuje jednotlivé identifikátory přihlašovacích údajů ve verzích balíčku Azure.Identity 1.15.0 a vyšších.

Chcete-li zajistit, aby byla proměnná prostředí definována a nastavena na podporovaný řetězec, použijte přetížení DefaultAzureCredential(String, DefaultAzureCredentialOptions)konstruktoru.

Přehled ChainedTokenCredential

ChainedTokenCredential je prázdný řetězec, ke kterému přidáváte přihlašovací údaje, které vyhovují potřebám vaší aplikace. Příklad:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

Předchozí ukázka kódu vytvoří přizpůsobený řetěz přihlašovacích údajů složený ze dvou přihlašovacích údajů v době vývoje. Nejprve se provede AzurePowerShellCredential, a pokud je to nutné, následuje VisualStudioCredential. V grafické podobě řetězec vypadá takto:

ChainedTokenCredential

Návod

Pokud chcete dosáhnout vyššího výkonu, optimalizujte řazení přihlašovacích údajů v ChainedTokenCredential od většiny po nejméně používané přihlašovací údaje.

Pokyny k použití pro DefaultAzureCredential

DefaultAzureCredential je nepochybně nejjednodušší způsob, jak začít s knihovnou identit Azure, ale s tím, že pohodlí přináší kompromisy. Po nasazení aplikace do Azure byste měli porozumět požadavkům na ověřování aplikace. Z tohoto důvodu nahraďte DefaultAzureCredential konkrétní implementací TokenCredential, například ManagedIdentityCredential. Možnosti najdete v seznamu odvozených položek.

Tady je důvod:

  • Problémy s laděním: Při selhání ověřování může být náročné ladit a identifikovat odsunuté přihlašovací údaje. Abyste viděli průběh z jednoho pověření na další a stav úspěchu/selhání každého z nich, musíte povolit protokolování. Další informace najdete v tématu Ladění zřetězených přihlašovacích údajů.
  • Režie na výkon: Proces postupného pokusu o více přihlašovacích údajů může představovat režii na výkon. Například při spuštění na místním vývojovém počítači není spravovaná identita k dispozici. V důsledku toho ManagedIdentityCredential vždy selže v místním vývojovém prostředí, pokud není explicitně zakázáno prostřednictvím odpovídající Excludevlastnosti -prefixed.
  • Nepředvídatelné chování: DefaultAzureCredential kontroluje přítomnost určitých proměnných prostředí. Je možné, že někdo může přidat nebo upravit tyto proměnné prostředí na úrovni systému na hostitelském počítači. Tyto změny platí globálně a proto mění chování DefaultAzureCredential za běhu v libovolné aplikaci spuštěné na tomto počítači. Další informace o neprediktovatelnosti najdete v tématu Použití deterministických přihlašovacích údajů v produkčních prostředích.

Ladění zřetězených přihlašovacích údajů

Pokud chcete diagnostikovat neočekávaný problém nebo zjistit, co dělá zřetězený přihlašovací údaj, povolte protokolování v aplikaci. Volitelně můžete protokoly filtrovat jenom na ty události generované z knihovny identit Azure. Příklad:

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

Pro ilustraci předpokládejme, že se k ověření požadavku v pracovním prostoru služby Log Analytics použila bez DefaultAzureCredential parametrů. Aplikace se spustila v místním vývojovém prostředí a Visual Studio se ověřilo pro účet Azure. Při příštím spuštění aplikace se ve výstupu zobrazí následující relevantní položky:

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

V předchozím výstupu si všimněte, že:

  • EnvironmentCredential, WorkloadIdentityCredentiala ManagedIdentityCredential každý z nich se nepodařilo získat přístupový token Microsoft Entra v daném pořadí.
  • Položka DefaultAzureCredential credential selected:-prefixed označuje vybrané přihlašovací údaje –VisualStudioCredential v tomto případě. Od úspěchu VisualStudioCredential nebyly použity žádné přihlašovací údaje.
  • Last updated on