Łańcuchy poświadczeń w bibliotece tożsamości platformy Azure dla platformy .NET

Artykuł
11/16/2024

Biblioteka tożsamości platformy Azure udostępnia poświadczenia — klasy publiczne pochodzące z klasy TokenCredential biblioteki Azure Core. Poświadczenie reprezentuje odrębny przepływ uwierzytelniania na potrzeby uzyskiwania tokenu dostępu z identyfikatora Entra firmy Microsoft. Te poświadczenia można połączyć w łańcuch, aby utworzyć uporządkowaną sekwencję mechanizmów uwierzytelniania, które mają być podejmowane.

Jak działa poświadczenie łańcuchowe

W czasie wykonywania łańcuch poświadczeń próbuje uwierzytelnić się przy użyciu pierwszego poświadczenia sekwencji. Jeśli to poświadczenie nie może uzyskać tokenu dostępu, zostanie podjęta próba następnego poświadczenia w sekwencji itd., dopóki token dostępu nie zostanie pomyślnie uzyskany. Poniższy diagram sekwencji ilustruje to zachowanie:

Diagram sekwencji łańcuchów poświadczeń

Dlaczego warto używać łańcuchów poświadczeń

Poświadczenie łańcuchowe może oferować następujące korzyści:

Świadomość środowiska: automatycznie wybiera najbardziej odpowiednie poświadczenia na podstawie środowiska, w którym działa aplikacja. Bez niego musisz napisać kod podobny do następującego:

TokenCredential credential;

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

Bezproblemowe przejścia: Aplikacja może przejść z lokalnego programowania do środowiska przejściowego lub produkcyjnego bez zmiany kodu uwierzytelniania.
Ulepszona odporność: obejmuje mechanizm rezerwowy, który przechodzi do następnego poświadczenia, gdy poprzednia próba uzyskania tokenu dostępu zakończy się niepowodzeniem.

Jak wybrać poświadczenie łańcuchowe

Istnieją dwie różne filozofie tworzenia łańcuchów poświadczeń:

"Rozerwanie" łańcucha: Zacznij od wstępnie skonfigurowanego łańcucha i wyklucz to, czego nie potrzebujesz. W przypadku tego podejścia zobacz sekcję Omówienie domyślneAzureCredential.
"Utwórz" łańcuch: zacznij od pustego łańcucha i uwzględnij tylko potrzebne elementy. Aby uzyskać to podejście, zobacz sekcję ChainedTokenCredential overview (Omówienie elementu ChainedTokenCredential).

Omówienie domyślneAzureCredential

DefaultAzureCredential jest wstępnie skonfigurowanym łańcuchem poświadczeń. Jest ona przeznaczona do obsługi wielu środowisk wraz z najczęściej używanymi przepływami uwierzytelniania i narzędziami deweloperskich. W postaci graficznej podstawowy łańcuch wygląda następująco:

Domyślny schemat blokowy uwierzytelnianiaAzureCredential

Kolejność, w której DefaultAzureCredential następuje próba wykonania poświadczeń.

Zamówienie	Referencje	opis	Włączone domyślnie?
1	Środowisko	Odczytuje kolekcję zmiennych środowiskowych, aby określić, czy dla aplikacji skonfigurowano jednostkę usługi aplikacji (użytkownika aplikacji). Jeśli tak, `DefaultAzureCredential` użyj tych wartości do uwierzytelniania aplikacji na platformie Azure. Ta metoda jest najczęściej używana w środowiskach serwera, ale może być również używana podczas opracowywania lokalnie.	Tak
2	Tożsamość obciążenia	Jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością obciążenia, uwierzytelnij to konto.	Tak
3	Tożsamość zarządzana	Jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością zarządzaną, uwierzytelnij aplikację na platformie Azure przy użyciu tej tożsamości zarządzanej.	Tak
100	Program Visual Studio	Jeśli deweloper uwierzytelniony na platformie Azure, logując się do programu Visual Studio, uwierzytelniaj aplikację na platformie Azure przy użyciu tego samego konta.	Tak
5	Interfejs wiersza polecenia platformy Azure	Jeśli deweloper uwierzytelniony na platformie Azure przy użyciu polecenia interfejsu `az login` wiersza polecenia platformy Azure, uwierzytelnij aplikację na platformie Azure przy użyciu tego samego konta.	Tak
6	Azure PowerShell	Jeśli deweloper uwierzytelnił się na platformie Azure przy użyciu polecenia cmdlet programu Azure PowerShell `Connect-AzAccount` , uwierzytelnij aplikację na platformie Azure przy użyciu tego samego konta.	Tak
7	Interfejs wiersza polecenia dla deweloperów platformy Azure	Jeśli deweloper uwierzytelniony na platformie Azure przy użyciu polecenia interfejsu `azd auth login` wiersza polecenia dla deweloperów platformy Azure, uwierzytelnij się przy użyciu tego konta.	Tak
8	Przeglądarka interaktywna	Jeśli to ustawienie jest włączone, interakcyjne uwierzytelnianie dewelopera za pośrednictwem domyślnej przeglądarki bieżącego systemu.	Nie.

W najprostszej formie można użyć bez parametrów DefaultAzureCredential wersji w następujący sposób:

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

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

Napiwek

Metoda w poprzednim fragmencie kodu jest zalecana UseCredential do użycia w aplikacjach ASP.NET Core. Aby uzyskać więcej informacji, zobacz Use the Azure SDK for .NET in ASP.NET Core apps (Używanie zestawu Azure SDK dla platformy .NET w aplikacjach platformy ASP.NET Core).

Jak dostosować wartość domyślnąAzureCredential

Aby usunąć poświadczenie z DefaultAzureCredentialklasy , użyj odpowiedniej Excludewłaściwości -prefiksed w obszarze DefaultAzureCredentialOptions. Na przykład:

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

W poprzednim przykładzie EnvironmentCredential kodu i WorkloadIdentityCredential są usuwane z łańcucha poświadczeń. W związku z tym pierwsze poświadczenie do podjęcia próby to ManagedIdentityCredential. Zmodyfikowany łańcuch wygląda następująco:

Ustawienie domyślneAzureCredential przy użyciu właściwości Wyklucza

Uwaga

InteractiveBrowserCredential jest domyślnie wykluczony i dlatego nie jest wyświetlany na powyższym diagramie. Aby dołączyć InteractiveBrowserCredentialelement , przekaż true do konstruktora DefaultAzureCredential(Boolean) lub ustaw właściwość DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential na false.

W miarę ustawiania większej Excludeliczby właściwości prefiksów na true wartość (skonfigurowane są wykluczenia poświadczeń), korzyści wynikające z używania DefaultAzureCredential maleją. W takich przypadkach ChainedTokenCredential jest lepszym wyborem i wymaga mniej kodu. Aby zilustrować, te dwa przykłady kodu zachowują się tak samo:

Wartość domyślnaAzureCredential
ChainedTokenCredential

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

credential = new ChainedTokenCredential(
    new ManagedIdentityCredential(clientId: userAssignedClientId),
    new VisualStudioCredential());

ChainedTokenCredential — omówienie

ChainedTokenCredential to pusty łańcuch, do którego dodasz poświadczenia zgodnie z potrzebami aplikacji. Na przykład:

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

Powyższy przykładowy kod tworzy dostosowany łańcuch poświadczeń składający się z dwóch poświadczeń. Wariant tożsamości zarządzanej przypisanej ManagedIdentityCredential przez użytkownika jest najpierw podejmowany, a następnie VisualStudioCredential, w razie potrzeby. W formie graficznej łańcuch wygląda następująco:

ChainedTokenCredential

Napiwek

Aby uzyskać lepszą wydajność, zoptymalizuj kolejność poświadczeń w ChainedTokenCredential środowisku produkcyjnym. Poświadczenia przeznaczone do użytku w lokalnym środowisku programistycznym powinny zostać dodane ostatnio.

Wskazówki dotyczące użycia elementu DefaultAzureCredential

DefaultAzureCredential jest niewątpliwie najprostszym sposobem rozpoczęcia pracy z biblioteką tożsamości platformy Azure, ale z tym wygodą są kompromisy. Po wdrożeniu aplikacji na platformie Azure należy zrozumieć wymagania dotyczące uwierzytelniania aplikacji. Z tego powodu zdecydowanie rozważ przejście z jednego z DefaultAzureCredential następujących rozwiązań:

TokenCredential Konkretna implementacja, taka jak ManagedIdentityCredential. Zobacz listę pochodną, aby uzyskać opcje.
Implementacja pared-down ChainedTokenCredential zoptymalizowana pod kątem środowiska platformy Azure, w którym działa aplikacja.

Poniżej przedstawiono przyczyny:

Wyzwania związane z debugowaniem: w przypadku niepowodzenia uwierzytelniania może być trudne debugowanie i identyfikowanie obraźliwych poświadczeń. Należy włączyć rejestrowanie, aby zobaczyć postęp z jednego poświadczenia do następnego i stan powodzenia/niepowodzenia każdego z nich. Aby uzyskać więcej informacji, zobacz Debugowanie poświadczeń łańcuchowych.
Obciążenie związane z wydajnością: proces sekwencyjnie próbujący uzyskać wiele poświadczeń może wprowadzić obciążenie związane z wydajnością. Na przykład w przypadku uruchamiania na lokalnym komputerze deweloperskim tożsamość zarządzana jest niedostępna. ManagedIdentityCredential W związku z tym zawsze kończy się niepowodzeniem w lokalnym środowisku projektowym, chyba że jawnie wyłączone za pośrednictwem odpowiedniej Excludewłaściwości -prefiksed.
Nieprzewidywalne zachowanie: DefaultAzureCredential sprawdza obecność określonych zmiennych środowiskowych. Możliwe, że ktoś może dodać lub zmodyfikować te zmienne środowiskowe na poziomie systemu na maszynie hosta. Te zmiany są stosowane globalnie i w związku z tym zmieniają zachowanie DefaultAzureCredential środowiska uruchomieniowego w dowolnej aplikacji uruchomionej na tym komputerze.

Debugowanie poświadczeń łańcuchowych

Aby zdiagnozować nieoczekiwany problem lub zrozumieć, co robi łańcuchowe poświadczenia, włącz rejestrowanie w aplikacji. Opcjonalnie przefiltruj dzienniki tylko do tych zdarzeń emitowanych z biblioteki tożsamości platformy Azure. Na przykład:

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

W celach ilustracyjnych załóżmy, że forma bez parametrów DefaultAzureCredential została użyta do uwierzytelniania żądania w obszarze roboczym usługi Log Analytics. Aplikacja została uruchomiona w lokalnym środowisku projektowym, a program Visual Studio został uwierzytelniony na koncie platformy Azure. Przy następnym uruchomieniu aplikacji w danych wyjściowych pojawią się następujące istotne wpisy:

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

W poprzednich danych wyjściowych zwróć uwagę, że:

EnvironmentCredential, WorkloadIdentityCredentiali ManagedIdentityCredential każdy z nich nie może uzyskać tokenu dostępu firmy Microsoft Entra w tej kolejności.
Wpis DefaultAzureCredential credential selected:-prefiksed wskazuje poświadczenie, które zostało wybrane —VisualStudioCredential w tym przypadku. Ponieważ VisualStudioCredential zakończyło się pomyślnie, nie były używane żadne poświadczenia poza nim.

Udostępnij za pośrednictwem