Ř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:
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(clientId: 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:
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 | 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 |
| 6 | 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 |
| 7 | 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 |
| 8 | 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. | No |
V nejjednodušší podobě můžete použít bezparametrovou verzi DefaultAzureCredential následujícím způsobem:
builder.Services.AddAzureClients(clientBuilder =>
{
clientBuilder.AddBlobServiceClient(
new Uri("https://<account-name>.blob.core.windows.net"));
DefaultAzureCredential credential = new();
clientBuilder.UseCredential(credential);
});
Tip
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
Chcete-li odebrat přihlašovací údaje z DefaultAzureCredential, použijte odpovídající Exclude-prefixed vlastnost defaultAzureCredentialOptions. Příklad:
builder.Services.AddAzureClients(clientBuilder =>
{
clientBuilder.AddBlobServiceClient(
new Uri("https://<account-name>.blob.core.windows.net"));
clientBuilder.UseCredential(new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
ExcludeEnvironmentCredential = true,
ExcludeWorkloadIdentityCredential = true,
ManagedIdentityClientId = userAssignedClientId,
}));
});
V předchozí ukázce EnvironmentCredential kódu a WorkloadIdentityCredential jsou odebrány z řetězu přihlašovacích údajů. V důsledku toho je prvním pokusem o ManagedIdentityCredentialpřihlašovací údaje . Upravený řetězec vypadá takto:
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 true tomu, že jsou nastaveny další Excludevlastnosti 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,
ExcludeAzureCliCredential = true,
ExcludeAzurePowerShellCredential = true,
ExcludeAzureDeveloperCliCredential = true,
ManagedIdentityClientId = userAssignedClientId
});
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.AddBlobServiceClient(
new Uri("https://<account-name>.blob.core.windows.net"));
clientBuilder.UseCredential(new ChainedTokenCredential(
new ManagedIdentityCredential(clientId: userAssignedClientId),
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ů. Varianta spravované identity ManagedIdentityCredential přiřazená uživatelem se nejprve pokusí a v případě potřeby následuje VisualStudioCredential. V grafické podobě řetězec vypadá takto:
Tip
Pokud chcete dosáhnout vyššího výkonu, optimalizujte řazení přihlašovacích údajů v ChainedTokenCredential produkčním prostředí. Přihlašovací údaje určené k použití v místním vývojovém prostředí by měly být přidány jako poslední.
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 důrazně zvažte přechod z DefaultAzureCredential jednoho z následujících řešení:
- Konkrétní
TokenCredentialimplementace, napříkladManagedIdentityCredential. Možnosti najdete v seznamu odvozených položek. - Pared-down
ChainedTokenCredentialimplementace optimalizovaná pro prostředí Azure, ve kterém vaše aplikace běží.
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
ManagedIdentityCredentialvž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í:
DefaultAzureCredentialkontroluje 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íDefaultAzureCredentialza běhu v libovolné aplikaci spuštěné na tomto počítači.
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,WorkloadIdentityCredentialaManagedIdentityCredentialkaž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 –VisualStudioCredentialv tomto případě. Od úspěchuVisualStudioCredentialnebyly použity žádné přihlašovací údaje.
