Dela via


Autentiseringskedjor i Azure Identity-biblioteket för .NET

Azure Identity-biblioteket tillhandahåller autentiseringsuppgifter – offentliga klasser som härleds från Azure Core-bibliotekets TokenCredential-klass . En autentiseringsuppgift representerar ett distinkt autentiseringsflöde för att hämta en åtkomsttoken från Microsoft Entra-ID. Dessa autentiseringsuppgifter kan kopplas samman för att bilda en ordnad sekvens med autentiseringsmekanismer som ska försökas.

Så här fungerar en länkad autentiseringsuppgift

Vid körning försöker en autentiseringskedja autentisera med sekvensens första autentiseringsuppgifter. Om det inte går att hämta en åtkomsttoken görs nästa autentiseringsuppgifter i sekvensen och så vidare tills en åtkomsttoken har hämtats. Följande sekvensdiagram illustrerar det här beteendet:

Sekvensdiagram för autentiseringsuppgifter

Varför använda autentiseringskedjor

En länkad autentiseringsuppgift kan erbjuda följande fördelar:

  • Miljömedvetenhet: Väljer automatiskt de lämpligaste autentiseringsuppgifterna baserat på miljön där appen körs. Utan den skulle du behöva skriva kod så här:

    TokenCredential credential;
    
    if (app.Environment.IsProduction() || app.Environment.IsStaging())
    {
        credential = new ManagedIdentityCredential(clientId: userAssignedClientId);
    }
    else
    {
        // local development environment
        credential = new VisualStudioCredential();
    }
    
  • Sömlösa övergångar: Din app kan gå från lokal utveckling till mellanlagrings- eller produktionsmiljön utan att ändra autentiseringskoden.

  • Förbättrad återhämtning: Innehåller en återställningsmekanism som flyttas till nästa autentiseringsuppgift när den föregående misslyckas med att hämta en åtkomsttoken.

Så här väljer du en länkad autentiseringsuppgift

Det finns två olika filosofier för autentiseringslänkning:

  • "Riv ned" en kedja: Börja med en förkonfigurerad kedja och uteslut det du inte behöver. För den här metoden kan du läsa översiktsavsnittet DefaultAzureCredential.
  • "Bygg upp" en kedja: Börja med en tom kedja och inkludera bara det du behöver. Den här metoden finns i översiktsavsnittet ChainedTokenCredential.

Översikt över DefaultAzureCredential

DefaultAzureCredential är en åsiktsbaserad, förkonfigurerad kedja med autentiseringsuppgifter. Den är utformad för att stödja många miljöer, tillsammans med de vanligaste autentiseringsflödena och utvecklarverktygen. I grafisk form ser den underliggande kedjan ut så här:

StandardazureCredential-autentiseringsflödesschema

Den ordning som DefaultAzureCredential autentiseringsförsöken följer.

Order Merit beskrivning Aktiverat som standard?
1 Miljö Läser en samling miljövariabler för att avgöra om ett programtjänsthuvudnamn (programanvändare) har konfigurerats för appen. I så fall DefaultAzureCredential använder du dessa värden för att autentisera appen till Azure. Den här metoden används oftast i servermiljöer men kan också användas när du utvecklar lokalt. Ja
2 Arbetsbelastningsidentitet Om appen distribueras till en Azure-värd med arbetsbelastningsidentitet aktiverad autentiserar du kontot. Ja
3 Hanterad identitet Om appen distribueras till en Azure-värd med hanterad identitet aktiverad autentiserar du appen till Azure med hjälp av den hanterade identiteten. Ja
4 Visual Studio Om utvecklaren autentiserades till Azure genom att logga in på Visual Studio autentiserar du appen till Azure med samma konto. Ja
5 Azure CLI Om utvecklaren autentiserade till Azure med hjälp av Azure CLI:s az login kommando autentiserar du appen till Azure med samma konto. Ja
6 Azure PowerShell Om utvecklaren autentiserade till Azure med hjälp av Azure PowerShells Connect-AzAccount cmdlet autentiserar du appen till Azure med samma konto. Ja
7 Azure Developer CLI Om utvecklaren autentiserade till Azure med hjälp av Azure Developer CLI:s azd auth login kommando autentiserar du med det kontot. Ja
8 Interaktiv webbläsare Om det är aktiverat autentiserar du utvecklaren interaktivt via det aktuella systemets standardwebbläsare. Nej

I sin enklaste form kan du använda den parameterlösa versionen av DefaultAzureCredential på följande sätt:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

Dricks

Metoden UseCredential i föregående kodfragment rekommenderas för användning i ASP.NET Core-appar. Mer information finns i Använda Azure SDK för .NET i ASP.NET Core-appar.

Så här anpassar du DefaultAzureCredential

Om du vill ta bort en autentiseringsuppgift från DefaultAzureCredentialanvänder du motsvarande Exclude-prefixed-egenskap i DefaultAzureCredentialOptions. Till exempel:

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,
        }));
});

I föregående kodexempel EnvironmentCredential tas och WorkloadIdentityCredential tas bort från autentiseringskedjan. Därför är ManagedIdentityCredentialden första autentiseringsuppgiften som ska försökas . Den ändrade kedjan ser ut så här:

StandardazureCredential med hjälp av exkluderingsegenskaper

Kommentar

InteractiveBrowserCredential exkluderas som standard och visas därför inte i föregående diagram. Om du vill inkludera InteractiveBrowserCredentialskickar true du antingen till konstruktorn DefaultAzureCredential(Boolean) eller anger egenskapen DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential till false.

Eftersom fler Excludeprefixade egenskaper anges till true (undantag för autentiseringsuppgifter har konfigurerats) minskar fördelarna med att använda DefaultAzureCredential . I sådana fall ChainedTokenCredential är ett bättre val och kräver mindre kod. För att illustrera fungerar dessa två kodexempel på samma sätt:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeAzureCliCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ManagedIdentityClientId = userAssignedClientId
    });

Översikt över ChainedTokenCredential

ChainedTokenCredential är en tom kedja som du lägger till autentiseringsuppgifter till för att passa appens behov. Till exempel:

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()));
});

Föregående kodexempel skapar en anpassad autentiseringskedja som består av två autentiseringsuppgifter. Den användartilldelade hanterade identitetsvarianten för ManagedIdentityCredential görs först, följt av VisualStudioCredential, om det behövs. I grafisk form ser kedjan ut så här:

ChainedTokenCredential

Dricks

Optimera ordning ChainedTokenCredential på autentiseringsuppgifter för produktionsmiljön för bättre prestanda. Autentiseringsuppgifter som är avsedda att användas i den lokala utvecklingsmiljön bör läggas till sist.

Användningsvägledning för DefaultAzureCredential

DefaultAzureCredential är utan tvekan det enklaste sättet att komma igång med Azure Identity-biblioteket, men med den bekvämligheten kommer kompromisser. När du har distribuerat din app till Azure bör du förstå appens autentiseringskrav. Därför bör du överväga att flytta från DefaultAzureCredential till någon av följande lösningar:

  • En specifik TokenCredential implementering, till exempel ManagedIdentityCredential. Se listan Härledd för alternativ.
  • En avskalad implementering optimerad för Azure-miljön ChainedTokenCredential där appen körs.

Här är varför:

  • Felsökningsutmaningar: När autentiseringen misslyckas kan det vara svårt att felsöka och identifiera de felaktiga autentiseringsuppgifterna. Du måste aktivera loggning för att se förloppet från en autentiseringsuppgift till nästa och statusen för lyckade/misslyckade för var och en. Mer information finns i Felsöka en länkad autentiseringsuppgift.
  • Prestandakostnader: Processen med att sekventiellt prova flera autentiseringsuppgifter kan medföra prestandakostnader. När den till exempel körs på en lokal utvecklingsdator är den hanterade identiteten inte tillgänglig. Därför ManagedIdentityCredential misslyckas alltid i den lokala utvecklingsmiljön, såvida den inte uttryckligen inaktiveras via motsvarande Excludeprefixegenskap.
  • Oförutsägbart beteende: DefaultAzureCredential söker efter förekomsten av vissa miljövariabler. Det är möjligt att någon kan lägga till eller ändra dessa miljövariabler på systemnivå på värddatorn. Dessa ändringar gäller globalt och ändrar därför beteendet DefaultAzureCredential för vid körning i alla appar som körs på den datorn.

Felsöka en länkad autentiseringsuppgift

Om du vill diagnostisera ett oväntat problem eller förstå vad en länkad autentiseringsuppgift gör aktiverar du loggning i din app. Du kan också filtrera loggarna till endast de händelser som genereras från Azure Identity-biblioteket. Till exempel:

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

I illustrationssyfte förutsätter vi att den parameterlösa formen av DefaultAzureCredential användes för att autentisera en begäran till en Log Analytics-arbetsyta. Appen kördes i den lokala utvecklingsmiljön och Visual Studio autentiserades till ett Azure-konto. Nästa gång appen kördes visas följande relevanta poster i utdata:

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

Observera följande i föregående utdata:

  • EnvironmentCredential, WorkloadIdentityCredentialoch ManagedIdentityCredential kunde inte hämta en Microsoft Entra-åtkomsttoken i den ordningen.
  • Posten DefaultAzureCredential credential selected:-prefix anger den valda autentiseringsuppgiften iVisualStudioCredential det här fallet. Sedan VisualStudioCredential det lyckades användes inga autentiseringsuppgifter utöver det.