Referentieketens in de Azure Identity-bibliotheek voor .NET
De Azure Identity-bibliotheek biedt referenties: openbare klassen die zijn afgeleid van de TokenCredential-klasse van de Azure Core-bibliotheek. Een referentie vertegenwoordigt een afzonderlijke verificatiestroom voor het verkrijgen van een toegangstoken van Microsoft Entra-id. Deze referenties kunnen worden gekoppeld om een geordende reeks verificatiemechanismen te vormen die moeten worden geprobeerd.
Hoe een gekoppelde referentie werkt
Tijdens runtime probeert een referentieketen te verifiëren met behulp van de eerste referentie van de reeks. Als deze referentie geen toegangstoken kan verkrijgen, wordt de volgende referentie in de reeks geprobeerd, enzovoort, totdat een toegangstoken is verkregen. In het volgende sequentiediagram ziet u dit gedrag:
Waarom referentieketens gebruiken
Een gekoppelde referentie kan de volgende voordelen bieden:
Omgevingsbewustzijn: selecteert automatisch de meest geschikte referentie op basis van de omgeving waarin de app wordt uitgevoerd. Zonder deze code moet u als volgt code schrijven:
TokenCredential credential; if (app.Environment.IsProduction() || app.Environment.IsStaging()) { credential = new ManagedIdentityCredential(clientId: userAssignedClientId); } else { // local development environment credential = new VisualStudioCredential(); }Naadloze overgangen: uw app kan overstappen van lokale ontwikkeling naar uw faserings- of productieomgeving zonder verificatiecode te wijzigen.
Verbeterde tolerantie: bevat een terugvalmechanisme dat naar de volgende referentie wordt verplaatst wanneer het voorgaande geen toegangstoken kan verkrijgen.
Een gekoppelde referentie kiezen
Er zijn twee verschillende filosofieën voor het koppelen van referenties:
- Een keten afbreken: begin met een vooraf geconfigureerde keten en sluit uit wat u niet nodig hebt. Zie de overzichtssectie DefaultAzureCredential voor deze aanpak.
- 'Bouw' een keten op: Begin met een lege keten en neem alleen op wat u nodig hebt. Zie de overzichtssectie ChainedTokenCredential voor deze aanpak.
Overzicht van DefaultAzureCredential
DefaultAzureCredential is een vooraf geconfigureerde keten van referenties. Het is ontworpen om veel omgevingen te ondersteunen, samen met de meest voorkomende verificatiestromen en ontwikkelhulpprogramma's. In grafische vorm ziet de onderliggende keten er als volgt uit:
De volgorde waarin DefaultAzureCredential referenties worden geprobeerd, volgt.
| Order | Referentie | Beschrijving | Standaard ingeschakeld? |
|---|---|---|---|
| 1 | Omgeving | Leest een verzameling omgevingsvariabelen om te bepalen of een toepassingsservice-principal (toepassingsgebruiker) is geconfigureerd voor de app. Als dat het zo is, DefaultAzureCredential gebruikt u deze waarden om de app te verifiëren bij Azure. Deze methode wordt meestal gebruikt in serveromgevingen, maar kan ook worden gebruikt bij het lokaal ontwikkelen. |
Ja |
| 2 | Workloadidentiteit | Als de app is geïmplementeerd op een Azure-host waarvoor workloadidentiteit is ingeschakeld, verifieert u dat account. | Ja |
| 3 | Beheerde identiteit | Als de app is geïmplementeerd op een Azure-host waarvoor Managed Identity is ingeschakeld, verifieert u de app bij Azure met behulp van die beheerde identiteit. | Ja |
| 4 | Visual Studio | Als de ontwikkelaar zich bij Azure heeft geverifieerd door u aan te melden bij Visual Studio, moet u de app verifiëren bij Azure met hetzelfde account. | Ja |
| 5 | Azure-CLI | Als de ontwikkelaar is geverifieerd bij Azure met behulp van de opdracht van az login Azure CLI, moet u de app verifiëren bij Azure met hetzelfde account. |
Ja |
| 6 | Azure PowerShell | Als de ontwikkelaar is geverifieerd bij Azure met behulp van de cmdlet van Connect-AzAccount Azure PowerShell, moet u de app verifiëren bij Azure met hetzelfde account. |
Ja |
| 7 | Azure Developer CLI | Als de ontwikkelaar is geverifieerd bij Azure met behulp van de opdracht van azd auth login Azure Developer CLI, moet u zich verifiëren met dat account. |
Ja |
| 8 | Interactieve browser | Indien ingeschakeld, verifieert u de ontwikkelaar interactief via de standaardbrowser van het huidige systeem. | Nee |
In de eenvoudigste vorm kunt u de parameterloze versie als DefaultAzureCredential volgt gebruiken:
builder.Services.AddAzureClients(clientBuilder =>
{
clientBuilder.AddBlobServiceClient(
new Uri("https://<account-name>.blob.core.windows.net"));
DefaultAzureCredential credential = new();
clientBuilder.UseCredential(credential);
});
Tip
De UseCredential methode in het voorgaande codefragment wordt aanbevolen voor gebruik in ASP.NET Core-apps. Zie De Azure SDK voor .NET gebruiken in ASP.NET Core-apps voor meer informatie.
DefaultAzureCredential aanpassen
Als u een referentie wilt DefaultAzureCredentialverwijderen, gebruikt u de bijbehorende Excludeeigenschap -voorvoegsel in DefaultAzureCredentialOptions. Voorbeeld:
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,
}));
});
In het voorgaande codevoorbeeld EnvironmentCredential en WorkloadIdentityCredential worden ze verwijderd uit de referentieketen. Als gevolg hiervan is ManagedIdentityCredentialde eerste referentie die moet worden geprobeerd. De gewijzigde keten ziet er als volgt uit:
Notitie
InteractiveBrowserCredential is standaard uitgesloten en wordt daarom niet weergegeven in het voorgaande diagram. Als u wilt opnemen InteractiveBrowserCredential, geeft u door true aan constructor DefaultAzureCredential(Boolean) of stelt u de eigenschap in DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential op false.
Naarmate meer Excludeeigenschappen met voorvoegsel zijn ingesteld op true (referentieuitsluitingen zijn geconfigureerd), nemen de voordelen van het gebruik DefaultAzureCredential af. In dergelijke gevallen ChainedTokenCredential is dit een betere keuze en is minder code vereist. Ter illustratie gedragen deze twee codevoorbeelden zich op dezelfde manier:
credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
ExcludeEnvironmentCredential = true,
ExcludeWorkloadIdentityCredential = true,
ExcludeAzureCliCredential = true,
ExcludeAzurePowerShellCredential = true,
ExcludeAzureDeveloperCliCredential = true,
ManagedIdentityClientId = userAssignedClientId
});
Overzicht chainedTokenCredential
ChainedTokenCredential is een lege keten waaraan u referenties toevoegt aan de behoeften van uw app. Voorbeeld:
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()));
});
In het voorgaande codevoorbeeld wordt een aangepaste referentieketen gemaakt die bestaat uit twee referenties. De door de gebruiker toegewezen beheerde identiteitvariant wordt ManagedIdentityCredential eerst geprobeerd, gevolgd door VisualStudioCredential, indien nodig. In grafische vorm ziet de keten er als volgt uit:
Tip
Voor betere prestaties optimaliseert u de volgorde van referenties voor ChainedTokenCredential uw productieomgeving. Referenties die zijn bedoeld voor gebruik in de lokale ontwikkelomgeving, moeten als laatste worden toegevoegd.
Gebruiksrichtlijnen voor DefaultAzureCredential
DefaultAzureCredential is ongetwijfeld de eenvoudigste manier om aan de slag te gaan met de Azure Identity-bibliotheek, maar met dat gemak komt het van pas. Zodra u uw app in Azure hebt geïmplementeerd, moet u de verificatievereisten van de app begrijpen. Daarom kunt u het beste overstappen van DefaultAzureCredential een van de volgende oplossingen:
- Een specifieke
TokenCredentialimplementatie, zoalsManagedIdentityCredential. Zie de afgeleide lijst voor opties. - Een geparseerde implementatie die is geoptimaliseerd voor de Azure-omgeving
ChainedTokenCredentialwaarin uw app wordt uitgevoerd.
Waarom is:
- Problemen met foutopsporing: wanneer verificatie mislukt, kan het lastig zijn om fouten op te sporen en de referentie te identificeren. U moet logboekregistratie inschakelen om de voortgang te zien van de ene referentie naar de volgende en de succes-/foutstatus van elke referentie. Zie Fouten opsporen in een gekoppelde referentie voor meer informatie.
- Prestatieoverhead: het proces waarbij meerdere referenties opeenvolgend worden geprobeerd, kan leiden tot prestatieoverhead. Wanneer een beheerde identiteit bijvoorbeeld wordt uitgevoerd op een lokale ontwikkelcomputer, is de beheerde identiteit niet beschikbaar.
ManagedIdentityCredentialDaarom mislukt altijd in de lokale ontwikkelomgeving, tenzij deze expliciet is uitgeschakeld via de bijbehorendeExcludevoorvoegseleigenschap. - Onvoorspelbaar gedrag:
DefaultAzureCredentialcontroleert op de aanwezigheid van bepaalde omgevingsvariabelen. Het is mogelijk dat iemand deze omgevingsvariabelen kan toevoegen of wijzigen op systeemniveau op de hostcomputer. Deze wijzigingen zijn globaal van toepassing en wijzigen daarom het gedrag vanDefaultAzureCredentialtijdens runtime in elke app die op die computer wordt uitgevoerd.
Fouten opsporen in een gekoppelde referentie
Als u een onverwacht probleem wilt vaststellen of wilt weten wat een gekoppelde referentie doet, schakelt u logboekregistratie in uw app in. U kunt de logboeken desgewenst filteren op alleen de gebeurtenissen die zijn verzonden uit de Azure Identity-bibliotheek. Voorbeeld:
using AzureEventSourceListener listener = new((args, message) =>
{
if (args is { EventSource.Name: "Azure-Identity" })
{
Console.WriteLine(message);
}
}, EventLevel.LogAlways);
Voor illustratiedoeleinden wordt ervan uitgegaan dat de parameterloze vorm van is gebruikt voor het verifiëren van DefaultAzureCredential een aanvraag voor een Log Analytics-werkruimte. De app is uitgevoerd in de lokale ontwikkelomgeving en Visual Studio is geverifieerd bij een Azure-account. De volgende keer dat de app werd uitgevoerd, worden de volgende relevante vermeldingen weergegeven in de uitvoer:
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
In de voorgaande uitvoer ziet u dat:
EnvironmentCredential,WorkloadIdentityCredentialenManagedIdentityCredentialelk kan in die volgorde geen Microsoft Entra-toegangstoken verkrijgen.- De
DefaultAzureCredential credential selected:vermelding -voorvoegsel geeft de referentie aan die is geselecteerd,VisualStudioCredentialin dit geval. OmdatVisualStudioCredentialdit is gelukt, zijn er geen referenties meer gebruikt.
